# doctrine/orm architecture

> Architecture diagram of the GitHub repository doctrine/orm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/doctrine/orm
- Repository: https://github.com/doctrine/orm

## Overview

##### Main Components
- Core Persistence Layer:
– EntityManager (e.g., src/EntityManager.php and its interface) which mediates between domain objects and the database.
– UnitOfWork (src/UnitOfWork.php) that tracks changes and synchronizes object state with the database.
- Mapping Layer:
– ClassMetadata and Mapping directories (src/Mapping, src/Mapping/Builder, etc.) handling entity metadata, field mapping, association overrides, inheritance, and custom field types.
- Query Component:
– DQL Parsing and AST modules (e.g., src/Query, src/Query/AST) that capture the parsing of DQL, building of SQL, use of query expressions, and intermediate representations.
– Query Builders and Expression classes (src/QueryBuilder.php, src/Query/Expr).
- Cache Layer:
– Cache components (src/Cache and its subdirectories) that store query, entity, and collection caches; also, associated logging and persister submodules.
- Proxy and Lazy Loading:
– Proxy generation and management (src/Proxy) which are used to support lazy-loading of entities.
- Tools and CLI:
– Console tools, commands, and schema tools (src/Tools/Console, src/Tools/SchemaTool.php) enabling tasks like schema creation/updating, metadata inspection, and debugging.
- Exception Handling & Configuration:
– Dedicated Exception classes (src/Exception, src/Mapping/Exception, etc.) and central configuration (src/Configuration.php).

##### Component Relationships and Interactions
- The EntityManager sits at the core, interacting with the UnitOfWork to manage object persistence.
- When a query is executed:
– The QueryBuilder assembles a DQL expression which is parsed into an AST.
– The Query component converts the AST into SQL (possibly with help from SQL walkers) and interacts with the DBAL.
– The Cache layer is consulted to retrieve or store results.
- The Mapping layer is used at startup and throughout the lifecycle:
– Metadata (extracted by mapping drivers) informs the EntityManager and UnitOfWork of object-to-database table relationships.
- Proxies are created and handed out to clients by the ProxyFactory to support lazy-loading.
- Tools and CLI commands use the configuration and EntityManager to perform operations like clearing caches, generating proxies, and updating the schema.

##### Architectural Patterns / Principles
- Separation of Concerns: Each component, such as the Mapping layer or the Cache layer, is responsible for a specific task.
- Extensibility: Customization points (e.g., custom mappings, id generators, repository customizations) should be clearly identified.
- Use of Patterns: Note the use of the Decorator (evident in EntityManagerDecorator), Factory (ProxyFactory, CacheFactory), and Observer patterns (for event listeners in src/Event).

– Data flow, such as from EntityManager → UnitOfWork → Persistence Layer (via Query).
– Dependency flows, such as Mapping feeding configuration data to EntityManager.
– How Query components interact with Cache and DBAL.
- Classes or interfaces that have large roles (e.g., EntityManagerInterface, ClassMetadata, ProxyFactory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Persistence Layer"
        EMInterface["EntityManagerInterface"]:::core
        EntityManager["EntityManager"]:::core
        UnitOfWork["UnitOfWork"]:::core
    end
    EntityManager -->|"implements"| EMInterface
    EntityManager -->|"TracksChanges"| UnitOfWork

    subgraph "Mapping Layer"
        ClassMetadata["ClassMetadata"]:::mapping
        MappingBuilder["Mapping Builder"]:::mapping
    end
    ClassMetadata -->|"ProvidesMetadata"| EntityManager
    MappingBuilder -->|"BuildsMetadata"| ClassMetadata

    subgraph "Query Component"
        QueryBuilder["Query Builder"]:::query
        DQLParser["DQL Parser/AST"]:::query
        QueryExpr["Query/Expr"]:::query
        SQLConverter["SQL Converter"]:::query
    end
    EntityManager -->|"ExecutesQuery"| QueryBuilder
    QueryBuilder -->|"ParsesDQL"| DQLParser
    DQLParser -->|"BuildsExpression"| QueryExpr
    QueryExpr -->|"GeneratesSQL"| SQLConverter

    subgraph "Cache Layer"
        Cache["Cache"]:::cache
    end
    SQLConverter -->|"FetchesCachesData"| Cache

    subgraph "Proxy and Lazy Loading"
        ProxyFactory["ProxyFactory"]:::proxy
    end
    EntityManager -->|"GeneratesProxy"| ProxyFactory

    subgraph "Tools and CLI"
        ConsoleTools["Console Tools"]:::tools
        SchemaTool["Schema Tool"]:::tools
    end
    ConsoleTools -->|"ManagesSchema"| SchemaTool
    ConsoleTools -->|"UsesEM"| EntityManager

    subgraph "Exception & Configuration"
        Exceptions["Exception Handling"]:::exception
        Configuration["Configuration"]:::exception
    end
    Configuration -->|"ConfiguresEM"| EntityManager
    Exceptions -->|"HandlesErrors"| EntityManager

    %% Click Events
    click EntityManager "https://github.com/doctrine/orm/blob/3.3.x/src/EntityManager.php"
    click EMInterface "https://github.com/doctrine/orm/blob/3.3.x/src/EntityManagerInterface.php"
    click UnitOfWork "https://github.com/doctrine/orm/blob/3.3.x/src/UnitOfWork.php"
    click ClassMetadata "https://github.com/doctrine/orm/blob/3.3.x/src/Mapping/ClassMetadata.php"
    click MappingBuilder "https://github.com/doctrine/orm/tree/3.3.x/src/Mapping/Builder"
    click QueryBuilder "https://github.com/doctrine/orm/blob/3.3.x/src/QueryBuilder.php"
    click DQLParser "https://github.com/doctrine/orm/tree/3.3.x/src/Query/AST"
    click QueryExpr "https://github.com/doctrine/orm/tree/3.3.x/src/Query/Expr"
    click SQLConverter "https://github.com/doctrine/orm/tree/3.3.x/src/Query"
    click Cache "https://github.com/doctrine/orm/tree/3.3.x/src/Cache"
    click ProxyFactory "https://github.com/doctrine/orm/blob/3.3.x/src/Proxy/ProxyFactory.php"
    click ConsoleTools "https://github.com/doctrine/orm/tree/3.3.x/src/Tools/Console"
    click SchemaTool "https://github.com/doctrine/orm/blob/3.3.x/src/Tools/SchemaTool.php"
    click Exceptions "https://github.com/doctrine/orm/tree/3.3.x/src/Exception"
    click Configuration "https://github.com/doctrine/orm/blob/3.3.x/src/Configuration.php"

    %% Styles
    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px
    classDef mapping fill:#ccffcc,stroke:#009900,stroke-width:2px
    classDef query fill:#ccccff,stroke:#000099,stroke-width:2px
    classDef cache fill:#ffffcc,stroke:#999900,stroke-width:2px
    classDef proxy fill:#e0ccff,stroke:#6600cc,stroke-width:2px
    classDef tools fill:#cceeff,stroke:#006699,stroke-width:2px
    classDef exception fill:#ffe6cc,stroke:#ff8000,stroke-width:2px
```
