layout: default title: Analyzers Catalog parent: User Guide nav_order: 2

Analyzer Reference Documentation

1. Overview

Doctrine Doctor implements 90+ specialized analyzers organized into four categories that detect Doctrine ORM anti-patterns and performance issues.

1.1 Severity Classification

2. Analyzer Taxonomy

2.1 Distribution by Category

2.2 Detection Methods

• Static Analysis: Entity metadata, configuration analysis
• Runtime Analysis: Query pattern recognition, signature matching
• Database Analysis: EXPLAIN query execution plans
• Code Analysis: Call stack inspection, trace analysis

3. Performance Analyzers

3.1 Category Overview

Performance analyzers detect patterns that degrade application responsiveness, increase database load, or consume excessive system resources.

Total: 19 analyzers Average Impact: 10-1000x performance improvement when resolved

3.2 Analyzer Catalog

3.2 Key Performance Analyzers

3.2.1 NPlusOneAnalyzer

• Severity: Critical
• Purpose: Detects N+1 query problems (1 initial query + N lazy-loaded queries)
• Detection: Query signature matching and execution pattern analysis
• Impact: 90-99% query reduction when fixed

3.2.2 MissingIndexAnalyzer

• Severity: Critical
• Purpose: Identifies queries doing full table scans
• Detection: Database EXPLAIN plan analysis
• Impact: 10-1000x performance improvement

3.2.3 FlushInLoopAnalyzer

• Severity: Critical
• Purpose: Finds EntityManager::flush() calls inside loops
• Detection: Call stack trace analysis
• Impact: 10-100x improvement by batching operations

3.2.4 SlowQueryAnalyzer

• Severity: Warning
• Purpose: Flags queries exceeding execution time threshold
• Detection: Direct execution time measurement

3.2.5 HydrationAnalyzer

• Severity: Info
• Purpose: Detects inefficient result set hydration
• Impact: 50-80% memory reduction

3.2.6 CartesianProductAnalyzer

• Severity: Critical
• Purpose: Detects cartesian product risks caused by joining multiple collections
• Detection: Correlates multi-collection JOIN patterns with grouped N+1 collection behavior
• Impact: Prevents row explosion, duplicate hydration, memory spikes, and severe slowdowns
• Example: Joining multiple to-many associations in one query creates N x M result multiplication

Note: Some analyzer classes exist in src/Analyzer/ but are not part of the default registered analyzer set.

3.3 Analyzer Summary Table

Internal Parser Utilities (not directly user-facing): | SqlAggregationAnalyzer | Aggregation function analysis | Query optimization | Internal | | SqlConditionAnalyzer | WHERE/ON clause analysis | Index effectiveness | Internal | | SqlPerformanceAnalyzer | SQL pattern analysis | Performance insights | Internal |

4. Security Analyzers

4.1 Category Overview

Security analyzers detect vulnerabilities aligned with OWASP Top 10 and Doctrine-specific attack vectors.

Total: 4 analyzers OWASP Coverage: A02:2021 (Cryptographic Failures), A03:2021 (Injection), A05:2021 (Security Misconfiguration)

4.2 Key Security Analyzers

4.2.1 DQLInjectionAnalyzer

• Severity: Critical
• OWASP: A03:2021 Injection
• Purpose: Detects DQL injection vulnerabilities in string concatenation
• Detection: AST analysis of DQL string construction

4.2.2 SQLInjectionInRawQueriesAnalyzer

• Severity: Critical
• OWASP: A03:2021 Injection
• Purpose: Finds SQL injection in native queries
• Detection: Native query pattern analysis

4.2.3 SensitiveDataExposureAnalyzer

• Severity: Critical
• OWASP: A02:2021 Cryptographic Failures
• Purpose: Detects sensitive fields exposed in serialization
• Detection: Field pattern matching (password, token, secret, api_key)

4.2.4 InsecureRandomAnalyzer

• Severity: Warning
• Purpose: Identifies insecure random number generation
• Detection: Usage of rand() in security contexts

5. Integrity Analyzers

5.1 Category Overview

Integrity analyzers detect code smells, anti-patterns, and violations of best practices that affect maintainability, readability, and adherence to Doctrine ORM conventions.

Total: 35 analyzers Focus: Type safety, relationship consistency, lifecycle management, naming conventions

5.2 Key Analyzers

5.2.1 CascadeAnalyzer (Unified)

Description: Single unified analyzer for all cascade-related issues following Single Responsibility Principle.

Detects:

1. cascade="all" usage (highest priority - most dangerous)
2. cascade="remove" on independent entities (potential data loss)
3. cascade="persist" on independent entities (wrong aggregate boundaries)

Benefits:

• O(n) performance instead of O(3n)
• No duplicate issues
• Clear priority ordering

Example Violation:

/**
 * [@ORM](https://github.com/ORM)\ManyToOne(targetEntity="Tag")
 * [@ORM](https://github.com/ORM)\JoinColumn(cascade={"remove"})  // ❌ Tag is independent!
 */
private Tag $tag;

Issue: Deleting article would delete shared tag → data loss

5.2.2 CascadeConfigurationAnalyzer

Description: Validates consistency between ORM cascade operations and database foreign key constraints.

Violation Example:

/**
 * [@ORM](https://github.com/ORM)\OneToMany(targetEntity="Item", mappedBy="order", cascade={"remove"})
 */
private Collection $items;

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

Issue: ORM expects cascade delete, database sets NULL → inconsistent state

5.2.2 BidirectionalConsistencyAnalyzer

Description: Ensures symmetric mapping in bidirectional relationships.

Violation:

class Order {
    /** [@ORM](https://github.com/ORM)\ManyToOne(targetEntity="Customer", inversedBy="orders") */
    private Customer $customer;
}

class Customer {
    /** [@ORM](https://github.com/ORM)\OneToMany(targetEntity="Order", mappedBy="wrongField") */
    //                                               ↑ Should be "customer"
    private Collection $orders;
}

5.3 Integrity Analyzer Summary

6. Configuration Analyzers

6.1 Key Configuration Analyzers

6.1.1 TimeZoneAnalyzer

• Purpose: Detects timezone handling issues in datetime fields
• Recommendation: Use DateTimeImmutable with UTC timezone

6.1.2 TimestampableTraitAnalyzer

• Purpose: Validates timestampable trait configuration and automatic timestamp updates
• Recommendation: Ensure createdAt/updatedAt fields are mapped and lifecycle updates are consistent

6.1.3 BlameableTraitAnalyzer

• Purpose: Ensures proper user-tracking field configuration for blameable traits
• Recommendation: Use compatible user/entity mappings and nullable strategy where lifecycle demands it

6.1.4 SoftDeleteableTraitAnalyzer

• Purpose: Validates soft delete trait configuration and deleted-at semantics
• Recommendation: Align filter usage, deletedAt mapping, and query expectations across the app

6.1.5 CharsetAnalyzer

• Purpose: Detects charset issues (recommends UTF8MB4)
• Recommendation: Standardize on utf8mb4 to avoid truncation and multi-byte character loss

6.1.6 CollationAnalyzer

• Purpose: Validates collation settings for proper sorting and comparisons
• Detection Notes:
  • MySQL/MariaDB: detects utf8mb4_general_ci vs utf8mb4_unicode_ci mismatches
  • PostgreSQL: detects "C" collation issues, libc vs ICU differences, FK collation mismatches
• Recommendation: Use consistent, platform-appropriate collations across related tables/columns

6.1.7 StrictModeAnalyzer

• Purpose: Ensures MySQL strict mode is enabled
• Recommendation: Enable strict mode to fail fast on invalid/truncated data instead of silent coercion

6.1.8 InnoDBEngineAnalyzer

• Purpose: Validates InnoDB storage engine usage
• Recommendation: Prefer InnoDB for transactions, row-level locking, and foreign key support

6.2 Configuration Summary

7. Configuration

7.1 Basic Configuration

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

7.2 Analyzer Configuration

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

7.3 Enabling / Disabling Individual Analyzers

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

8. Extensibility

8.1 Custom Analyzers

Create custom analyzers by implementing AnalyzerInterface (query-based) or MetadataAnalyzerInterface (metadata-based):

// Query-based analyzer
use AhmedBhs\DoctrineDoctor\Analyzer\AnalyzerInterface;

final class CustomQueryAnalyzer implements AnalyzerInterface
{
    public function analyze(QueryDataCollection $queries): IssueCollection
    {
        // Detection logic based on captured SQL queries
    }
}

// Metadata-based analyzer
use AhmedBhs\DoctrineDoctor\Analyzer\Concern\MetadataAnalyzerTrait;
use AhmedBhs\DoctrineDoctor\Analyzer\MetadataAnalyzerInterface;

final class CustomMetadataAnalyzer implements MetadataAnalyzerInterface
{
    use MetadataAnalyzerTrait;

    public function analyzeMetadata(): IssueCollection
    {
        // Detection logic based on Doctrine metadata or database connection
    }
}

8.2 Registration

services:
    App\Analyzer\CustomAnalyzer:
        tags:
            - { name: 'doctrine_doctor.analyzer' }

[← Back to Main Documentation]({{ site.baseurl }}/) | Configuration →