Php Engine Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require event-engine/php-engine
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       EventEngine\Engine\EngineServiceProvider::class,
   ],
   

2. Basic Event Definition Define an event class (e.g., UserRegistered):

   namespace App\Events;
   
   use EventEngine\Engine\Event;
   
   class UserRegistered extends Event
   {
       public function __construct(public string $userId) {}
   }
   

3. Registering Listeners Bind listeners in a service provider or boot method:

   $engine = app('event-engine');
   $engine->listen(UserRegistered::class, function ($event) {
       // Handle event logic
   });
   

4. Triggering Events Dispatch events via the engine:

   $engine = app('event-engine');
   $engine->dispatch(new UserRegistered('user-123'));
   

First Use Case: Logging Events

$engine->listen(UserRegistered::class, function ($event) {
    \Log::info("User registered: {$event->userId}");
});

Implementation Patterns

Workflow: Event-Driven Architecture

1. Decoupling Logic Use events to separate business logic from execution (e.g., notifications, analytics, audits).

   // Instead of:
   $userService->register($user);
   $notificationService->sendWelcome($user);
   
   // Do:
   $engine->dispatch(new UserRegistered($user->id));
   

2. Middleware for Events Apply middleware to events (e.g., rate limiting, auth checks):

   $engine->listen(UserRegistered::class)
       ->middleware(CheckUserRole::class)
       ->then(function ($event) {
           // Core logic
       });
   

3. Async Processing Offload heavy tasks to queues:

   $engine->listen(UserRegistered::class)
       ->queueOn('high-priority')
       ->then(function ($event) {
           // Queue job here
       });
   

Integration Tips

• Laravel Integration Extend Laravel’s event system by wrapping EventEngine in a facade:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      app()->singleton('event-engine', function () {
          return app('event-engine');
      });
  }
  

  Use in controllers:

  use Illuminate\Support\Facades\EventEngine;
  
  EventEngine::dispatch(new UserRegistered($userId));
  

• Dynamic Listeners Load listeners from config or database:

  $engine->loadListenersFromConfig('events.listeners');
  

• Event Retries Implement retry logic for failed listeners:

  $engine->listen(UserRegistered::class)
      ->retry(3, 100) // Retry 3 times with 100ms delay
      ->then(...);
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies Avoid circular event triggers (e.g., EventA triggers EventB, which triggers EventA again). Solution: Use a triggered flag or middleware to break cycles.

2. Memory Leaks Unbound listeners persist until the app shuts down. Explicitly unbind if needed:

   $engine->forget(UserRegistered::class);
   

3. Priority Collisions Listeners with the same priority may execute unpredictably. Solution: Use explicit priorities:

   $engine->listen(UserRegistered::class, fn($e) => ...)
       ->priority(100); // Higher priority runs first
   

Debugging

• Listener Inspection Dump registered listeners:

  dd($engine->listeners());
  

• Event Tracing Enable debug mode to log event flow:

  $engine->debug(true);
  

Extension Points

1. Custom Event Stores Override the default in-memory store for persistence:

   $engine->setStore(new DatabaseEventStore());
   

2. Event Filters Filter events dynamically:

   $engine->listen(UserRegistered::class)
       ->filter(fn($event) => $event->userId === 'admin')
       ->then(...);
   

3. Event Metadata Attach metadata to events for observability:

   $event = new UserRegistered('user-123');
   $event->setMetadata(['source' => 'api']);
   

Config Quirks

• Default Timeouts Async listeners default to 5-second timeouts. Adjust via:

  $engine->setTimeout(30); // 30 seconds
  

• Queue Configuration Ensure queue drivers (e.g., database, redis) are properly configured in .env.