Doctrine Doctor Laravel Package

Getting Started

1. Installation: Run composer require --dev ahmed-bhs/doctrine-doctor in your Symfony project. On v2.11.x the bundle ships with the runtime analysis path reworked (see Gotchas), so no extra wiring is needed beyond the usual Flex recipe.
2. Enable Backtraces: Add profiling_collect_backtrace: true under doctrine.dbal in config/packages/dev/doctrine.yaml.
3. First Use Case: Visit any page in your Symfony app in the dev environment, open the Symfony Web Profiler, and navigate to the Doctrine Doctor panel to inspect runtime Doctrine issues. Since v2.11.2 the panel data is attached at view time instead of blocking the response, so the page render is no longer gated on analysis completion.

Implementation Patterns

Daily Workflow

1. Development Phase:

   • Write code as usual, then check the Doctrine Doctor panel after each significant change.
   • Focus on Critical and Warning issues first, then address Info issues progressively.

2. Code Review:

   • Use Doctrine Doctor to catch runtime issues early.
   • Share configuration settings and common patterns with your team to maintain consistency.

3. Testing:

   • Run tests to ensure fixes don’t break functionality.
   • Review the staging environment with production-like data before deployment.

Integration Tips

• Symfony Events: Leverage Symfony events to integrate Doctrine Doctor with custom workflows (e.g., pre-commit hooks).
• CI/CD: Add a step to run Doctrine Doctor in your CI pipeline to catch issues early.
• Custom Analyzers: Extend the package by creating custom analyzers for project-specific requirements.
• Repeat-visit workflow: Because analysis results are cached, iterating on a single page is cheap — reload, fix, reload. Reach for a cache clear only when the panel appears stale after edits.

Example Workflow for N+1 Queries

1. Detect: Doctrine Doctor flags an N+1 query pattern in your Twig template.
2. Locate: Use the backtrace to identify the exact line in your template or controller.
3. Fix: Implement eager loading with addSelect() in your QueryBuilder.
4. Verify: Refresh the page and confirm the issue is resolved in the Doctrine Doctor panel.

Gotchas and Tips

Common Pitfalls

• Backtrace Disabled: If backtraces aren’t showing, ensure profiling_collect_backtrace: true is set in your Doctrine configuration.
• High Thresholds: Some analyzers (e.g., slow_query) have default thresholds that might be too high for your environment. Adjust them in config/packages/dev/doctrine_doctor.yaml.
• Production Environment: Doctrine Doctor is designed for development only. Ensure it’s disabled in production by setting enabled: false in the config.
• Stale Cached Analysis: Since the parser results are cached, the panel can lag behind an edit (especially template or repository changes). If a fix doesn’t disappear from the report, clear the cache before assuming the analyzer is wrong.

Debugging Tips

• No Issues Detected: Verify that your page executes database queries and that doctrine_doctor.enabled is set to true.
• Permission Issues: For the Missing Index Analyzer, ensure your database user has SELECT permissions to execute EXPLAIN queries.
• Performance Overhead: Largely a non-issue from v2.11.2 onward — the runtime analysis no longer blocks requests (parser output is cached and results are attached at view time), and the pending-analysis listener is constructed lazily rather than on every request. If you are still on an older 2.x tag and see slow dev pages, upgrading is the first thing to try before reaching for enabled: false.
• Analysis Not Appearing At All: If the panel is empty after upgrading, suspect the lazy listener — confirm the bundle is registered and the profiler is collecting, rather than assuming analysis ran and found nothing.

Configuration Quirks

• Analyzer-Specific Settings: Some analyzers (e.g., n_plus_one) allow custom thresholds. Adjust these based on your project’s needs.
• Environment-Specific Config: Use environment variables or separate config files for different environments (e.g., dev, staging).

Extension Points

• Custom Analyzers: Extend the package by creating custom analyzers for project-specific Doctrine issues.
• Symfony Events: Listen to Doctrine Doctor events (e.g., doctrine_doctor.issue.detected) to integrate with custom logic or logging.
• Profiler Integration: Customize the Profiler panel by overriding templates or adding your own data collectors.