Download the PHP package tokkerbaz/phpsql-lint without Composer

phpsql-lint

A rule-based SQL linter, EXPLAIN-aware analyzer, and query log collector for PHP.

What this is

• A static SQL linter — a pluggable set of rules that catch known anti-patterns (SELECT *, unconditional UPDATE/DELETE, leading-wildcard LIKE, unbounded IN (...) lists, and more) without touching a database.
• An EXPLAIN-aware analyzer — runs EXPLAIN against MySQL or Postgres and normalizes the output so rules can reason about real access paths (full scans, filesort, temp tables, estimated row counts) instead of guessing.
• A query log collector — a framework-agnostic recorder you can wire into any PDO-based app to capture queries per request and detect N+1 patterns by grouping structurally identical queries.
• A page/request debugger — a drop-in TrackedPdo that auto-records every query, plus a PageDebugger that runs the linter and N+1 detection across an entire request and renders a self-contained HTML debug panel (or exposes the raw data if you want to build your own view).
• Optional Laravel auto-discovery — if Laravel is present, a service provider wires itself up automatically (query recording + the debug panel); everything else works identically in plain PHP with zero Laravel dependency.

What this is not

This is not a query optimizer. It does not have a cost model, does not know your table statistics or index cardinality, and does not rewrite your schema. Real query planners (MySQL's, Postgres's) already do that, with far more information than a static tool ever will. What this package does is surface known anti-patterns and real EXPLAIN output so a human can make an informed decision. Every suggested fix is a suggestion — nothing here mutates your schema or your queries automatically.

Install

Quick start — static linting

EXPLAIN-aware analysis

N+1 detection from a live request

Laravel integration (optional, zero-config)

If Laravel is present, package auto-discovery registers PhpSqlLintServiceProvider automatically — you don't need to touch config/app.php. The Laravel-specific code lives entirely under PhpSqlLint\Laravel\* and is never loaded for plain PHP projects; the core package (Analyzer, Rules, Collector, Debugger) has no dependency on Illuminate at all.

Then in .env:

That's it. With enabled=true and APP_ENV in the configured environments list (local by default — see config/phpsql-lint.php), the provider:

1. Hooks DB::listen() to record every query Laravel runs (this is the idiomatic Laravel integration point — TrackedPdo below is for plain PHP, since Laravel manages its own PDO connections internally).
2. Pushes RenderDebugPanel middleware onto the web group, which appends the floating debug panel to any HTML response.

Set render_panel to false in the published config if you'd rather query PageDebugger yourself (e.g. to log findings to your APM instead of rendering the HTML panel):

Note on test coverage: the Laravel provider and middleware are exercised manually but don't yet have an automated test suite (that would mean pulling in Orchestra Testbench) — worth flagging honestly rather than implying full coverage. The framework-agnostic core (rules, analyzer, collector, debugger) does have full unit test coverage; see tests/.

Always gate this to non-production environments — the panel and the DB::listen hook expose raw SQL and bindings, which you don't want on production traffic regardless of the enabled flag's default.

Debugging a whole page/request (plain PHP)

TrackedPdo is a drop-in PDO subclass that records every query automatically — no manual ->record() calls. PageDebugger then runs the static rule set and N+1 detection against everything that ran, and can render a floating HTML debug panel, similar in spirit to Symfony's profiler toolbar or Laravel Debugbar, but scoped to what this package checks (findings, N+1, timings).

The panel shows, per page load: total query count and time, every static-rule finding, any N+1 groups it caught, and the full query list with per-query timing and call site. It's entirely self-contained (inline CSS/JS, no CDN dependency) so it works even if the page's own asset pipeline is broken.

PageDebugger also exposes the underlying data if you'd rather build your own UI or feed it into logging/APM instead of the HTML panel:

Built-in rules

Writing a custom rule

Every rule implements a small interface, so adding your own is straightforward:

Register it with $analyzer->addRule(new NoOrderByRandRule()).

Development

License

MIT — see LICENSE.