Events Laravel Package

Getting Started

The illuminate/events package provides a simple event dispatcher implementation, leveraging Laravel’s contract-based architecture. To start:

1. Ensure Laravel 13+ (per composer.json requirements), as this package targets the latest framework version.
2. Although this package is typically installed as part of Laravel (via laravel/framework), it can be used standalone in any PHP project that supports PSR-11 containers.
3. First use case: register a basic event listener to handle domain-side side effects (e.g., logging after user registration) without coupling logic to core services.

use Illuminate\Events\Dispatcher;
use Illuminate\Container\Container;

$events = new Dispatcher(Container::getInstance());
$events->listen(UserRegistered::class, function ($event) {
    logger()->info('New user registered: ' . $event->user->email);
});

Check tests/ for usage patterns if official docs are minimal.

Implementation Patterns

• Event-Driven Workflows: Use events to decouple domain side effects (notifications, audit logging, cache invalidation) from core business logic. Dispatch from domain services or application services (not controllers directly in larger apps).
• Custom Dispatcher Configuration: For non-Laravel apps, bootstrap a Dispatcher with a Container to inject dependencies into listeners:

  $container = new Container;
  $container->singleton(LoggerInterface::class, MonologLogger::class);
  $events = new Dispatcher($container);
  $events->listen(OrderShipped::class, ShipNotificationListener::class); // Listener resolved from container
  

• Wildcard Listeners: Handle multiple event types uniformly:

  $events->listen('*.shipped', function ($event) { /* unified shipping logging */ });
  

• Testing: Stub Dispatcher with Mockery or PHPUnit doubles to assert event dispatching occurs without triggering real side effects.

Gotchas and Tips

• Standalone Usage Complexity: Without Laravel’s full service container, ensure you provide a working PSR-11 container to Dispatcher, otherwise listener instantiation may fail silently.
• No Auto-Discovery in Standalone Mode: Unlike Laravel apps (where event/service providers auto-register), listeners must be explicitly bound via listen() or manually via service providers.
• Missing Broadcast/Queue Support: Unlike Laravel’s full event system, this package only provides local dispatching — no built-in broadcasting or queued listeners. You must integrate with separate packages (e.g., laravel/octane, custom queue workers).
• Dependency on illuminate/container: Even standalone, the container dependency means you’ll need to resolve dependencies recursively. Prefer a DI container like PHP-DI and wrap it in an Illuminate\Container\Container adapter.
• Debug Tip: Enable Dispatcher::setLogCalls(true) to log all event dispatches via Laravel’s logger for tracing — invaluable when listener chains are complex.