Doctrine Common

Doctrine Common is a small PHP library that provides the shared plumbing used by Doctrine’s persistence libraries: lazy-loading proxy generation, class-name resolution utilities, and reflection helpers. Where Doctrine Collections handles array abstractions and Doctrine Persistence defines the persistence-layer interfaces, Common supplies the runtime machinery — most notably its ProxyGenerator — that ORM and ODM implementations use to create lazy-loaded proxy objects for entities that haven’t been fully hydrated yet.

The package has narrowed considerably over Doctrine’s history; functionality that once lived here (collections, annotations, caching, event management) has been split into dedicated packages, leaving Common focused on proxy generation and a handful of class/reflection utilities that don’t belong in any single downstream library.

What You Get

• ProxyGenerator and AbstractProxyFactory for generating lazy-loading proxy classes at runtime
• Proxy interface and Autoloader for registering generated proxy classes
• ClassUtils for resolving real class names behind proxy instances
• Debug utility for exporting variable contents in a readable format for debugging
• Comparable interface used by Doctrine components to define custom equality logic

Common Use Cases

• Generating lazy proxy classes for ORM/ODM entities so relations load only when accessed
• Resolving an entity’s real class name when working with proxied objects in application code
• Sharing a single Comparable contract across Doctrine components that need custom equality checks
• Debugging entity/proxy state during development of Doctrine-based applications

Under The Hood

Architecture - The library’s core is the Proxy namespace (src/Proxy/): ProxyGenerator builds PHP source for lazy-loading proxy classes at runtime, AbstractProxyFactory caches and instantiates those generated classes, and Autoloader wires the generated files into PHP’s autoload chain so consuming ORMs (like Doctrine ORM) can transparently substitute a proxy for a not-yet-loaded entity. The much smaller Util namespace holds ClassUtils (strips proxy suffixes to resolve a proxied object’s real class) and Debug (a var_export-style debug dumper), while Comparable is a single-method interface re-exported for other Doctrine packages to implement. Tech Stack - Pure PHP (100%) supporting PHP 7.1 through 8.x, depending on doctrine/persistence for the interfaces it operates against; PHPStan and Psalm both run in CI for static analysis alongside PHPUnit. Code Quality - The tests/ suite exercises the proxy generator’s generated code paths and class-name resolution edge cases; 221 contributors and a long release history reflect that this code sits underneath the widely-used Doctrine ORM, so regressions get caught quickly by downstream consumers. API Design - The public surface is intentionally small and low-level — a handful of classes most application developers never touch directly, since they’re consumed by Doctrine ORM/ODM internals rather than called from everyday application code.