How doctrine/orm works
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).