Yii Event Laravel Package

Getting Started

• In a Yii 3 skeleton (yiisoft/app) this package is already installed and wired. Start by reading the merged config: config/common/events.php in your app, plus vendor/yiisoft/yii-event/config/di.php, which binds Psr\EventDispatcher\EventDispatcherInterface to the package dispatcher. Everything you register goes through that binding.
• Installing standalone: composer require yiisoft/yii-event. Note it is a thin integration layer over yiisoft/event-dispatcher (the actual PSR‑14 engine); read both, but treat the latter as the source of truth for dispatcher semantics.
• First use case — dispatch a small event and react to it:

// config/common/events.php
return [
    'yiisoft/yii-event' => [
        'events' => [
            App\Event\UserRegistered::class => [
                [App\Listener\SendWelcomeEmail::class, 'handle'],
            ],
        ],
    ],
];

final class UserService
{
    public function __construct(private EventDispatcherInterface $events) {}

    public function register(string $email): void
    {
        // ...
        $this->events->dispatch(new UserRegistered($email));
    }
}

• Verify before you build on it: pull EventDispatcherInterface from the container, dispatch a throwaway event from a console command, and run the skeleton's config check (composer check, which exercises the package's listener configuration checker). This catches typos in event/listener class names before runtime.

Implementation Patterns

• Inject the interface, never the concrete dispatcher. Constructor-type against Psr\EventDispatcher\EventDispatcherInterface; services stay framework-agnostic and tests can swap a fake or collecting dispatcher.
• Events are immutable DTOs. final class OrderPlaced { public function __construct(public readonly string $orderId) {} } — no base class needed. PSR‑14 dispatches objects, so listeners are keyed by the event class you actually dispatch.
• Listener formats in config:
  • [SomeListener::class, 'handle'] — resolved from the container, so constructor DI works.
  • InvokableListener::class — class-string for an invokable service, also container-resolved.
  • Closures/callables — fine for prototypes; avoid in production (see gotchas).
• Group by event, order is registration order. Keep related listeners in one file; split into per-feature files (config/common/events/foo.php) for modular apps and let yiisoft/config merge them. Ordering matters — put audit/logging handlers first, side-effects last.
• Lifecycle events. HTTP and console runners emit events like BeforeRequest/AfterRequest; register cross-cutting concerns (request IDs, timing) there when they're not HTTP-specific enough to justify middleware.
• Stoppable events for vetoable flows. Implement StoppableEventInterface where a listener may cancel ("can this be saved?") and check isPropagationStopped() in the dispatcher loop. Use sparingly — it makes flow harder to follow.
• Testing. Unit-test listeners in isolation (mock constructor deps, call handle()); use a collecting fake dispatcher in service tests to assert the event was dispatched. Reserve full-container dispatch tests for integration coverage of side effects.
• Defer heavy work. Dispatch is synchronous and in-process. Listeners should enqueue jobs (yiisoft/queue or similar) for email, webhooks, and long writes rather than doing them inline.
• Dispatch at boundaries. Emit domain events from application services/handlers, not entities or repositories; listeners are the integration seam between modules.

Gotchas and Tips

• The container binding is the dispatcher. If you new a PSR‑14 dispatcher anywhere, config listeners silently never fire. Always resolve EventDispatcherInterface; if you decorate, decorate the bound interface so registration still flows through the package.
• Class-string listeners must be invokable. SomeListener::class without __invoke() fails; use [Class::class, 'method'] for ordinary methods.
• Closures break config caching/serialization. Yii 3 caches merged config in production; closures work in dev but will bite you. Prefer class-based listeners and keep them stateless/autowirable.
• Typos fail silently at runtime. A misspelled event class simply never matches. Make the package's listener configuration checker part of CI — it's the cheapest protection you have.
• Exceptions propagate. PSR‑14 does not catch listener exceptions; a throwing listener can fail the request from inside dispatch(). Wrap genuinely non-critical listeners in try/catch inside the listener and log; let the error handler manage the rest.
• No priorities. Ordering is array order in config. There's no priority key — list listeners explicitly or have one coordinating listener.
• Don't build a service locator. Because listeners are container-resolved, injecting ContainerInterface is tempting; inject concrete dependencies instead.
• Debugging "listener didn't run" — in order: (1) exact dispatched class matches the registered key, (2) dispatcher came from the container, (3) config checker passed, (4) an earlier listener stopped propagation. A temporary logging listener at the top of the list confirms the event arrives.
• Extension points. For custom provider/composite behavior, implement ListenerProviderInterface and rebind, or override the package's listener factory/event config via DI. A decorator around EventDispatcherInterface is the cleanest place for logging, metrics, and tracing while keeping config unchanged.
• Treat it as glue. With ~17 stars it's a small wrapper; don't expect features beyond wiring config into PSR‑14. Stick to the config conventions — the rest of Yii 3's lifecycle events assume them.