Event Laravel Package

Getting Started

Install the package with composer require sabre/event "^6.0" (requires PHP 7.4+). Begin by mastering the Emitter class for synchronous event management—e.g., attaching listeners via $emitter->on('user.created', $callback) and triggering with $emitter->emit('user.created', $payload). For asynchronous work, start with simple Promise usage: Promise::resolve('hello')->then(fn($v) => echo $v);. The official examples repo includes clear demos: simple-event-emitter.php, promise-all.php, and event-loop.php are ideal first reads.

Implementation Patterns

• Emitter Trait in Services: Use EmitterTrait in domain services (e.g., OrderService) to expose on()/emit()—ideal for decoupling order confirmation, shipping, and analytics without tight integration.
• Promise Chaining for External APIs: Replace nested callbacks with Promise\all() for parallel HTTP requests (e.g., fetching user + order + inventory) or Promise\race() for fallback logic.
• Event Loop in CLI Tools: Use EventLoop::addPeriodicTimer() for background tasks (e.g., health checks) and EventLoop::run() to keep workers alive while waiting on async operations.
• Coroutines for Sequential Async: Write async flows linearly using generators:

  coroutine(function () {
      $user = yield $this->fetchUser($id);
      $orders = yield $this->fetchOrders($user['id']);
      return compact('user', 'orders');
  })->then($this->handleCompleteProfile(...));
  

• Priority-Gated Listeners: Leverage on($event, $callback, $priority) to enforce execution order (e.g., audit logger before cache invalidator).

Gotchas and Tips

• Type declaration breakage: v6+ enforces strict type hints (e.g., int $priority in Emitter::on()). Extending Emitter requires matching signatures—PHPStan level 9 (now default in 6.0.1) will catch mismatches.
• Event loop is mandatory for promises: If you create promises using Promise and EventLoop but forget to call EventLoop::run(), your then() callbacks will never fire—common in CLI scripts where developers assume async = non-blocking without驱动.
• Nullable parameters in PHPDoc: v5.1.6+ marks nullable params (e.g., ?float $microseconds). Ensure your static analysis ignores null-related false positives.
• Wildcard emitter ordering: WildcardEmitter::emit('user.created.admin', $data) matches listeners for user.created.*, but no ordering guarantee exists across wildcards—avoid overlapping patterns in critical paths.
• Avoid wait() in HTTP context: While Promise::wait() blocks until resolution, never use it in Laravel controllers—it negates async benefits and blocks the web server. Reserve for CLI, queue workers, or testing.
• once() vs on() priority bug: In older versions, once() ignored priority—fixed in v2.0.1+, but verify your composer.lock excludes broken legacy versions (≤2.0.0).