blissjaspis/laravel-query-detector

Laravel N+1 Query Detector

The Laravel N+1 query detector helps you improve application performance by spotting relation queries that should be eager loaded. It monitors queries in real time during development and notifies you when an N+1 pattern is detected.

History

This repository is a fork of beyondcode/laravel-query-detector. The original package was not updated for newer Laravel releases, so this fork keeps the tool compatible with current Laravel versions.

Compatibility

Version 2.x (current)

Latest release: 2.1.0. Compatible with Laravel 12 and above (PHP 8.2+).

Version 1.x

For Laravel 11 and below:

composer require blissjaspis/laravel-query-detector:^1.0 --dev

Installation

Install as a development dependency:

composer require blissjaspis/laravel-query-detector --dev

The service provider is registered automatically.

Publish configuration (optional):

php artisan vendor:publish --provider="BlissJaspis\QueryDetector\QueryDetectorServiceProvider"

Usage

When APP_DEBUG=true (and QUERY_DETECTOR_ENABLED is not set to false), detection runs automatically on HTTP requests. No extra setup is required.

Configuration

Environment variables:

• QUERY_DETECTOR_ENABLED
• QUERY_DETECTOR_THRESHOLD
• QUERY_DETECTOR_LOG_CHANNEL

Output drivers

Configure output in config/querydetector.php:

Optional integrations are listed under composer suggest.

Custom handling

Listen for BlissJaspis\QueryDetector\Events\QueryDetected to send notifications (Sentry, Slack, etc.):

use BlissJaspis\QueryDetector\Events\QueryDetected;

Event::listen(QueryDetected::class, function (QueryDetected $event) {
    foreach ($event->getQueries() as $query) {
        // $query['model'], $query['relation'], $query['relatedModel'], $query['count'], ...
    }
});

The event is dispatched once per HTTP request when issues are found.

Scope and limitations

• Detection runs on HTTP requests via global middleware. No manual middleware registration is required—the service provider registers it automatically.
• Artisan commands, queue jobs, and schedulers are not covered unless you wrap them manually in local dev (see usage — Beyond HTTP).
• Inertia / SPA: prefer Log + Json output; Alert only helps on full HTML page loads (usage — SPA and Inertia).
• Intended for local/staging development only; keep it as a --dev dependency.
• For Octane and other long-lived workers, the detector resets its state between requests but keeps a single DB::listen registration per worker process.

More detail: docs/usage.md.

Package internals and class responsibilities: docs/architecture.md.

Development

composer install
composer test      # Run tests
composer lint      # Pint (dry-run) + PHPStan
composer format    # Apply Pint fixes
composer analyse   # PHPStan only

Testing

composer test

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING.

Security

Report security issues to bliss@jaspis.me instead of using the public issue tracker.

Credits

• Bliss Jaspis
• Marcel Pociot
• All Contributors

License

The MIT License (MIT). See LICENSE.