Proxy Manager Lts Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require friendsofphp/proxy-manager-lts

No framework integration is required out-of-the-box — it’s framework-agnostic. Your first use case is likely implementing lazy loading for heavy dependencies. For example, to lazily instantiate a costly service (e.g., database-dependent client), create a proxy factory and generate a proxy class:

use ProxyManager\Factory\LazyLoadingValueHolderFactory;
use ProxyManager\Proxy\LazyLoadingInterface;

$factory = new LazyLoadingValueHolderFactory();
$proxy   = $factory->createProxy(
    HeavyService::class,
    function (&$wrappedObject, $proxy, $method, $params, &$initializer) {
        $initializer = null; // Initialize only once
        $wrappedObject = new HeavyService(); // Actual instantiation
        return true;
    }
);

// HeavyService is *not* instantiated until a method is called
$proxy->doSomethingExpensive(); // Only now is HeavyService constructed

Check the examples/ directory in the source repo (if available) or the original ProxyManager docs for foundational concepts — this LTS fork maintains the same API surface.

Implementation Patterns

• Lazy Services in DI Containers: Integrate proxy generation with Symfony DI or Laravel’s container by extending service resolution logic. For instance, wrap resolved services in a proxy before returning them, especially for lazy tagged services.
• Access Interceptors for Logging/Metrics: Attach pre/post method hooks to intercept calls (e.g., performance tracing):

use ProxyManager\Factory\AccessInterceptorScopeLocalizerFactory;
use ProxyManager\Proxy\AccessInterceptorInterface;

$factory = new AccessInterceptorScopeLocalizerFactory();
$proxy   = $factory->createProxy(
    Service::class,
    ['preSetMethod' => function ($instance, $method, &$params) {
        logger()->debug("Calling $method");
    }]
);

• Virtual Proxies for Domain Objects: Proxy expensive entity relationships (e.g., User->getProfile()) to avoid N+1 queries. The proxy defers loading until getProfile() is accessed.
• Caching Proxy Metadata: For production, cache generated proxy classes to disk using ProxyManager\Configuration::setProxyGenerator() with a custom generator that writes to var/proxies/. Reduces runtime overhead significantly.

Gotchas and Tips

• Autoloading Conflicts: Generated proxy classes must be autoloadable. Register a custom autoloader or pre-generate proxies (see below) — do not rely on __call() in your base classes, as proxies often rely on __construct() and signature matching.
• Memory Leaks in Long-Running Scripts: Virtual proxies with closures capture scope — ensure interceptors don’t hold references to non-serializable objects (e.g., closures, DB connections). Use ScopeLocalizer to scope interceptors to request context.
• PHP 8+ Compatibility: The LTS fork backports fixes for newer PHP versions — but if you’re using attributes or named arguments in proxy targets, verify that signatures match exactly. Proxy generation is compile-time via Reflection, so mismatches break silently if not tested.
• Test First!: Proxies rely on runtime class generation — unit tests must cover lazy vs. eager behavior (e.g., assert constructor wasn’t called until method invocation). Mock the proxy factory in tests.
• Pre-generation Strategy: For performance-critical apps (e.g., CLI tools, workers), generate proxies at build time using ProxyManager\Util\ProxyGenerator::generate() and ClassLoader::addClassLoader(). Avoid runtime compilation in prod.