Interoperability Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require php-standard-library/interoperability
   

2. Locate Core Classes:
   • Interfaces: vendor/php-standard-library/interoperability/src/Contracts/
   • Adapters: vendor/php-standard-library/interoperability/src/Adapters/
   • Utilities: vendor/php-standard-library/interoperability/src/Utilities/

First Use Case: Standardizing Event Dispatchers

use PHPStandardLibrary\Interoperability\Contracts\EventDispatcherInterface;

// Laravel's event dispatcher
$laravelDispatcher = new LaravelEventDispatcher();

// Third-party dispatcher
$thirdPartyDispatcher = new ThirdPartyEventDispatcher();

// Wrap with adapter for consistency
$standardDispatcher = new \PHPStandardLibrary\Interoperability\Adapters\EventDispatcherAdapter(
    $thirdPartyDispatcher
);

$standardDispatcher->dispatch(new MyEvent());

Implementation Patterns

1. Adapter Pattern for Laravel Services

Problem: Integrate a non-Laravel cache library with Laravel’s cache facade. Solution:

use PHPStandardLibrary\Interoperability\Contracts\CacheInterface;
use PHPStandardLibrary\Interoperability\Adapters\CacheAdapter;

class LaravelCacheWrapper implements CacheInterface {
    public function __construct(private CacheAdapter $adapter) {}

    public function get($key) {
        return $this->adapter->get($key);
    }

    // Delegate other methods...
}

2. Dependency-Agnostic Middleware

Pattern: Use MiddlewareInterface to abstract framework-specific middleware.

use PHPStandardLibrary\Interoperability\Contracts\MiddlewareInterface;

class AuthMiddleware implements MiddlewareInterface {
    public function handle($request, Closure $next) {
        if (!$request->user()) {
            abort(403);
        }
        return $next($request);
    }
}

// Register in Laravel via:
$app->bind(
    \PHPStandardLibrary\Interoperability\Contracts\MiddlewareInterface::class,
    AuthMiddleware::class
);

3. Event-Driven Workflows

Use Case: Decouple event listeners from Laravel’s Illuminate\Events\Dispatcher.

use PHPStandardLibrary\Interoperability\Contracts\EventDispatcherInterface;

class OrderProcessedListener {
    public function __construct(private EventDispatcherInterface $dispatcher) {}

    public function handle(Order $order) {
        $this->dispatcher->dispatch(new OrderProcessedEvent($order));
    }
}

4. Service Container Integration

Leverage ServiceProviderInterface to register dependencies portably:

use PHPStandardLibrary\Interoperability\Contracts\ServiceProviderInterface;

class DatabaseServiceProvider implements ServiceProviderInterface {
    public function register(Container $container) {
        $container->singleton(
            \PDO::class,
            fn() => new PDO('mysql:host=...')
        );
    }
}

Gotchas and Tips

1. Interface Mismatches

• Pitfall: Assuming Laravel’s Illuminate\Contracts\Cache\Store implements CacheInterface.
• Fix: Use the provided CacheAdapter to bridge implementations:

  $adapter = new \PHPStandardLibrary\Interoperability\Adapters\LaravelCacheAdapter(
      Cache::store('file')
  );
  

2. Circular Dependencies

• Tip: Prefer constructor injection with interfaces over concrete classes to avoid tight coupling.

  // Bad: Tight coupling
  new MyService(new LaravelEventDispatcher());
  
  // Good: Interface-based
  new MyService(new EventDispatcherAdapter(new ThirdPartyDispatcher()));
  

3. Performance Overhead

• Gotcha: Adapters add minimal overhead, but excessive nesting (e.g., Adapter<Adapter<Service>>) can impact performance.
• Tip: Use direct implementations when possible, reserve adapters for cross-library boundaries.

4. Laravel-Specific Quirks

• Service Binding: Laravel’s container may conflict with the library’s ServiceProviderInterface. Explicitly bind interfaces:

  $app->bind(
      \PHPStandardLibrary\Interoperability\Contracts\CacheInterface::class,
      fn($app) => new CacheAdapter($app->make(\Illuminate\Contracts\Cache\Store::class))
  );
  

5. Testing Strategies

• Mock Interfaces: Replace Laravel services with mocks of *Interface contracts:

  $this->mock(CacheInterface::class)->shouldReceive('get')->once();
  

• Adapter Isolation: Test adapters in isolation to verify contract compliance.

6. Extension Points

• Custom Adapters: Extend the library by creating new adapters for unsupported services:

  class DoctrineEntityManagerAdapter implements EntityManagerInterface {
      public function __construct(private EntityManager $em) {}
      // Implement methods...
  }
  

• Contribute: Submit adapters to the library for shared use cases.

7. Debugging Tips

• Interface Violations: Use instanceof checks or get_class() to verify implementations:

  if (!$dispatcher instanceof EventDispatcherInterface) {
      throw new \RuntimeException('Dispatcher must implement EventDispatcherInterface');
  }
  

• Adapter Logs: Add debug logs in adapters to trace cross-boundary calls:

  \Log::debug('Adapter: Delegating to underlying service', ['method' => __FUNCTION__]);