Doctrine Persistence

Doctrine Persistence is the interface layer shared by Doctrine’s object mappers — most notably Doctrine ORM (relational) and Doctrine MongoDB ODM (document) — so that application code, framework integrations, and third-party libraries can depend on abstractions like ObjectManager and ObjectRepository rather than a specific mapper implementation. It defines the contracts for persisting and fetching objects, managing class metadata, and reacting to lifecycle events, without implementing any storage backend itself.

This decoupling is what lets frameworks like Symfony offer a single ManagerRegistry service that works whether an application uses the relational ORM, the MongoDB ODM, or both side by side, and lets library authors write mapper-agnostic code (e.g. form field guessers, admin generators) against the shared interfaces instead of coupling to one implementation.

What You Get

• ObjectManager and ObjectRepository interfaces defining the core persist/find/flush contract
• ManagerRegistry / AbstractManagerRegistry for resolving the right manager across multiple configured connections
• ClassMetadata and ClassMetadataFactory interfaces for describing how objects map to storage
• Lifecycle event classes (PreUpdateEventArgs, LifecycleEventArgs, LoadClassMetadataEventArgs, etc.)
• Reflection services (RuntimeReflectionService, TypedNoDefaultReflectionProperty) for metadata-driven property access

Common Use Cases

• Writing framework integrations (e.g. Symfony’s Doctrine bridge) that work across ORM and ODM interchangeably
• Building mapper-agnostic libraries (form guessers, admin panels, serializers) that target the ObjectManager contract
• Reacting to entity lifecycle events (preUpdate, postLoad) without depending on a specific Doctrine implementation
• Implementing a custom object mapper that plugs into existing Doctrine-aware tooling

Under The Hood

Architecture - The library is organized around a small set of core interfaces: ObjectManager (src/ObjectManager.php) defines persist/remove/flush/find, ObjectRepository defines the find-by-criteria contract implementations expose per class, and ManagerRegistry/AbstractManagerRegistry let consumers resolve “the manager for this object’s class” across multiple configured connections/managers — the mechanism Symfony’s Doctrine bridge uses to support ORM and ODM side by side. The Mapping/ subtree (ClassMetadata, ClassMetadataFactory, AbstractClassMetadataFactory, Driver/) defines how metadata about how a class maps to storage is loaded and cached, while Reflection/ supplies typed reflection-property wrappers so metadata drivers can read/write private properties without relying on getters/setters. The Event/ subtree defines the lifecycle event payload classes dispatched through doctrine/event-manager. Tech Stack - Pure PHP (100%) for PHP 8.1+, depending on doctrine/deprecations, doctrine/event-manager, and psr/cache; PHPStan (strict rules) and doctrine/coding-standard run in CI alongside PHPUnit. Code Quality - The tests/ suite covers metadata factory caching, reflection-property edge cases (typed properties without defaults, enum-backed properties), and manager-registry resolution logic; interfaces are fully typed with PHP 8 generics-style PHPDoc templates for static analysis tooling. API Design - As a pure interface package, its design goal is contract stability: ObjectManager/ObjectRepository method signatures are what every Doctrine mapper and every framework integration commits to, so the API changes conservatively and is documented primarily through the interfaces themselves plus the implementing ORM/ODM’s docs.