Db Profiler Laravel Package

Getting Started

• Install as a dev-only dependency so it never reaches production autoloading: composer require illuminated/db-profiler --dev. The MIT license and active release cadence make it safe to keep in require-dev.
• Laravel package discovery registers the service provider automatically. If you are on an older Laravel or have discovery disabled, add the provider manually in config/app.php — check the README for the exact class name for your version.
• Publish the config and read it before doing anything else: php artisan vendor:publish --tag=db-profiler-config (or publish by provider). This is the first place to look — it defines whether profiling is enabled, which middleware injects the toolbar, and which collectors run.
• Enable it only for local/staging via .env:

  DB_PROFILER_ENABLED=true
  

  Keep it false in .env.example and in any shared environment file.
• First use case: load a page that performs several queries (a dashboard or index listing), then open the profiler bar rendered at the bottom of the HTML response. The panel shows the query list, execution time, and duplicate/slow query flags. That is the entire day-to-day workflow: click through the app, watch the bar, fix queries.
• For console, enable the same flag and run an Artisan command. The profiler reports the collected queries after the command finishes, which is the fastest way to inspect a backfill or import job.

Implementation Patterns

• Environment-scoped enablement. Drive the enabled flag from an env var (DB_PROFILER_ENABLED) rather than editing the config file, so every developer opts in locally without touching tracked files. Pair it with APP_DEBUG=true assumptions in your docs.
• Middleware injection for HTTP. The toolbar is appended to HTML responses by the package middleware. If your app uses a custom middleware stack or a non-standard kernel, confirm the middleware is registered in the web group (or wherever the config expects it). API-only apps should skip HTTP profiling entirely and use console mode.
• Targeted profiling during a refactor. When optimizing an N+1, keep the profiler on, load the slow page, and use the duplicate-query grouping to identify the relationship that is looping. Fix, reload, compare query count and total time in the bar. This is the core loop.
• Console profiling for jobs and commands. Run the command with the flag enabled and read the post-command summary. This is more practical than HTTP profiling for importers, schedulers, and one-off scripts, because the output is not truncated by a page render.
• Use it as a lightweight Telescope substitute. If you only need query visibility and do not want Telescope's storage tables or full event collection, this package gives you the query panel with far less setup. If you later need views, events, or cache inspection, switch to Telescope or Debugbar.
• Pair with Laravel's own tooling for assertions. Do not use this package in tests. For test assertions use DB::listen/DB::enableQueryLog() and assert on query counts directly; the profiler is an interactive tool, not an assertion library.
• Runtime toggling for a single request. If the config supports runtime enablement, flip the flag in a service provider or middleware for one route instead of enabling globally on a busy local app. Otherwise keep global enablement and accept the overhead.
• Do not run it alongside Laravel Debugbar's query collector. Two DB::listen collectors double the overhead and produce confusing duplicate counts. Pick one per environment.

Gotchas and Tips

• Never enable in production. The toolbar renders raw SQL and bindings into the response, which can leak data. Guard with both APP_ENV and the explicit env flag; also ensure deployments run composer install --no-dev so the package is not even present.
• Config caching silently disables it. If php artisan config:cache has run locally, changes to .env or the config file have no effect. Run php artisan config:clear after toggling.
• Memory growth in long-running processes. Query collection accumulates in memory. Do not enable it for queue workers or under Octane/RoadRunner where the process persists across requests; disable it or reset state between requests.
• Toolbar injection can corrupt responses. Streamed responses, file downloads, and responses with strict Content-Length headers may break if the toolbar is appended. Verify behavior on download and export routes; disable the middleware there if needed.
• JSON and API responses. The web toolbar only makes sense for HTML. For JSON endpoints, rely on console profiling or a temporary DB::listen dump instead of expecting the bar to appear.
• Duplicate detection is binding-insensitive by design. Two queries with the same SQL shape but different bindings may be grouped or may look identical. Always inspect the bindings before concluding a query is truly duplicated.
• Slow-query thresholds are profiler-local. The "slow" badge uses the package config, not MySQL's long_query_time. Tune the threshold in the config to match your app's expectations, and do not treat the profiler's judgment as authoritative for production performance work.
• Pin the version. The package is actively released; lock a known-good version in composer.json and upgrade deliberately, since internal collector behavior and config keys can change between minors.
• Check Laravel/PHP constraints before adopting. Confirm the composer require block matches your framework version; older Laravel releases may need an earlier package tag.
• Extension point: if the built-in panel is not enough, wrap the package's collector or add your own DB::listen callback in a service provider to log queries to a file — the profiler's config is the easiest place to see how it hooks in.