ProxyManager

ProxyManager provides a set of code generators and runtime utilities for building object proxies in PHP — wrapper classes that transparently defer expensive object initialization, intercept method calls, or localize access to specific object state. It covers several proxy patterns out of the box: lazy-loading ghost objects, virtual proxies, value holders, access-interceptor proxies, and null objects.

The library is a foundational dependency for ORMs and dependency-injection containers that need to defer instantiating heavy objects (like database entities or service graphs) until they’re actually used. It generates the proxy classes on the fly using laminas/laminas-code, caching the generated source to disk for production performance.

What You Get

• Lazy-loading ghost object proxies that initialize their wrapped object on first property/method access
• Virtual proxies and value-holder proxies for deferring construction of an underlying instance
• Access-interceptor proxies for wrapping method calls with before/after hooks (useful for AOP-style cross-cutting concerns)
• Null-object proxy generation for safe default/no-op implementations
• A Configuration object controlling proxy class generation, caching, and autoloading strategy
• Production-tuning guidance for pre-generating and caching proxy classes ahead of runtime

Common Use Cases

• ORMs (e.g. Doctrine) generating lazy-loading proxies for entity associations to avoid unnecessary joins
• Dependency-injection containers deferring construction of expensive services until first use
• Adding cross-cutting method interception (logging, caching, access control) without modifying target classes
• Providing safe null-object defaults for optional dependencies

Under The Hood

Architecture The library’s Factory classes (LazyLoadingGhostFactory, AccessInterceptorValueHolderFactory, etc.) act as the primary entry points: each factory pairs a ProxyGenerator (which emits the proxy class source using laminas/laminas-code’s Generator API) with a GeneratorStrategy (which decides whether to eval the generated code in-memory or write it to a cache file via FileLocator) and an Inflector/Autoloader pair that maps original class names to generated proxy class names. This separation lets the same generation pipeline support multiple proxy patterns (ghost objects, value holders, access interceptors, null objects) by swapping the specific ProxyGenerator implementation.

Tech Stack Pure PHP 8.0 library depending directly on laminas/laminas-code for code generation and webimpress/safe-writer for atomic file writes when caching generated proxies to disk. Test/quality tooling includes PHPUnit, PHPBench for generation-performance benchmarking, Psalm and PHP_CodeSniffer for static analysis/style, and Infection for mutation testing.

Code Quality The tests/ tree includes 201 PHP test files spanning ProxyManagerTest (unit tests per proxy type) and ProxyManagerBench (performance benchmarks), plus mutation testing via Roave Infection Static Analysis Plugin, indicating a rigorous quality bar consistent with its role as a dependency embedded in ORMs and DI containers.

API Design Each proxy type has a dedicated factory class with a focused createProxy()-style method, and the docs/ directory documents each proxy pattern (ghost object, value holder, access interceptor, null object, remote object) individually with usage examples and production-tuning notes; understanding which proxy type fits a given use case is the main learning curve.