README

Find Doctrine ORM problems in the profiler. Catch them in CI.

Get started · Add it to CI · Browse analyzers

Doctrine Doctor adds Doctrine-focused feedback to the two places where it is most useful:

When you need an answer	Doctrine Doctor helps you
A page is slow	Inspect real queries, timings, and backtraces in the Web Profiler.
A change is ready for review	Check source code, mappings, and configuration in CI.
A database needs a closer look	Run an opt-in audit with `--with-database`.

Runtime context with the real CI result kept in view.

Catch issues in CI · Investigate them in the profiler

Choose your feedback loop

While you develop

Use the Web Profiler when a real page behaves badly. See the query, timing, pattern, and backtrace together while you still have the page open.

Best for: N+1 queries, slow SQL, repeated queries, and expensive hydration.

Before you merge

Run the static checks in CI so every pull request gets the same persistence review, even when no page has been exercised yet.

Best for: source code, mappings, configuration, and database-independent design issues.

What it catches

Doctrine Doctor ships with more than 100 analyzers grouped by the kind of decision they support:

Area	Examples
Performance	N+1 queries, missing indexes, slow queries, excessive hydration, unbounded reads, and inefficient joins
Security	DQL/SQL injection, unsafe QueryBuilder input, sensitive data exposure, and insecure randomness
Integrity	Cascade and orphan-removal issues, mapping mismatches, type errors, and invalid entity boundaries
Configuration	Charset, collation, timezone, strict mode, cache, and platform configuration

See the full analyzer catalog for the complete list.

Quick start

1. Install the bundle

composer require --dev ahmed-bhs/doctrine-doctor

2. Open a real page

The bundle is auto-configured through Symfony Flex. No YAML is needed for the first run.

3. Read the feedback

Refresh the page in the dev environment, open the Symfony Web Profiler, and select the Doctrine Doctor panel.

Add it to CI

Check your code and mappings on every pull request:

php bin/console doctrine:doctor:analyze --fail-on=warning

The command exits with a failure when it finds a warning or critical issue. Use --fail-on=critical to fail only on critical issues, --fail-on=info to fail on every finding, or --fail-on=never to report without failing. Live database audits are opt-in with --with-database.

See the profiler and CI checks guide for the full analyzer inventory and execution rules.

How the feedback flows

flowchart LR
    A[Pull request] --> B[Doctrine Doctor]
    B --> C{Finding?}
    C -->|No| D[Merge with confidence]
    C -->|Yes| E[Analyzer + location + next step]
    E --> F[Fix and push]
    F --> B

    classDef start fill:#dbeafe,stroke:#2563eb,color:#0f172a
    classDef check fill:#ede9fe,stroke:#7c3aed,color:#0f172a
    classDef finding fill:#fee2e2,stroke:#dc2626,color:#0f172a
    classDef done fill:#dcfce7,stroke:#16a34a,color:#0f172a
    class A start
    class B check
    class C,E finding
    class D done

Configuration (optional)

Configure thresholds in config/packages/dev/doctrine_doctor.yaml:

doctrine_doctor:
    analyzers:
        n_plus_one:
            threshold: 5  # default, lower to 3 to be stricter
        slow_query:
            threshold: 100  # milliseconds (default)

Enable backtraces to see WHERE in your code issues originate:

# config/packages/dev/doctrine.yaml
doctrine:
    dbal:
        profiling_collect_backtrace: true

Full configuration reference →

AI Mate / MCP integration (optional)

Doctrine Doctor can expose its profiler findings to AI assistants (Claude Code, Cursor, GitHub Copilot, …) over MCP through Symfony AI Mate. It registers an MCP tool, doctrine-doctor-issues, that reads a profiler request and returns the detected issues — already sanitized for safe AI consumption.

This is opt-in. The bundle ships the integration code but pulls no AI dependency by default. Without AI Mate installed, this does not apply and Doctrine Doctor runs exactly as before.

Setup guide & tool reference →

Example: N+1 Query Detection

Before — 100 queries After — 1 query

$users = $repository->findAll();

{% for user in users %}
    {{ user.profile.bio }}
{% endfor %}

$users = $repository
    ->createQueryBuilder('u')
    ->leftJoin('u.profile', 'p')
    ->addSelect('p')
    ->getQuery()
    ->getResult();

Doctrine Doctor detects the N+1 pattern at runtime — reports query count, execution time, points to the exact template line, and suggests eager loading with addSelect().

Documentation

Document	Description
Full Analyzers List	Browse the built-in checks for performance, security, integrity, and configuration
Profiler and CI Checks	A quick guide to choosing where to run each check
Architecture Guide	Deep dive into system design, architecture patterns, and technical internals - understand how Doctrine Doctor works under the hood
Configuration Reference	Comprehensive guide to all configuration options - customize analyzers, thresholds, and outputs to match your workflow
Template Security	Essential security best practices for PHP templates - prevent XSS attacks and ensure safe template rendering
AI Mate / MCP integration	Optional AI assistant integration - expose profiler issues to Claude Code, Cursor, and other MCP clients through Symfony AI Mate

Contributing

See Contributing Guide for guidelines.

License

MIT License - see LICENSE for details.

Created by Ahmed EBEN HASSINE

ahmed-bhs / doctrine-doctor

Package info

Security

Fund package maintenance!

Statistics