Laravel Events and Listeners: Internals, Queued Jobs & Production Patterns

<?php

// ─────────────────────────────────────────────────────────────
// 1. The Event — a plain PHP class, a value object.
//    It holds all the data that listeners will need.
//    No logic here. Think of it as a named payload.
// ─────────────────────────────────────────────────────────────
namespace App\Events;

use App\Models\User;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered
{
    use Dispatchable;     // adds the static ::dispatch() factory
    use SerializesModels; // safely serialises Eloquent models for queued listeners

    public function __construct(
        public readonly User $user,  // PHP 8 constructor promotion — clean and immutable
        public readonly string $registrationSource = 'web'
    ) {}
}

// ─────────────────────────────────────────────────────────────
// 2. Peek inside how Dispatcher resolves listeners.
//    You'd never write this yourself — it's to show the mechanism.
// ─────────────────────────────────────────────────────────────

// Internally, Illuminate\Events\Dispatcher holds a structure like:
// [
//   'App\Events\UserRegistered' => [
//       Closure (wraps SendWelcomeEmail::class),
//       Closure (wraps CreateDefaultWorkspace::class),
//   ]
// ]
//
// When you call event(new UserRegistered($user)), Dispatcher does:
//
//   foreach ($this->getListeners($eventName) as $listener) {
//       $response = $listener($event);          // call the listener
//       if ($response === false) break;         // halt propagation
//   }
//
// Each listener Closure is a wrapper that either:
//   a) Instantiates a class and calls handle(), OR
//   b) Queues a job (if the listener implements ShouldQueue)

// ─────────────────────────────────────────────────────────────
// 3. Dispatching the event — three equivalent ways.
// ─────────────────────────────────────────────────────────────

// Option A — via the Dispatchable trait (most expressive):
UserRegistered::dispatch($user, 'mobile-app');

// Option B — via the global helper (readable in controllers):
event(new UserRegistered($user, 'api'));

// Option C — via the facade (useful when you need the return values):
$responses = \Illuminate\Support\Facades\Event::dispatch(new UserRegistered($user));
// $responses is an array of return values from each listener.
// If any listener returned false, dispatch() returns false.
var_dump($responses); // array(2) { [0]=> NULL [1]=> NULL } — typical void listeners

<?php
// app/Providers/EventServiceProvider.php

namespace App\Providers;

use App\Events\UserRegistered;
use App\Events\OrderShipped;
use App\Listeners\SendWelcomeEmail;
use App\Listeners\CreateDefaultWorkspace;
use App\Listeners\NotifyAdminSlackChannel;
use App\Listeners\SendShipmentConfirmation;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Event;

class EventServiceProvider extends ServiceProvider
{
    /**
     * Explicit registration — the source of truth.
     * Laravel reads this during boot and calls Dispatcher::listen() for each pair.
     */
    protected $listen = [
        UserRegistered::class => [
            SendWelcomeEmail::class,        // queued — sends email async
            CreateDefaultWorkspace::class,  // queued — heavy DB work
            NotifyAdminSlackChannel::class, // queued — external HTTP call
        ],
        OrderShipped::class => [
            SendShipmentConfirmation::class,
        ],
    ];

    public function boot(): void
    {
        parent::boot();

        // Wildcard listener — catches every event whose name matches the pattern.
        // The first argument is the event name, second is the event object.
        // Use this for audit logging, debugging, or feature-flag interception.
        Event::listen('App\\Events\\*', function (string $eventName, array $eventPayload) {
            $event = $eventPayload[0]; // wildcard passes payload as an array
            \Log::channel('audit')->info('Event dispatched', [
                'event'      => $eventName,
                'user_id'    => auth()->id(),
                'ip_address' => request()->ip(),
                'timestamp'  => now()->toIso8601String(),
            ]);
        });
    }
}

// ─────────────────────────────────────────────────────────────
// A production-grade queued listener
// ─────────────────────────────────────────────────────────────
// app/Listeners/SendWelcomeEmail.php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeEmail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Support\Facades\Mail;
use Throwable;

class SendWelcomeEmail implements ShouldQueue
{
    use InteractsWithQueue; // gives access to $this->release(), $this->fail(), etc.

    /**
     * Push this listener onto the 'notifications' queue,
     * using the 'redis' connection specifically.
     * This keeps email jobs separate from heavy data-processing jobs.
     */
    public string $queue = 'notifications';
    public string $connection = 'redis';

    /**
     * Delay execution by 10 seconds — gives the DB transaction
     * that fired the event time to fully commit before we read the user.
     * This avoids a race condition where the email job runs before
     * the user row is visible to a replica database.
     */
    public int $delay = 10;

    /**
     * Maximum number of attempts before the job is marked as failed.
     */
    public int $tries = 3;

    /**
     * The handle method receives the fully hydrated event object.
     * SerializesModels means $event->user was re-fetched from the DB
     * at the moment this job started — always fresh data.
     */
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user->email)
            ->send(new WelcomeEmail($event->user, $event->registrationSource));
    }

    /**
     * Called after all retries are exhausted.
     * Use this to alert your team or write to a dead-letter log.
     */
    public function failed(UserRegistered $event, Throwable $exception): void
    {
        \Log::error('WelcomeEmail failed permanently', [
            'user_id'   => $event->user->id,
            'exception' => $exception->getMessage(),
        ]);

        // Optionally notify your on-call team via PagerDuty, Slack, etc.
    }
}

<?php
// ─────────────────────────────────────────────────────────────
// Pattern 1: ShouldDispatchAfterCommit on the Event class
// ─────────────────────────────────────────────────────────────
namespace App\Events;

use App\Models\Order;
use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class OrderPlaced implements ShouldDispatchAfterCommit
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public readonly Order $order
    ) {}
    // Laravel will NOT dispatch this event if the wrapping DB transaction
    // rolls back. No race condition. No phantom events.
}


// ─────────────────────────────────────────────────────────────
// Pattern 2: Using Event::fake() in feature tests
// ─────────────────────────────────────────────────────────────
namespace Tests\Feature;

use App\Events\UserRegistered;
use App\Events\OrderPlaced;
use App\Listeners\SendWelcomeEmail;
use App\Models\User;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;

class UserRegistrationTest extends TestCase
{
    public function test_user_registration_dispatches_correct_event(): void
    {
        // Fake ALL events — no listeners run, no emails sent.
        Event::fake();

        $response = $this->postJson('/api/register', [
            'name'     => 'Alice Nguyen',
            'email'    => 'alice@example.com',
            'password' => 'supersecret123',
        ]);

        $response->assertStatus(201);

        // Assert the right event was dispatched with the right payload.
        Event::assertDispatched(UserRegistered::class, function (UserRegistered $event) {
            return $event->user->email === 'alice@example.com'
                && $event->registrationSource === 'web';
        });

        // Assert a different event was NOT dispatched (guard against accidental fires).
        Event::assertNotDispatched(OrderPlaced::class);
    }

    public function test_only_fakes_specific_events_and_runs_others_normally(): void
    {
        // Fake ONLY UserRegistered — all other events fire for real.
        // Useful when you want to test a chain of events but isolate one.
        Event::fake([UserRegistered::class]);

        // ... your test actions ...

        Event::assertDispatched(UserRegistered::class);
    }

    public function test_queued_listener_is_registered_for_event(): void
    {
        Event::fake();

        UserRegistered::dispatch(User::factory()->make());

        // Assert that the listener is registered and would be queued.
        // This checks the listener CLASS is attached, not that it ran.
        Event::assertListening(
            UserRegistered::class,
            SendWelcomeEmail::class
        );
    }
}


// ─────────────────────────────────────────────────────────────
// Pattern 3: dispatchAfterResponse — fire and forget for UI events
// ─────────────────────────────────────────────────────────────
// In a controller action:
public function store(RegisterUserRequest $request): JsonResponse
{
    $user = $this->userService->register($request->validated());

    // The response is sent to the browser FIRST,
    // THEN UserRegistered is dispatched in the shutdown phase.
    // Great for reducing perceived latency on registration endpoints.
    UserRegistered::dispatchAfterResponse($user, 'web');

    return response()->json(['message' => 'Registration successful'], 201);
}

<?php
// ─────────────────────────────────────────────────────────────
// Event Subscriber — one class, multiple events, one registration.
// Ideal when a domain area (Orders) owns several related events.
// ─────────────────────────────────────────────────────────────
namespace App\Listeners;

use App\Events\OrderPlaced;
use App\Events\OrderShipped;
use App\Events\OrderCancelled;
use App\Models\Order;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Events\Dispatcher;

// ShouldQueue on a subscriber applies to ALL its listener methods.
class OrderEventSubscriber implements ShouldQueue
{
    public string $queue = 'orders';

    /**
     * Handle OrderPlaced: reserve inventory, charge the card.
     */
    public function handleOrderPlaced(OrderPlaced $event): void
    {
        $order = $event->order;

        // Each method stays focused on ONE responsibility.
        // Inventory reservation happens here; email happens elsewhere.
        \Log::info('Order placed, reserving inventory', ['order_id' => $order->id]);

        $order->items->each(function ($item) {
            $item->product->decrement('stock_quantity', $item->quantity);
        });
    }

    /**
     * Handle OrderShipped: notify the customer, update analytics.
     */
    public function handleOrderShipped(OrderShipped $event): void
    {
        $order = $event->order;

        \Log::info('Order shipped, sending tracking info', ['order_id' => $order->id]);
        // ... send tracking email, push to analytics ...
    }

    /**
     * Handle OrderCancelled: release reserved inventory, issue refund.
     */
    public function handleOrderCancelled(OrderCancelled $event): void
    {
        $order = $event->order;

        \Log::info('Order cancelled, releasing inventory', ['order_id' => $order->id]);

        $order->items->each(function ($item) {
            $item->product->increment('stock_quantity', $item->quantity);
        });
    }

    /**
     * subscribe() tells the Dispatcher which method handles which event.
     * This is called during boot — same timing as EventServiceProvider::$listen.
     *
     * The second argument to listen() is a priority integer.
     * We give handleOrderPlaced a higher priority (10) than the default (0)
     * to ensure inventory is reserved BEFORE fulfilment kicks off.
     */
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(
            OrderPlaced::class,
            [self::class, 'handleOrderPlaced'],
            10 // run before other OrderPlaced listeners
        );

        $events->listen(
            OrderShipped::class,
            [self::class, 'handleOrderShipped']
        );

        $events->listen(
            OrderCancelled::class,
            [self::class, 'handleOrderCancelled']
        );
    }
}

// ─────────────────────────────────────────────────────────────
// Register the subscriber in EventServiceProvider:
// ─────────────────────────────────────────────────────────────
// protected $subscribe = [
//     \App\Listeners\OrderEventSubscriber::class,
// ];


// ─────────────────────────────────────────────────────────────
// Performance diagnostic — run this in Tinker or an artisan command
// to see every registered listener and whether it's queued.
// ─────────────────────────────────────────────────────────────
$dispatcher = app('events');
$listeners  = $dispatcher->getRawListeners(); // returns the internal $listeners array

foreach ($listeners as $eventName => $listenerClosures) {
    echo sprintf(
        "%-60s %d listener(s)\n",
        $eventName,
        count($listenerClosures)
    );
}