laravel-event-driven-architecture

Laravel Event-Driven Architecture

Event Class Structure

<?php

namespace App\Events;

use App\Models\Order;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class OrderPlaced
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public readonly Order $order,
    ) {}
}

Listener Class Structure

<?php

namespace App\Listeners;

use App\Events\OrderPlaced;

class SendOrderConfirmation
{
    public function handle(OrderPlaced $event): void
    {
        $event->order->user->notify(
            new OrderConfirmationNotification($event->order)
        );
    }
}

Automatic Listener Discovery

Laravel auto-discovers listeners when they are in the App\Listeners directory and have a handle method type-hinting an event. No manual registration needed.

// ✅ Auto-discovered - just create the class with a typed handle method
class SendOrderConfirmation
{
    public function handle(OrderPlaced $event): void { /* ... */ }
}

// ✅ One listener handling multiple events
class AuditLogger
{
    public function handleOrderPlaced(OrderPlaced $event): void { /* ... */ }
    public function handleOrderCancelled(OrderCancelled $event): void { /* ... */ }
}

// ❌ Won't be discovered - missing type hint
class SendOrderConfirmation
{
    public function handle($event): void { /* ... */ }
}

Dispatching Events

// ✅ Using static dispatch
OrderPlaced::dispatch($order);

// ✅ Using event helper
event(new OrderPlaced($order));

// ❌ Calling listeners directly instead of dispatching events
(new SendOrderConfirmation)->handle($order); // Tight coupling

Queued Listeners

use Illuminate\Contracts\Queue\ShouldQueue;

// ✅ Listener runs asynchronously on the queue
class GenerateInvoicePdf implements ShouldQueue
{
    public string $queue = 'invoices';
    public int $tries = 3;
    public array $backoff = [10, 60];

    public function handle(OrderPlaced $event): void
    {
        $pdf = PdfGenerator::fromOrder($event->order);
        Storage::put("invoices/{$event->order->id}.pdf", $pdf);
    }

    public function failed(OrderPlaced $event, \Throwable $exception): void
    {
        // Handle failure
    }

    // Conditionally handle
    public function shouldQueue(OrderPlaced $event): bool
    {
        return $event->order->total > 0;
    }
}