README

Runtime Analysis Tool for Doctrine ORM — Integrated into Symfony Web Profiler

Why Runtime Analysis?

Unlike static analysis tools (PHPStan, Psalm) that analyze code without execution, Doctrine Doctor:

Detects runtime doctrine issues by analyzing real execution context (actual parameters, data volume, query plans), including N+1 queries, real query performance bottlenecks, and missing indexes.
Integrated into your workflow: Results appear directly in Symfony Web Profiler during development
- 📍 Backtrace: Points to exact template line
- 💡 Suggestion: Use ->addSelect(..) to eager load products

Features

90+ Specialized Analyzers

Performance — Detects N+1 queries, missing database indexes, slow queries, excessive hydration, findAll() without limits, setMaxResults() with collection joins, too many JOINs, and query caching opportunities
Security — Identifies DQL/SQL injection vulnerabilities, QueryBuilder SQL injection risks, sensitive data exposure in serialization, unprotected sensitive fields, and insecure random generators
Integrity — Detects cascade configuration issues, bidirectional inconsistencies, missing orphan removal, type mismatches, float usage for money, uninitialized collections, EntityManager in entities, and architectural violations
Configuration — Validates database charset/collation settings, timezone handling, Gedmo trait configurations, MySQL strict mode, and other database-level configurations

⚡ Quick Start (30 seconds)

Step 1: Install

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

Step 2: That's it!

Auto-configured via Symfony Flex. No YAML, no configuration files needed.

Step 3: See it in action

Refresh any page in your Symfony app (in dev environment)
Open the Symfony Web Profiler (bottom toolbar)
Click the "Doctrine Doctor" panel 🩺

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	Complete catalog of all 90+ analyzers covering performance, security, integrity, and configuration - find the perfect analyzer for your specific needs
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

Maintainers

Package info

Statistics

Security