Proximity Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dealroadshow/proximity
   

   No additional configuration is required for basic usage.

2. First Use Case: Proxying a Class Create a proxy for an existing class (e.g., UserRepository):

   use DealRoadshow\Proximity\Proxy;
   
   $userRepository = new UserRepository();
   $proxy = Proxy::create($userRepository);
   

   The proxy will now intercept method calls to the original object.

3. Where to Look First

   • Documentation (if available; otherwise, check the src/ directory for core logic).
   • tests/ folder for usage examples and edge cases.
   • Proxy class methods (create(), intercept(), etc.) for core functionality.

Implementation Patterns

Common Workflows

1. Transparent Proxying Use proxies to log, validate, or modify method calls without altering the original class:

   $proxy = Proxy::create($service)
       ->intercept('save', function ($args) {
           Log::info('Saving entity', $args);
           return $service->save(...$args);
       });
   

2. Dynamic Method Interception Intercept methods dynamically (e.g., for AOP-like behavior):

   $proxy = Proxy::create($repository)
       ->intercept('*', function ($method, $args) {
           // Cross-cutting logic (e.g., caching, auth checks)
           return $repository->$method(...$args);
       });
   

3. Integration with Laravel Services

   • Service Providers: Bind proxied interfaces to the container:

     $this->app->bind(UserRepository::class, function ($app) {
         return Proxy::create(new EloquentUserRepository())
             ->intercept('find', fn($args) => $this->logAccess(...$args));
     });
     

   • Middleware: Use proxies to wrap HTTP requests/responses:

     $requestProxy = Proxy::create($request)
         ->intercept('get', fn($key) => $this->sanitizeInput($key));
     

4. Testing Mock dependencies with proxies to stub methods:

   $mock = Proxy::create(new class { public function riskyOperation() {} })
       ->intercept('riskyOperation', fn() => 'safe_value');
   

Laravel-Specific Tips

• Service Container: Leverage Laravel’s container to manage proxies:

  $this->app->when(UserRepository::class)
      ->needs('$repository')
      ->give(fn() => Proxy::create(new EloquentUserRepository()));
  

• Events: Trigger events via proxied methods:

  $proxy = Proxy::create($model)
      ->intercept('save', fn($args) => event(new ModelSaved($model)));
  

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Proxies add reflection-based method interception, which can slow down tight loops.
   • Mitigation: Use sparingly or cache proxies (e.g., singleton patterns).

2. Static Method Limitations

   • Proxies cannot intercept static methods directly.
   • Workaround: Use a wrapper class or dynamic method calls via __callStatic().

3. Closure Scope Issues

   • Interceptor closures lose scope (e.g., $this refers to the proxy, not the original object).
   • Fix: Use bindTo or arrow functions:

     ->intercept('method', fn($args) => $original->method(...$args))
     

4. Magic Methods (__get, __set)

   • Proxies may conflict with magic methods in the original class.
   • Debugging: Check if the proxy is overriding expected behavior.

5. Thread Safety

   • Proxies are not thread-safe by default (Laravel’s container handles this, but standalone proxies may not).
   • Note: Relevant only for non-Laravel PHP applications.

Debugging Tips

• Enable Reflection Logging Add this to debug intercepted methods:

  Proxy::debug(true); // Logs all intercepted calls to storage/logs/proximity.log
  

• Check Interception Order Interceptors are applied in registration order (last registered runs last). Use explicit ordering if needed:

  $proxy->intercept('method', $firstClosure)->intercept('method', $secondClosure);
  

Extension Points

1. Custom Interceptors Extend the DealRoadshow\Proximity\Interceptor class to add domain-specific logic:

   class CacheInterceptor implements Interceptor {
       public function __invoke($method, $args) {
           // Custom caching logic
       }
   }
   

   Register via:

   $proxy->intercept('*', new CacheInterceptor());
   

2. Proxy Factories Create reusable proxy configurations:

   class LoggingProxyFactory {
       public static function create($object) {
           return Proxy::create($object)
               ->intercept('*', fn($method, $args) => Log::debug("Called {$method}"));
       }
   }
   

3. Integration with Laravel Packages

   • Laravel Mix: Proxy asset compilation steps.
   • Queues: Wrap job payloads for validation:

     $jobProxy = Proxy::create($job)
         ->intercept('handle', fn() => $this->validatePayload());