Weave Code
Laravel Query Detector Laravel Package
beyondcode/laravel-query-detector
Laravel N+1 Query Detector monitors your queries in real-time while you develop, alerting you whenever you should add eager loading to fix N+1 queries. Install it as a dev dependency via Composer; it auto-registers and helps boost your app's performance.
Laravel N+1 Query Detector is a development-time package that helps you improve your application's performance by reducing the number of database queries it executes. It monitors queries in real-time as you use your application and alerts you whenever it detects N+1 queries, so you know exactly where to add eager loading.
- Real-time query monitoring while developing
- Instant alerts when N+1 queries are detected
- Suggests adding eager loading to fix performance issues
- Zero-configuration setup via auto-registration
- Installs easily with Composer as a dev dependency
Perfect for catching hidden performance bottlenecks before they reach production.
Frequently asked questions about Laravel Query Detector
- What is beyondcode/laravel-query-detector used for?
- It is a development-time Laravel package that monitors the queries executed during a request and alerts you when a relationship query repeats beyond a configured threshold. It helps you spot missing eager loading and eliminate N+1 queries. It is installed as a dev dependency and adds no production runtime layer.
- How do I install beyondcode/laravel-query-detector?
- Run composer require beyondcode/laravel-query-detector --dev. The package auto-registers its service provider through Laravel package discovery. No further setup is needed for the default behavior in a local environment with APP_DEBUG enabled.
- Does laravel-query-detector run in production?
- It is intended for development and debugging, not production. The package is a dev dependency and activates based on your debug configuration; with enabled left null it follows APP_DEBUG. Pin enabled explicitly rather than inheriting the value so diagnostics cannot leak into shared staging or API responses.
- Which Laravel versions does laravel-query-detector support?
- The package targets modern Laravel applications, with tagged releases covering Laravel 8 through 13 according to its recent support history. Major Laravel upgrades have sometimes required a new package release to restore compatibility. Check the latest tagged release against your framework version before adopting it.
- How do I change the N+1 query detection threshold?
- The package exposes a small config file with a threshold setting. A threshold of 1 flags any relationship query executed more than once, which is intentionally sensitive. Raise the threshold to reduce noise from legitimate loops over small collections, and review the value as part of your team's debugging policy.
- What output channels does laravel-query-detector support?
- It supports pluggable outputs including Log, Console, Alert, Json, Debugbar, and Clockwork. This lets the same detection signal appear in the browser, application logs, or an existing observability stack. Be careful with Json and Alert outputs because they can mutate the HTTP response, so keep them out of shared environments.
- How do I suppress false positives in laravel-query-detector?
- Use the except configuration to whitelist specific model-to-relation combinations that are known to be safe. This is useful for cached collections or intentionally repeated relation loads. The whitelist needs an owner and periodic review because stale entries can silently hide real N+1 problems.
- Can I listen to the QueryDetected event for CI or monitoring?
- Yes. The package dispatches a QueryDetected event, which is the main extension point for programmatic use. You can listen for it and send a Sentry or Bugsnag breadcrumb, a Slack notification, a CI artifact, or a custom Datadog metric. That turns the detector from a developer-only tool into a signal your pipeline can consume.
- Does laravel-query-detector work with Lumen?
- Lumen requires manual service provider registration and a hand-copied configuration file because it does not use the same package auto-discovery flow as Laravel. It is still usable, but the setup friction is higher. This matters mainly for legacy Lumen estates rather than new Laravel applications.
- Is laravel-query-detector a replacement for Laravel Telescope or Debugbar?
- No, it overlaps with them rather than replacing them. Telescope and Debugbar provide broad request and query inspection, while this package focuses narrowly on repeated relation queries and N+1 patterns. If you already have Telescope or an APM with per-query span attribution, the marginal value may be low.
Weaver
How can I help you explore Laravel packages today?