PHPackages                             qdenka/laravel-query-doctor - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. qdenka/laravel-query-doctor

ActiveLibrary[Database & ORM](/categories/database)

qdenka/laravel-query-doctor
===========================

Detect N+1 queries, missing indexes, and slow queries in your Laravel app before they reach production.

v0.1.3(3mo ago)06MITPHPPHP ^8.2CI passing

Since Feb 15Pushed 3mo agoCompare

[ Source](https://github.com/QDenka/laravel-query-doctor)[ Packagist](https://packagist.org/packages/qdenka/laravel-query-doctor)[ RSS](/packages/qdenka-laravel-query-doctor/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (9)Versions (5)Used By (0)

Laravel Query Doctor
====================

[](#laravel-query-doctor)

[![CI](https://github.com/QDenka/laravel-query-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/QDenka/laravel-query-doctor/actions)[![Latest Version](https://camo.githubusercontent.com/77dddb978fe5c039396194de90bdd6673baffd64c4d20934d6349e0818205b14/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7164656e6b612f6c61726176656c2d71756572792d646f63746f722e737667)](https://packagist.org/packages/qdenka/laravel-query-doctor)[![License](https://camo.githubusercontent.com/be80e900fdf3102da68978d5d87944332284c98e0a368a0c215db3a11777b8da/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f5144656e6b612f6c61726176656c2d71756572792d646f63746f722e737667)](LICENSE)

Detect N+1 queries, missing indexes, and slow queries in your Laravel app before they reach production.

- **Catches 5 types of problems**: N+1, duplicate queries, slow queries, missing indexes, unnecessary `SELECT *`.
- **Works in dev and CI**: Web dashboard for browsing, CLI commands for reporting, exit codes for CI pipelines.
- **Zero config to start**: Install, open `/query-doctor`, see results.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 10, 11, or 12
- SQLite PHP extension (included in most PHP installations)

Installation
------------

[](#installation)

```
composer require --dev qdenka/laravel-query-doctor
php artisan vendor:publish --tag=query-doctor-config
```

That's it. The package auto-discovers and starts capturing queries.

Quick Start
-----------

[](#quick-start)

1. Install the package (see above).
2. Browse your app — make some requests, trigger some pages.
3. Open `/query-doctor` in your browser.

Or generate a report from the command line:

```
php artisan doctor:report
```

CLI Commands
------------

[](#cli-commands)

CommandDescription`php artisan doctor:report`Show detected issues`php artisan doctor:report --format=json`Output as JSON`php artisan doctor:report --format=md --output=report.md`Save markdown report to file`php artisan doctor:baseline`Snapshot current issues as baseline`php artisan doctor:baseline --clear`Remove the baseline`php artisan doctor:ci-report --fail-on=high`CI mode: exit 1 if high+ severity issues exist`php artisan doctor:ci-report --baseline`CI mode: exclude baselined issues### CI Integration

[](#ci-integration)

```
# .github/workflows/ci.yml
- name: Run tests
  run: vendor/bin/phpunit

- name: Check query performance
  run: php artisan doctor:ci-report --fail-on=high --output=report.md

- name: Upload report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: query-doctor-report
    path: report.md
```

Configuration
-------------

[](#configuration)

Publish and edit the config file:

```
php artisan vendor:publish --tag=query-doctor-config
```

Key options:

```
// config/query-doctor.php
return [
    'enabled' => env('QUERY_DOCTOR_ENABLED', true),
    'allowed_environments' => ['local', 'staging'],

    'analyzers' => [
        'n_plus_one' => ['min_repetitions' => 5],
        'slow' => ['threshold_ms' => 100],
        'duplicate' => ['min_count' => 3],
    ],
];
```

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the full reference.

Dashboard
---------

[](#dashboard)

The web dashboard is available at `/query-doctor` (only in allowed environments).

It shows:

- Issues grouped by severity
- Slow queries with timing details
- N+1 candidates with query counts
- Filters by period, route, severity, and type

Security
--------

[](#security)

Query bindings are sanitized before storage:

- **Column-based masking**: Bindings for columns like `password`, `token`, `api_key` are replaced with `[MASKED]`.
- **Pattern-based masking**: Strings matching email, phone, or SSN patterns are masked regardless of column.
- **Hash-only storage**: Bindings are stored as SHA-256 hashes for duplicate detection, not raw values.

You can add your own columns and patterns in the config:

```
'masking' => [
    'columns' => ['password', 'secret', 'token', 'date_of_birth'],
    'value_patterns' => ['/^[A-Z]{2}\d{6}$/'],  // passport numbers
],
```

How It Works
------------

[](#how-it-works)

1. The package hooks into Laravel's `DB::listen()` to capture every SQL query.
2. Queries are fingerprinted (normalized) to group structurally identical queries.
3. Five analyzers run against captured queries to detect problems.
4. Results are stored in a dedicated SQLite file (separate from your app's database).
5. You view results via the dashboard, CLI, or exported reports.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture overview.

Extending
---------

[](#extending)

Add custom analyzers:

```
use QDenka\QueryDoctor\Domain\Contracts\AnalyzerInterface;

final class MyCustomAnalyzer implements AnalyzerInterface
{
    public function analyze(array $events): array { /* ... */ }
    public function type(): IssueType { /* ... */ }
}
```

See [docs/EXTENSION\_API.md](docs/EXTENSION_API.md) for details on custom analyzers, reporters, and event hooks.

Contributing
------------

[](#contributing)

See [CONTRIBUTING.md](.github/CONTRIBUTING.md).

License
-------

[](#license)

MIT. See [LICENSE](LICENSE).

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance82

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

92d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3339fb58d7742b5f4ce6a647b09c74739d28b9ecfc85ffb5de6d2f04b6985b82?d=identicon)[qdenka](/maintainers/qdenka)

---

Top Contributors

[![QDenka](https://avatars.githubusercontent.com/u/77678360?v=4)](https://github.com/QDenka "QDenka (58 commits)")

---

Tags

laravelperformanceprofilingsqlquerydiagnosticsn-plus-one

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/qdenka-laravel-query-doctor/health.svg)

```
[![Health](https://phpackages.com/badges/qdenka-laravel-query-doctor/health.svg)](https://phpackages.com/packages/qdenka-laravel-query-doctor)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k25.9M107](/packages/laravel-cashier)[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[illuminated/db-profiler

Database Profiler for Laravel Web and Console Applications.

168237.4k](/packages/illuminated-db-profiler)[sarfraznawaz2005/indexer

Laravel package to monitor SELECT queries and offer best possible INDEX fields.

562.7k](/packages/sarfraznawaz2005-indexer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)