Doctrine Doctor

https://github.com/ahmed-bhs/doctrine-doctor
Admin
Doctrine Doctor is a runtime analysis tool for Doctrine ORM that detects N+1 queries, performance...
Tokens:219,822
Snippets:1,578
Trust Score:8.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with Composer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Install project dependencies using Composer.

```bash
composer install
```

--------------------------------

### Set up AI Mate MCP integration in Symfony

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/ai-mate.md

Steps to set up AI Mate integration in a Symfony project: install the bridge, initialize AI Mate, discover extensions, enable Doctrine Doctor in mate/extensions.php, optionally set the profiler directory, start the MCP server, and verify the tool.

```bash
composer require --dev symfony/ai-symfony-mate-extension
```

```bash
vendor/bin/mate init
composer dump-autoload
```

```bash
vendor/bin/mate discover
```

```php
return [
    'ahmed-bhs/doctrine-doctor' => ['enabled' => true],
    'symfony/ai-symfony-mate-extension' => ['enabled' => true],
];
```

```php
$container->parameters()
    ->set('ai_mate_symfony.profiler_dir', '%mate.root_dir%/var/cache/dev/profiler');
```

```bash
vendor/bin/mate serve
```

```bash
vendor/bin/mate mcp:tools:list --filter="doctrine*"
```

--------------------------------

### Backtrace Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/first-steps.md

Example of a backtrace showing the code location where the query originated.

```text
src/Controller/UserController.php:42
templates/user/index.html.twig:15
```

--------------------------------

### Verify Installation - Check Bundle Loaded

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/installation.md

Command to verify that the DoctrineDoctorBundle is loaded in the container.

```bash
php bin/console debug:container --parameter=kernel.bundles
```

--------------------------------

### After adding index output

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/missing-indexes.md

Example output after adding the index, showing improved performance with fewer rows scanned and faster execution time.

```text
Query: SELECT * FROM article WHERE status = ?
Rows scanned: 8,500 (only matching rows)
Execution time: 12ms

Improvement: 95% faster
```

--------------------------------

### Never trust user input: use parameterized queries

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Shows the difference between unsafe string interpolation and safe parameterized queries. The bad example directly interpolates user input into DQL, while the good example uses a query builder with a named parameter.

```php
// Bad
$dql = "SELECT u FROM User u WHERE u.role = '{$_GET['role']}'";

// Good
$qb->where('u.role = :role')->setParameter('role', $_GET['role']);
```

--------------------------------

### Stricter N+1 Detection Configuration

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/first-steps.md

Configuration example to set a stricter threshold for N+1 detection in the dev environment.

```yaml
doctrine_doctor:
    analyzers:
        n_plus_one:
            threshold: 2  # Detect even minor N+1 issues
```

--------------------------------

### Analyzer with Metadata Test (CollectionInitializationAnalyzerTest)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/tests/README.md

Example test for an analyzer with metadata (CollectionInitializationAnalyzerTest) that creates entity metadata with an uninitialized collection, writes a temporary PHP file, and cleans up afterward.

```php
/** @test */
public function it_detects_uninitialized_collection(): void
{
    // Arrange: Create entity metadata with uninitialized collection
    $metadata = $this->createEntityMetadata([
        'items' => ['type' => ClassMetadata::ONE_TO_MANY]
    ]);

    // Create temp PHP file without initialization
    $tempFile = sys_get_temp_dir() . '/TestEntity.php';
    file_put_contents($tempFile, '<?php ...');

    // Act
    $issues = $this->analyzer->analyze(QueryDataCollection::empty());

    // Assert
    $this->assertCount(1, $issues);

    // Cleanup
    @unlink($tempFile);
}
```

--------------------------------

### Before: Old template using extract()

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/advanced/template-security.md

Shows the old template style using extract() and a manual escaping function $e. This is the 'before' state in the migration guide.

```php
<?php
// Old template using extract()
extract($context);
$e = fn(string $str): string => htmlspecialchars($str, ENT_QUOTES, 'UTF-8');
?>

<div class="alert">
    <strong><?php echo $e($title); ?></strong>
    <p><?php echo $e($message); ?></p>
</div>
```

--------------------------------

### Enable local hooks with git config core.hooksPath

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/guides/hooks.md

Enables the optional local hooks by setting the core.hooksPath configuration to the .githooks directory. Run composer install and verify npx --no-install markdownlint-cli2 --version works before enabling.

```bash
git config core.hooksPath .githooks
```

--------------------------------

### Affected SQL Query Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/first-steps.md

Example of an affected SQL query with a comment indicating it was executed 100 times.

```sql
SELECT * FROM user WHERE id = ?
-- Executed 100 times
```

--------------------------------

### Adjust Slow Query Threshold Configuration

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/first-steps.md

Configuration example to adjust the slow query threshold to 50 milliseconds.

```yaml
doctrine_doctor:
    analyzers:
        slow_query:
            threshold: 50  # Flag queries over 50ms
```

--------------------------------

### GitHub Actions step with database audits

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/execution-modes.md

GitHub Actions step that includes optional database audits via --with-database. Use when the job starts the database used by your test environment.

```yaml
- name: Run Doctrine Doctor with database audits
  run: php bin/console doctrine:doctor:analyze --with-database --fail-on=warning
```

--------------------------------

### Analyzer with Queries Test (NPlusOneAnalyzerTest)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/tests/README.md

Example test for an analyzer with queries (NPlusOneAnalyzerTest) that creates a query pattern and asserts the issue type is 'N+1 Query'.

```php
/** @test */
public function it_detects_n_plus_one_queries(): void
{
    // Arrange: Create query pattern
    $queries = QueryDataCollection::fromArray([
        $this->createQuery('SELECT * FROM users'),
        $this->createQuery('SELECT * FROM posts WHERE user_id = 1'),
        $this->createQuery('SELECT * FROM posts WHERE user_id = 2'),
        // ... more similar queries
    ]);

    // Act
    $issues = $this->analyzer->analyze($queries);

    // Assert
    $this->assertCount(1, $issues);
    $this->assertEquals('N+1 Query', $issues->toArray()[0]->getType());
}
```

--------------------------------

### Example 4: Solution - Eager Loading with Query Builder

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

This snippet shows the first solution to the N+1 problem: eager loading the comments collection using a query builder with leftJoin and addSelect.

```php
<?php

$articles = $articleRepository
    ->createQueryBuilder('a')
    ->leftJoin('a.comments', 'comments')
    ->addSelect('comments')
    ->getQuery()
    ->getResult();
```

--------------------------------

### DQL Injection Exploitation Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Demonstrates how an attacker can exploit the vulnerable query by providing a crafted username that alters the DQL logic, potentially returning all users.

```php
<?php
// Attacker input
$username = "' OR '1'='1";

// Resulting DQL
"SELECT u FROM App\Entity\User u WHERE u.username = '' OR '1'='1'"
// Returns all users!
```

--------------------------------

### Simple Analyzer Test (StrictModeAnalyzerTest)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/tests/README.md

Example test for a simple analyzer (StrictModeAnalyzerTest) that mocks a non-compliant configuration and asserts one issue is detected.

```php
/** @test */
public function it_detects_missing_configuration(): void
{
    // Arrange: Mock non-compliant configuration
    $this->connection
        ->method('fetchOne')
        ->willReturn('INVALID_VALUE');

    // Act
    $issues = $this->analyzer->analyze(QueryDataCollection::empty());

    // Assert
    $this->assertCount(1, $issues);
}
```

--------------------------------

### Issue Title and Severity Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/first-steps.md

Example of an issue title and severity level as displayed in the Doctrine Doctor panel.

```text
🔴 Critical: N+1 Query Detected
```

--------------------------------

### Install Doctrine Doctor bundle with Composer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/README.md

Install the Doctrine Doctor bundle as a development dependency. The bundle is auto-configured through Symfony Flex, so no YAML configuration is needed for the first run.

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

--------------------------------

### Require the package as dev dependency

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Install the local doctrine-doctor package as a dev dependency.

```bash
composer require --dev ahmed-bhs/doctrine-doctor:@dev
```

--------------------------------

### Example 3: Solution with Query Builder Joins

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

This snippet provides the solution to the N+1 problem by using a query builder with left joins and addSelect to eager load author and comments, avoiding additional queries.

```php
<?php

public function generateReport(ArticleRepository $articleRepository): Response
{
    $articles = $articleRepository
        ->createQueryBuilder('a')
        ->leftJoin('a.author', 'author')
        ->leftJoin('a.comments', 'comments')
        ->addSelect('author', 'comments')
        ->getQuery()
        ->getResult();

    $report = [];
    foreach ($articles as $article) {
        $report[] = [
            'title' => $article->getTitle(),
            'author' => $article->getAuthor()->getName(),
            'comments_count' => $article->getComments()->count(),
        ];
    }

    return $this->json($report);
}
```

--------------------------------

### CascadeConfigurationAnalyzer Violation Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/analyzers.md

Demonstrates a mismatch between ORM cascade remove and database ON DELETE SET NULL, leading to inconsistent state.

```php
/**
 * @ORM\OneToMany(targetEntity="Item", mappedBy="order", cascade={"remove"})
 */
private Collection $items;

// Database: ON DELETE SET NULL (mismatch!)
```

--------------------------------

### Example 4: Solution - DQL with HAVING Clause

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

This snippet shows an alternative solution using DQL with a HAVING clause to filter articles with comments in the database, avoiding N+1 queries.

```php
<?php

$articles = $articleRepository
    ->createQueryBuilder('a')
    ->leftJoin('a.comments', 'c')
    ->having('COUNT(c.id) > 0')  // Filter in database
    ->groupBy('a.id')
    ->getQuery()
    ->getResult();
```

--------------------------------

### After: New template using SafeContext

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/advanced/template-security.md

Shows the new template style using SafeContext with auto-escaping via $context->title and $context->message. This is the 'after' state in the migration guide.

```php
<?php
// New template using SafeContext
// No need for manual escaping function
?>

<div class="alert">
    <strong><?php echo $context->title; ?></strong>
    <p><?php echo $context->message; ?></p>
</div>
```

--------------------------------

### SQL Injection Exploitation - Attacker Input

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Example attacker input that exploits the vulnerable query, demonstrating how an attacker can inject SQL and potentially drop the product table.

```php
<?php
// Attacker input
$category = "electronics' OR '1'='1";
$sortBy = "price; DROP TABLE product--";

// Potential SQL injection and data destruction
```

--------------------------------

### Doctrine Doctor detection output

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/missing-indexes.md

Example output from Doctrine Doctor showing a critical missing index detection with query, rows scanned, execution time, and suggested index.

```text
🔴 Critical: Missing Index Detected

Query: SELECT * FROM article WHERE status = ?
Rows scanned: 50,000
Execution time: 234ms

Suggested index:
ALTER TABLE article ADD INDEX idx_status (status);
```

--------------------------------

### Example 3: N+1 Problem Code in PHP

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

This snippet shows a generateReport method that fetches all articles and then accesses author and comments for each article, causing N+1 queries. The comments indicate the problematic lines.

```php
<?php

public function generateReport(ArticleRepository $articleRepository): Response
{
    $articles = $articleRepository->findAll();

    $report = [];
    foreach ($articles as $article) {
        $report[] = [
            'title' => $article->getTitle(),
            'author' => $article->getAuthor()->getName(),  // N+1!
            'comments_count' => $article->getComments()->count(),  // N+1!
        ];
    }

    return $this->json($report);
}
```

--------------------------------

### Suggestion template: repeated_insert.php

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

PHP template that renders the suggestion HTML. It extracts 'table' and 'insert_count' from context, escapes output, and displays a warning with the count and table name. Includes 'Before' and 'After' code examples showing the difference between individual flushes and batch processing. Returns an array with 'code' and 'description'.

```php
<?php

declare(strict_types=1);

$table = (string) ($context['table'] ?? 'entities');
$insertCount = (int) ($context['insert_count'] ?? 0);
$e = fn (?string $str): string => htmlspecialchars($str ?? '', ENT_QUOTES, 'UTF-8');
ob_start();
?>
<div class="suggestion-header"><h4>Use batch inserts</h4></div>
<div class="suggestion-content">

<div class="alert alert-warning">
    <strong><?php echo $insertCount; ?></strong> individual INSERT queries on
    <code><?php echo $e($table); ?></code>
</div>

<p>Inserting entities one by one forces a database round-trip for each row.
Batch processing reduces this to one round-trip per batch.</p>

<h4>Before</h4>
<div class="query-item"><pre><code class="language-php">foreach ($items as $item) {
    $entityManager->persist($item);
    $entityManager->flush(); // INSERT on every iteration
}</code></pre></div>

<h4>After</h4>
<div class="query-item"><pre><code class="language-php">$batchSize = 50;

foreach ($items as $i => $item) {
    $entityManager->persist($item);

    if (0 === ($i + 1) % $batchSize) {
        $entityManager->flush();
        $entityManager->clear();
    }
}

$entityManager->flush(); // remaining items</code></pre></div>

<p><a href="https://www.doctrine-project.org/projects/doctrine-orm/en/stable/reference/batch-processing.html"
      target="_blank" rel="noopener noreferrer" class="doc-link">
    Doctrine ORM Batch Processing
</a></p>

</div>
<?php
$code = ob_get_clean();

return [
    'code' => $code,
    'description' => sprintf('Use batch inserts for %s table', $e($table)),
];

```

--------------------------------

### Configuration precedence order

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Illustrates the precedence of configuration sources: environment-specific overrides global, which overrides bundle defaults.

```text
Environment-specific (config/packages/dev/)
    ↓ overrides
Global (config/packages/)
    ↓ overrides
Bundle defaults (DependencyInjection/Configuration.php)
```

--------------------------------

### Basic Configuration (YAML)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/analyzers.md

Enables the bundle and controls profiler toolbar display and debug info.

```yaml
doctrine_doctor:
    enabled: true
    profiler:
        show_in_toolbar: true
        show_debug_info: false
```

--------------------------------

### Create a new Symfony app for integration testing

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Create a new Symfony application to test the bundle locally.

```bash
symfony new test-app
cd test-app
```

--------------------------------

### Full Customization

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Complete configuration enabling all analyzers with custom thresholds. Shows profiler settings (show_in_toolbar, show_debug_info) and per-analyzer options. Security, integrity, configuration, and best-practice analyzers have no thresholds.

```yaml
doctrine_doctor:
    enabled: true

    profiler:
        show_in_toolbar: true
        show_debug_info: false

    analyzers:
        n_plus_one:
            enabled: true
            threshold: 5

        slow_query:
            enabled: true
            threshold: 100

        missing_index:
            enabled: true
            slow_query_threshold: 50
            min_rows_scanned: 1000
            explain_queries: true

        hydration:
            enabled: true
            row_threshold: 99
            critical_threshold: 999

        flush_in_loop:
            enabled: true
            flush_count_threshold: 5
            time_window_ms: 1000

        eager_loading:
            enabled: true
            join_threshold: 4
            critical_join_threshold: 7

        lazy_loading:
            enabled: true
            threshold: 10

        bulk_operation:
            enabled: true
            threshold: 20

        entity_manager_clear:
            enabled: true
            batch_size_threshold: 50

        join_optimization:
            enabled: true
            max_joins_recommended: 5
            max_joins_critical: 8

        partial_object:
            enabled: true
            threshold: 5

        find_all:
            enabled: true
            threshold: 99

        get_reference:
            enabled: true
            threshold: 2

        # Security (no thresholds)
        dql_injection:
            enabled: true
        sql_injection_in_raw_queries:
            enabled: true
        sensitive_data_exposure:
            enabled: true
        insecure_random:
            enabled: true

        # Integrity (no thresholds)
        cascade_configuration:
            enabled: true
        cascade_all:
            enabled: true
        bidirectional_consistency:
            enabled: true

        # Configuration (no thresholds)
        strict_mode:
            enabled: true
        charset:
            enabled: true
        inno_db_engine:
            enabled: true

        # Best Practices (no thresholds)
        naming_convention:
            enabled: true
        collection_initialization:
            enabled: true
        missing_embeddable_opportunity:
            enabled: true
        blameable_trait:
            enabled: true
```

--------------------------------

### Use parameterized queries with Doctrine

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Demonstrates using parameterized queries with Doctrine's createQuery method. The bad example concatenates a variable directly into the query string, while the good example uses a named parameter and setParameter.

```php
// Bad
$em->createQuery("SELECT u FROM User u WHERE u.id = " . $id);

// Good
$em->createQuery("SELECT u FROM User u WHERE u.id = :id")
   ->setParameter('id', $id);
```

--------------------------------

### Missing Required Parameters: Incomplete vs Complete

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Shows an incomplete configuration that relies on defaults and a complete configuration with all optional parameters specified. The complete version includes slow_query_threshold, min_rows_scanned, and explain_queries.

```yaml
# 📢 Incomplete
doctrine_doctor:
    analyzers:
        missing_index:
            enabled: true
            # Optional overrides omitted (defaults are used)

# Complete
doctrine_doctor:
    analyzers:
        missing_index:
            enabled: true
            slow_query_threshold: 50
            min_rows_scanned: 1000
            explain_queries: true
```

--------------------------------

### Create and Use YourPatternVisitor with PhpCodeParser

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Create a custom visitor class in the specified file and use it via PhpCodeParser to detect patterns in AST. The visitor must implement enterNode and can return null. The usage snippet shows how to parse code, traverse with NodeTraverser, and check the detection flag.

```text
src/Analyzer/Parser/Visitor/YourPatternVisitor.php
```

```php
<?php

declare(strict_types=1);

namespace AhmedBhs\DoctrineDoctor\Analyzer\Parser\Visitor;

use PhpParser\Node;
use PhpParser\NodeVisitorAbstract;

final class YourPatternVisitor extends NodeVisitorAbstract
{
    private bool $detected = false;

    public function enterNode(Node $node): ?Node
    {
        // Check for your pattern in the AST node
        if ($this->matchesPattern($node)) {
            $this->detected = true;
        }

        return null;
    }

    public function isDetected(): bool
    {
        return $this->detected;
    }

    private function matchesPattern(Node $node): bool
    {
        // Your detection logic using PhpParser node types:
        // Node\Expr\Assign, Node\Expr\MethodCall, Node\Expr\FuncCall,
        // Node\Expr\New_, Node\Param, Node\Stmt\Class_, etc.
        return false;
    }
}
```

```php
<?php

$code = $this->phpCodeParser->extractMethodCode($reflectionMethod);
$ast  = $this->phpCodeParser->parse($code);

$visitor   = new YourPatternVisitor();
$traverser = new NodeTraverser();
$traverser->addVisitor($visitor);
$traverser->traverse($ast);

if ($visitor->isDetected()) {
    // create issue
}
```

--------------------------------

### Disable Doctrine Doctor in production

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Example configuration for disabling the bundle in production environments. The comment indicates the intent.

```yaml
# config/packages/prod/doctrine_doctor.yaml
doctrine_doctor:
    enabled: false  # Disable in production
```

--------------------------------

### Run quality commands

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Run tests, static analysis, coding standards, and complete checks using Composer scripts.

```bash
# Tests
composer test

# Static analysis
composer phpstan

# Coding standards (ECS)
composer ecs

# Complete checks
composer check
```

--------------------------------

### Run All Tests

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/tests/README.md

Runs the entire test suite using PHPUnit.

```bash
vendor/bin/phpunit
```

--------------------------------

### Development Configuration

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Development environment configuration enabling the bundle, showing profiler toolbar and debug info, with strict analyzer thresholds and query explanation.

```yaml
# config/packages/dev/doctrine_doctor.yaml
doctrine_doctor:
    enabled: true

    profiler:
        show_in_toolbar: true
        show_debug_info: true  # Show analyzer performance metrics

    analyzers:
        n_plus_one:
            threshold: 2  # Strict

        slow_query:
            threshold: 20  # Fast local DB

        missing_index:
            explain_queries: true
```

--------------------------------

### BidirectionalConsistencyAnalyzer Violation Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/analyzers.md

Shows a bidirectional relationship where the mappedBy field in the inverse side does not match the owning side's property name.

```php
class Order {
    /** @ORM\ManyToOne(targetEntity="Customer", inversedBy="orders") */
    private Customer $customer;
}

class Customer {
    /** @ORM\OneToMany(targetEntity="Order", mappedBy="wrongField") */
    //                                               ↑ Should be "customer"
    private Collection $orders;
}
```

--------------------------------

### Slow Query Thresholds by Environment

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Shows recommended slow query thresholds for different environments. Use 20 ms for local development, 50 ms for shared development servers, and 100 ms for staging.

```yaml
# Local development (fast SSD)
threshold: 20

# Shared development server
threshold: 50

# Staging (production-like hardware)
threshold: 100
```

--------------------------------

### CascadeRemoveOnIndependentEntityAnalyzer Violation Example

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/analyzers.md

Shows a ManyToOne relationship with cascade remove on an independent entity, which can cause data loss when deleting the owning entity.

```php
#[ORM\ManyToOne(targetEntity: Tag::class, cascade: ['remove'])] // Tag is independent!
private Tag $tag;
```

--------------------------------

### Bulk Operation Recommendation

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Shows the recommended approach for bulk operations: use ORM removal below the threshold, and DQL delete above the threshold.

```php
// Below threshold: ORM is acceptable
foreach ($entities as $entity) {
    $em->remove($entity);
}
$em->flush();

// Above threshold: Use DQL
$qb->delete(Entity::class, 'e')
   ->where('e.status = :status')
   ->setParameter('status', 'inactive')
   ->getQuery()
   ->execute();
```

--------------------------------

### Local Development Thresholds

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Recommended thresholds for local development environments with fast databases. Use strict detection settings to catch issues early.

```yaml
doctrine_doctor:
    analyzers:
        slow_query:
            threshold: 10  # Fast local database
        n_plus_one:
            threshold: 2   # Strict detection
        missing_index:
            min_rows_scanned: 500  # Detect early
```

--------------------------------

### Manual Configuration - Create Configuration File

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/installation.md

Creates the configuration file for Doctrine Doctor when not using Flex, enabling the bundle.

```yaml
# config/packages/dev/doctrine_doctor.yaml
doctrine_doctor:
    enabled: true
```

--------------------------------

### Problem: Forgetting to Escape in Attributes

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/advanced/template-security.md

Shows a vulnerable attribute injection example using raw() directly in an HTML attribute. The comment marks it as VULNERABLE.

```php
// 📢 VULNERABLE - Attribute injection
<div class="user-<?php echo $context->raw('userId'); ?>">
```

--------------------------------

### Raw Output with SafeContext::raw()

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/advanced/template-security.md

Demonstrates intentional unescaped output using the raw() method. Only use for pre-sanitized content, such as already-sanitized SQL syntax highlighting.

```php
// UNSAFE - Use only for pre-sanitized content
echo $context->raw('formatted_sql');

// Example: SQL syntax highlighting is already sanitized
echo $context->raw('highlighted_code');
```

--------------------------------

### Create a feature branch

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Create a new branch for your changes.

```bash
git checkout -b feature/my-change
```

--------------------------------

### Solution: Double-Escaping

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/advanced/template-security.md

Provides two solutions: using raw() to get unescaped value then escaping once, or using auto-escaping directly. The comments label them as GOOD and BETTER.

```php
// GOOD - Use raw() to get unescaped value, then escape once
echo htmlspecialchars($context->raw('username'), ENT_QUOTES, 'UTF-8');

// BETTER - Just use auto-escaping
echo $context->username;
```

--------------------------------

### Project structure

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Shows the directory layout of the project.

```text
doctrine-doctor/
├── src/
│   ├── Analyzer/
│   ├── Collection/
│   ├── DTO/
│   ├── Factory/
│   ├── Issue/
│   ├── Suggestion/
│   ├── Template/
│   └── ValueObject/
├── tests/
├── config/
├── docs/
└── CHANGELOG.md
```

--------------------------------

### Create issue title with sprintf

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Creates a short title for an issue, including the entity and field name. Must be under 80 characters and start with the problem, not the solution.

```php
$title = sprintf('Uninitialized collection in %s::$%s', $shortClassName, $fieldName);
```

--------------------------------

### Solution: Use QueryBuilder (Recommended)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Shows the recommended secure approach using Doctrine's QueryBuilder with parameter binding to avoid DQL injection.

```php
<?php

public function findByUsername(string $username): ?User
{
    return $this->createQueryBuilder('u')
        ->where('u.username = :username')
        ->setParameter('username', $username)
        ->getQuery()
        ->getOneOrNullResult();
}
```

--------------------------------

### Database Permissions for EXPLAIN

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Database permission requirements for the missing index analyzer. MySQL requires granting SELECT on the database to the application user; PostgreSQL only requires SELECT permission, no additional grants.

```sql
-- MySQL: Ensure user can execute EXPLAIN
GRANT SELECT ON database.* TO 'app_user'@'localhost';

-- PostgreSQL: EXPLAIN requires SELECT permission
-- No additional permissions needed
```

--------------------------------

### Build issue description with DescriptionHighlighter

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Builds an issue description using DescriptionHighlighter::highlight(), which wraps placeholders in <code> tags. Auto-detects value types: backslash for class names, parentheses for methods, quotes for strings, uppercase for SQL keywords, dots for DB objects, otherwise generic code.

```php
use AhmedBhs\DoctrineDoctor\Utils\DescriptionHighlighter;

$description = DescriptionHighlighter::highlight(
    'Entity {entity} executes {count} identical {keyword} queries on {table}. '
    . 'This is a typical N+1 pattern that degrades response time linearly.',
    [
        'entity'  => $entityClass,    // auto-detected as class name (has backslash)
        'count'   => (string) $count, // auto-detected as code
        'keyword' => 'SELECT',        // auto-detected as SQL keyword (uppercase)
        'table'   => 'users',         // auto-detected as DB object
    ],
);
```

--------------------------------

### Doctrine Doctor Detection Output

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

Example output from Doctrine Doctor when it detects an N+1 query. It reports the query executed 100 times and suggests using eager loading with a JOIN.

```text
🔴 Critical: N+1 Query Detected

Query executed 100 times:
SELECT * FROM author WHERE id = ?

Suggestion: Use eager loading with JOIN
```

--------------------------------

### Define InitializationPatternInterface and CollectionInitializationVisitor

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Decouple collection initialization detection by defining an interface for patterns and having the visitor iterate over them. The interface requires a matches method, and the visitor accepts an optional patterns array, defaulting to defaultPatterns(). The enterNode method sets hasInitialization when a pattern matches.

```php
interface InitializationPatternInterface
{
    public function matches(Node $node, string $fieldName): bool;
}
```

```php
final class CollectionInitializationVisitor extends NodeVisitorAbstract
{
    public function __construct(
        private readonly string $fieldName,
        ?array $patterns = null,
    ) {
        $this->patterns = $patterns ?? self::defaultPatterns();
    }

    public function enterNode(Node $node): ?Node
    {
        foreach ($this->patterns as $pattern) {
            if ($pattern->matches($node, $this->fieldName)) {
                $this->hasInitialization = true;
                return null;
            }
        }
        return null;
    }
}
```

--------------------------------

### Doctrine Doctor Detection: Mass Assignment Warning

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Doctrine Doctor's detection output for the mass assignment example. It warns about the risk and recommends using explicit DTO mapping or the Form component.

```text
🟠 Warning: Potential Mass Assignment Vulnerability

Controller directly maps request data to entity properties without validation.

Risk: Attackers can modify unintended fields (roles, permissions, balances).

Recommendation: Use explicit DTO mapping or Form component.
```

--------------------------------

### Staging Thresholds

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Recommended thresholds for staging environments that mimic production, with higher thresholds to reduce noise on production-scale data.

```yaml
doctrine_doctor:
    analyzers:
        slow_query:
            threshold: 100
        n_plus_one:
            threshold: 5  # Reduce noise
        missing_index:
            min_rows_scanned: 5000  # Production-scale data
```

--------------------------------

### Symfony Flex Auto-Configuration - Directory Tree

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/getting-started/installation.md

Shows the directory structure created by Symfony Flex recipe for the bundle's configuration file.

```text
config/
└── packages/
    └── dev/
        └── doctrine_doctor.yaml
```

--------------------------------

### Attack Scenario: Malicious Payload via curl

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Example curl command showing an attacker exploiting the mass assignment vulnerability by sending isAdmin and credits fields. Demonstrates the privilege escalation risk.

```bash
# Attacker sends malicious payload
curl -X PUT /api/users/123 \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newname",
    "isAdmin": true,      # Privilege escalation!
    "credits": 999999      # Unauthorized balance modification
  }'
```

--------------------------------

### Doctrine Doctor Detection: Insecure Random Number Generation

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/security.md

Doctrine Doctor's detection output for the insecure random token example. It identifies the weak functions and recommends using random_bytes() or random_int().

```text
🔴 Critical: Insecure Random Number Generation

Detected use of weak random functions: mt_rand(), rand(), uniqid()

Context: Token generation for security purposes

Risk: Attackers can predict tokens and gain unauthorized access.

Recommendation: Use random_bytes() or random_int() for security tokens.
```

--------------------------------

### Before: N+1 Query Pattern with findAll() and Twig Loop

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/README.md

Shows the N+1 query problem: fetching all users with findAll() then accessing user.profile.bio in a Twig loop triggers one query per user, resulting in 100 queries for 100 users.

```php
$users = $repository->findAll();
```

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

--------------------------------

### Example 4: N+1 Problem with Collection Methods

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

This snippet shows an index method that calls isEmpty() on the comments collection, which triggers an additional query for each article. The comments indicate which methods cause queries.

```php
<?php

public function index(ArticleRepository $articleRepository): Response
{
    $articles = $articleRepository->findAll();

    foreach ($articles as $article) {
        // Each of these triggers a query!
        if ($article->getComments()->isEmpty()) {  // Query!
            continue;
        }

        $firstComment = $article->getComments()->first();  // Already loaded
        $commentCount = $article->getComments()->count();  // No new query
    }
}
```

--------------------------------

### Conditional Configuration via Environment Variables

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Configures the bundle using environment variables for the enabled flag and the slow query threshold. The .env.local file provides the actual values for these variables.

```yaml
# config/packages/doctrine_doctor.yaml
doctrine_doctor:
    enabled: '%env(bool:DOCTRINE_DOCTOR_ENABLED)%'

    analyzers:
        slow_query:
            threshold: '%env(int:SLOW_QUERY_THRESHOLD)%'
```

```dotenv
# .env.local
DOCTRINE_DOCTOR_ENABLED=true
SLOW_QUERY_THRESHOLD=30
```

--------------------------------

### IssueType enum entry: REPEATED_INSERT

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Shows how to add a new case to the IssueType enum if the analyzer covers a new concept. The example uses the existing BULK_OPERATION case, but a new case can be added as shown.

```php
case REPEATED_INSERT = 'repeated_insert';

```

--------------------------------

### GitHub Actions step for Doctrine Doctor

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/execution-modes.md

GitHub Actions step to run Doctrine Doctor after installing Symfony dependencies. Uses --fail-on=warning, the default severity that fails the build on warnings or critical findings.

```yaml
- name: Run Doctrine Doctor
  run: php bin/console doctrine:doctor:analyze --fail-on=warning
```

--------------------------------

### Run full pre-PR quality checks

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/guides/quality-checks.md

Run the full set of quality checks before submitting a pull request. This includes linting, coding standards, static analysis, dependency analysis, mess detection, rector, tests, markdown linting, and agent harness consistency checks.

```bash
composer lint
composer ecs
composer phpstan
composer phpmd
composer rector
composer deptrac
composer test
composer markdown-lint
composer agent:harness
```

--------------------------------

### Clone the repository

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/contributing/development.md

Clone your fork and add the upstream remote to keep your local copy in sync.

```bash
git clone https://github.com/YOUR-USERNAME/doctrine-doctor.git
cd doctrine-doctor
git remote add upstream https://github.com/ahmed-bhs/doctrine-doctor.git
```

--------------------------------

### Default configuration values

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Shows the default configuration values used when no configuration file exists, including enabled flags, paths, and analyzer thresholds.

```yaml
doctrine_doctor:
    enabled: true

    analysis:
        exclude_third_party_entities: true
        exclude_paths: ['vendor/']

    profiler:
        show_in_toolbar: true
        show_debug_info: false

    debug:
        enabled: false
        internal_logging: false

    analyzers:
        # Performance
        n_plus_one:
            enabled: true
            threshold: 5

        slow_query:
            enabled: true
            threshold: 100  # milliseconds

        missing_index:
            enabled: true
            slow_query_threshold: 50
            min_rows_scanned: 1000
            explain_queries: true

        # ... (see section 5 for complete list)
```

--------------------------------

### Analyzer class file path

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Place the new analyzer class in this path within the project's source directory, replacing {Category} and YourAnalyzer with the appropriate names.

```text
src/Analyzer/{Category}/YourAnalyzer.php
```

--------------------------------

### Configure Bulk Operation Analyzer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Enables the bulk operation analyzer with a threshold of 20 entities to recommend DQL bulk operations.

```yaml
doctrine_doctor:
    analyzers:
        bulk_operation:
            enabled: true
            threshold: 20
```

--------------------------------

### Configure Missing Index Analyzer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Enables the missing index analyzer. The slow_query_threshold (100 ms) triggers EXPLAIN analysis, min_rows_scanned (1000) is the minimum rows to recommend an index, and explain_queries (true) executes EXPLAIN queries, requiring database permissions.

```yaml
doctrine_doctor:
    analyzers:
        missing_index:
            enabled: true
            slow_query_threshold: 100
            min_rows_scanned: 1000
            explain_queries: true
```

--------------------------------

### Validate Configuration with lint:yaml and debug:config

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Commands to validate the configuration syntax and inspect the merged configuration. Use lint:yaml to check YAML syntax, debug:config to validate the container configuration, and --resolve-env to dump the complete merged configuration with environment variables resolved.

```bash
# Check YAML syntax
php bin/console lint:yaml config/packages/doctrine_doctor.yaml

# Validate container configuration
php bin/console debug:config doctrine_doctor

# Dump complete merged configuration
php bin/console debug:config doctrine_doctor --resolve-env
```

--------------------------------

### Basic N+1 in Templates: Controller and Template

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

Shows the initial controller and template that cause an N+1 query: the controller fetches all articles with a single query, and the template accesses article.author.name, triggering one additional query per article.

```php
<?php
// src/Controller/ArticleController.php

namespace App\Controller;

use App\Repository\ArticleRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ArticleController extends AbstractController
{
    #[Route('/articles', name: 'app_articles')]
    public function index(ArticleRepository $articleRepository): Response
    {
        $articles = $articleRepository->findAll();  // 1 query

        return $this->render('article/index.html.twig', [
            'articles' => $articles,
        ]);
    }
}
```

```twig
{% raw %}{# templates/article/index.html.twig #}
{% for article in articles %}
    <article>
        <h2>{{ article.title }}</h2>
        <p>By {{ article.author.name }}</p>  {# +N queries! #}
    </article>
{% endfor %}{% endraw %}
```

--------------------------------

### Configure join_optimization analyzer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Configuration for the join_optimization analyzer. max_joins_recommended (default 5) is the recommended maximum JOINs, and max_joins_critical (default 8) is the critical threshold.

```yaml
doctrine_doctor:
    analyzers:
        join_optimization:
            enabled: true
            max_joins_recommended: 5
            max_joins_critical: 8
```

--------------------------------

### Configure partial_object analyzer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Configuration for the partial_object analyzer. The threshold parameter (default 5) sets the minimum fields loaded to suggest partial objects.

```yaml
doctrine_doctor:
    analyzers:
        partial_object:
            enabled: true
            threshold: 5
```

--------------------------------

### Enabling/Disabling Individual Analyzers (YAML)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/analyzers.md

Shows how to enable specific analyzers (n_plus_one, dql_injection, strict_mode) individually.

```yaml
doctrine_doctor:
    analyzers:
        n_plus_one:
            enabled: true
        dql_injection:
            enabled: true
        strict_mode:
            enabled: true
```

--------------------------------

### Solution: Query Builder with Joins

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

The solution uses a query builder with left joins and addSelect to eagerly load all related entities, reducing the query count to one.

```php
<?php

public function index(ArticleRepository $articleRepository): Response
{
    $articles = $articleRepository
        ->createQueryBuilder('a')
        ->leftJoin('a.author', 'author')
        ->leftJoin('author.country', 'country')
        ->leftJoin('a.comments', 'comments')
        ->leftJoin('comments.author', 'commentAuthor')
        ->addSelect('author', 'country', 'comments', 'commentAuthor')
        ->getQuery()
        ->getResult();

    return $this->render('article/index.html.twig', [
        'articles' => $articles,
    ]);
}
```

--------------------------------

### Shared Development Server Thresholds

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Recommended thresholds for a shared development server, balancing detection with reduced noise from multiple developers.

```yaml
doctrine_doctor:
    analyzers:
        slow_query:
            threshold: 50
        n_plus_one:
            threshold: 3
        missing_index:
            min_rows_scanned: 1000
```

--------------------------------

### Configure Eager Loading Analyzer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Enables the eager loading analyzer. join_threshold (4) triggers info/warning severity, critical_join_threshold (7) triggers critical severity.

```yaml
doctrine_doctor:
    analyzers:
        eager_loading:
            enabled: true
            join_threshold: 4
            critical_join_threshold: 7
```

--------------------------------

### Run Tests Stopping on Failure

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/tests/README.md

Runs PHPUnit and stops on the first failure to see only failures.

```bash
vendor/bin/phpunit --stop-on-failure
```

--------------------------------

### Template file path

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/CONTRIBUTING_ANALYZER.md

Path where suggestion templates are stored, under src/Template/Suggestions/{Category}/.

```text
src/Template/Suggestions/Performance/your_template.php
```

--------------------------------

### Before Fix performance metrics

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/examples/n-plus-one.md

Performance metrics before fixing the N+1 problem: 501 queries, 1,247ms execution time, and 45MB memory usage.

```text
Queries: 501
Execution time: 1,247ms
Memory: 45MB
```

--------------------------------

### Analyzer Configuration (YAML)

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/analyzers.md

Configures individual analyzers with thresholds: n_plus_one (threshold 5), slow_query (threshold 100 ms), and missing_index (slow_query_threshold 50).

```yaml
doctrine_doctor:
    analyzers:
        n_plus_one:
            enabled: true
            threshold: 5
        slow_query:
            enabled: true
            threshold: 100  # milliseconds
        missing_index:
            enabled: true
            slow_query_threshold: 50
```

--------------------------------

### Configure get_reference analyzer

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/docs/user-guide/configuration.md

Configuration for the get_reference analyzer. The threshold parameter (default 2) sets the minimum find() calls to recommend getReference().

```yaml
doctrine_doctor:
    analyzers:
        get_reference:
            enabled: true
            threshold: 2
```

--------------------------------

### Create and use a DoctrineDoctor suggestion template

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/src/Template/Suggestions/README.md

These two PHP blocks form the complete workflow for creating a suggestion template: first, the template file itself (with context extraction, HTML escaping, output buffering, and the returned array), then the analyzer method that uses it via SuggestionFactory::createFromTemplate. The template file must be named {template_name}.php and the templateName argument omits the .php extension.

```php
<?php

declare(strict_types=1);

/**
 * Template for {Your Analyzer Name}
 *
 * Context variables:
 * @var string $entity_class - Entity class name
 * @var string $field_name - Field name
 * @var int $count - Number of occurrences
 */

// Extract context for clarity and type safety
[
    'entity_class' => $entityClass,
    'field_name' => $fieldName,
    'count' => $count,
] = $context;

// Helper function for safe HTML escaping
$e = fn(string $str): string => htmlspecialchars($str, ENT_QUOTES, 'UTF-8');

// Start output buffering
ob_start();
?>

<div class="suggestion-header">
    <h4>Your Suggestion Title</h4>
</div>

<div class="suggestion-content">
    <div class="alert alert-warning">
        <strong>Issue Description</strong><br>
        Detected <?= $count ?> <?= $count > 1 ? 'issues' : 'issue' ?> in <code><?= $e($entityClass) ?></code>
    </div>

    <h4>Problem</h4>
    <div class="code-block">
        <pre><code class="language-php">// Bad code example
class <?= $e($entityClass) ?> {
    private $<?= $e($fieldName) ?>;
}</code></pre>
    </div>

    <h4>Solution</h4>
    <div class="code-block">
        <pre><code class="language-php">// Good code example
class <?= $e($entityClass) ?> {
    private string $<?= $e($fieldName) ?>;
}</code></pre>
    </div>

    <h4>Benefits</h4>
    <ul>
        <li>Benefit 1</li>
        <li>Benefit 2</li>
    </ul>

    <p>
        <a href="https://docs.example.com" target="_blank" class="doc-link">
            📜 Documentation
        </a>
    </p>
</div>

<?php
$code = ob_get_clean();

return [
    'code' => $code,
    'description' => sprintf(
        'Short description with %s context',
        $entityClass
    )
];
```

```php
use AhmedBhs\DoctrineDoctor\ValueObject\SuggestionMetadata;
use AhmedBhs\DoctrineDoctor\ValueObject\SuggestionType;
use AhmedBhs\DoctrineDoctor\ValueObject\Severity;

private function createSuggestion(): SuggestionInterface
{
    return $this->suggestionFactory->createFromTemplate(
        templateName: 'your_template_name',  // Without .php extension
        context: [
            'entity_class' => $entityClass,
            'field_name' => $fieldName,
            'count' => $count,
        ],
        metadata: new SuggestionMetadata(
            type: SuggestionType::performance(),
            severity: Severity::high(),
            title: 'Your Issue Title',
            tags: ['performance', 'doctrine']
        )
    );
}
```

--------------------------------

### Run Tests with TestDox

Source: https://github.com/ahmed-bhs/doctrine-doctor/blob/main/tests/README.md

Runs PHPUnit with testdox output to see detailed assertions.

```bash
vendor/bin/phpunit --testdox
```
Tokens:
Raw