Proxy Interceptors Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dudu/proxy-interceptors
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Dudu\ProxyInterceptorsBundle\DuduProxyInterceptorsBundle::class => ['all' => true],
   ];
   

2. First Use Case: Intercepting a Service Define an interceptor for an existing service (e.g., App\Service\MyService):

   namespace App\Interceptor;
   
   use Dudu\ProxyInterceptorsBundle\Interceptor\InterceptorInterface;
   use Dudu\ProxyInterceptorsBundle\Interceptor\MethodInterceptor;
   use Dudu\ProxyInterceptorsBundle\Interceptor\Invocation;
   
   class MyServiceInterceptor implements InterceptorInterface
   {
       public function intercept(Invocation $invocation)
       {
           // Pre-processing logic
           $result = $invocation->proceed();
   
           // Post-processing logic
           return $result;
       }
   }
   

3. Configure the Interceptor In config/packages/dudu_proxy_interceptors.yaml:

   interceptors:
       App\Service\MyService:
           - App\Interceptor\MyServiceInterceptor
   

4. Inject the Intercepted Service Use dependency injection as usual:

   public function __construct(private MyService $myService) {}
   

Implementation Patterns

Common Workflows

1. Method-Level Interception Intercept specific methods (e.g., save() in a repository):

   interceptors:
       App\Repository\UserRepository:
           - App\Interceptor\UserRepositoryInterceptor
   

   class UserRepositoryInterceptor implements MethodInterceptor
   {
       public function intercept(Invocation $invocation)
       {
           if ($invocation->getMethodName() === 'save') {
               // Logic before/after save
           }
           return $invocation->proceed();
       }
   }
   

2. Chaining Interceptors Multiple interceptors are executed in declaration order:

   interceptors:
       App\Service\OrderService:
           - App\Interceptor\LogInterceptor
           - App\Interceptor\CacheInterceptor
   

3. Conditional Interception Use Invocation::getMethodName() or Invocation::getArguments() to conditionally apply logic.

4. Proxy Generation The bundle auto-generates proxies at runtime. Avoid manual proxy creation.

Integration Tips

• Leverage Symfony’s DI: Intercept services managed by Symfony’s container (e.g., repositories, services).
• AOP for Cross-Cutting Concerns: Use interceptors for logging, caching, or validation without modifying original classes.
• Testing: Mock intercepted services in tests by overriding the interceptor chain:

  $container->set('interceptor.chain.App\Service\MyService', $mockChain);
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies Interceptors themselves should avoid depending on the intercepted service to prevent circular proxy generation.

2. Method Signature Mismatches Ensure intercepted methods match the original service’s signature (return types, parameters). Use Invocation::proceed() to delegate to the original method.

3. Lazy Loading Issues If intercepting lazy-loaded services (e.g., Doctrine entities), ensure the interceptor handles null or uninitialized states gracefully.

4. Configuration Overrides Interceptor configurations in config/packages/ take precedence over environment-specific configs (e.g., .env).

Debugging

• Enable Debug Mode: Set DUDU_PROXY_INTERCEPTORS_DEBUG=true in .env to log interceptor invocations.
• Check Generated Proxies: Proxies are cached in var/cache/. Clear cache (php bin/console cache:clear) after config changes.
• Verify Interceptor Order: Use DUDU_PROXY_INTERCEPTORS_DEBUG to confirm execution order.

Extension Points

1. Custom Invocation Objects Extend Dudu\ProxyInterceptorsBundle\Interceptor\Invocation for advanced use cases (e.g., adding context data).

2. Dynamic Interceptors Implement Dudu\ProxyInterceptorsBundle\Interceptor\DynamicInterceptorInterface for runtime-registered interceptors:

   $container->get('interceptor.dynamic_registry')->addInterceptor(
       'App\Service\MyService',
       new DynamicInterceptor()
   );
   

3. Event-Based Interception Combine with Symfony events (e.g., kernel.request) for hybrid interception logic.

Performance

• Avoid Heavy Logic in Interceptors: Interceptors run on every method call. Offload expensive operations to the original service.
• Cache Interceptor Results: Use Invocation::getResult() to cache responses if applicable.