Engine Contract Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require hyperf/engine-contract
   

   Add to composer.json under autoload-dev if using for testing:

   "autoload-dev": {
       "psr-4": {
           "App\\Tests\\": "tests/"
       }
   }
   

2. Basic Contract Definition Define a contract interface (e.g., app/Contracts/EngineInterface.php):

   namespace App\Contracts;
   
   interface EngineInterface {
       public function execute(string $command): string;
   }
   

3. Register Contract in Hyperf Bind the contract in config/autoload/containers.php:

   'bindings' => [
       \App\Contracts\EngineInterface::class => \App\Services\EngineService::class,
   ],
   

4. First Use Case Inject the contract into a service or controller:

   use App\Contracts\EngineInterface;
   
   class CommandHandler {
       public function __construct(private EngineInterface $engine) {}
   
       public function handle(string $input) {
           return $this->engine->execute($input);
       }
   }
   

Implementation Patterns

Dependency Injection & Service Binding

• Dynamic Binding: Use Hyperf\Engine\Contract\EngineContract to dynamically resolve engines:

  $engine = app()->make(\Hyperf\Engine\Contract\EngineContract::class, [
      'engine' => 'custom_engine',
  ]);
  

• Contextual Binding: Bind engines per request or context:

  $container->bind(\App\Contracts\EngineInterface::class, function ($container) {
      return new \App\Services\CustomEngine();
  });
  

Engine Lifecycle Management

• Initialization: Override Hyperf\Engine\AbstractEngine for setup:

  class CustomEngine extends AbstractEngine {
      public function __construct() {
          $this->init(); // Calls `initialize()` if defined
      }
  }
  

• Cleanup: Implement Hyperf\Engine\Contract\EngineInterface::shutdown() for teardown.

Testing Strategies

• Mocking Contracts: Use Hyperf\Engine\Contract\EngineContract in tests:

  $this->mock(\Hyperf\Engine\Contract\EngineContract::class, function ($mock) {
      $mock->shouldReceive('execute')->andReturn('mocked_result');
  });
  

• Isolated Engines: Test engines in isolation with Hyperf\Engine\EngineManager.

Integration with Hyperf Components

• Processes: Use Hyperf\Process\ProcessManager to manage long-running engines:

  $process = Process::fromCallable(function () {
      $engine = app()->make(\App\Contracts\EngineInterface::class);
      $engine->execute('long_task');
  });
  

• Events: Dispatch engine events via Hyperf\Event\EventDispatcher:

  event(new EngineExecuted($result));
  

Gotchas and Tips

Common Pitfalls

• Circular Dependencies: Avoid binding contracts to engines that depend on them. Use lazy resolution:

  $container->bind(\App\Contracts\EngineInterface::class, function ($c) {
      return $c->make(\App\Services\EngineService::class);
  });
  

• Stateful Engines: Ensure thread safety if engines hold state. Use Hyperf\Context\Context for shared data:

  Context::set('engine_state', $state);
  

• Configuration Overrides: Prefer config/autoload/engines.php for engine-specific settings:

  return [
      'default' => 'custom_engine',
      'engines' => [
          'custom_engine' => [
              'timeout' => 30,
          ],
      ],
  ];
  

Debugging Tips

• Logging: Use Hyperf\Logger\LoggerFactory to log engine activity:

  $logger = \Hyperf\Logger\LoggerFactory::get('engine');
  $logger->info('Engine executed', ['command' => $command]);
  

• Profiling: Enable Hyperf\Engine\Middleware\EngineProfilerMiddleware to track execution time:

  $middleware = new EngineProfilerMiddleware();
  $middleware->process($request, $next);
  

Extension Points

• Custom Contracts: Extend Hyperf\Engine\Contract\EngineContract for multi-engine support:

  interface MultiEngineContract extends EngineContract {
      public function getEngines(): array;
  }
  

• Middleware: Add engine-specific middleware:

  class EngineAuthMiddleware implements Middleware {
      public function process(RequestInterface $request, Closure $next): ResponseInterface {
          if (!$request->hasHeader('engine-token')) {
              throw new \RuntimeException('Unauthorized');
          }
          return $next($request);
      }
  }
  

• Serialization: Implement Hyperf\Engine\Contract\SerializableEngine for state persistence:

  class SerializableEngine implements SerializableEngine {
      public function serialize(): string {
          return serialize($this->state);
      }
  
      public function unserialize(string $data): void {
          $this->state = unserialize($data);
      }
  }