Laravel Events — Phantom Emails on Failed Registrations

<?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
{\n    use Dispatchable;     // adds the static ::dispatch() factory\n    use SerializesModels; // safely serialises Eloquent models for queued listeners\n\n    public function __construct(\n        public readonly User $user,  // PHP 8 constructor promotion — clean and immutable\n        public readonly string $registrationSource = 'web'\n    ) {}
}

// ─────────────────────────────────────────────────────────────
// 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:
// [\n//   'App\\\Events\\\UserRegistered' => [\n//       Closure (wraps SendWelcomeEmail::class),\n//       Closure (wraps CreateDefaultWorkspace::class),\n//   ]
// ]
//
// 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 => [\n            SendShipmentConfirmation::class,\n        ],
    ];

    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', [\n                'event'      => $eventName,\n                'user_id'    => auth()->id(),\n                'ip_address' => request()->ip(),\n                'timestamp'  => now()->toIso8601String(),\n            ]);
        });
    }
}

// ─────────────────────────────────────────────────────────────
// 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', [\n            'user_id'   => $event->user->id,\n            'exception' => $exception->getMessage(),\n        ]);

        // 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(\n        public readonly Order $order\n    ) {}
    // 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', [\n            'name'     => 'Alice Nguyen',\n            'email'    => 'alice@example.com',\n            'password' => 'supersecret123',\n        ]);

        $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(\n            UserRegistered::class,\n            SendWelcomeEmail::class\n        );
    }
}


// ─────────────────────────────────────────────────────────────
// 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(\n            OrderShipped::class,\n            [self::class, 'handleOrderShipped']\n        );

        $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)
    );
}

<?php
// ─────────────────────────────────────────────────────────────
// Option 1: Using $dispatchesEvents to map to custom events
// ─────────────────────────────────────────────────────────────
namespace App\Models;

use App\Events\UserCreated;
use App\Events\UserUpdated;
use App\Events\UserDeleted;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $dispatchesEvents = [
        'created' => UserCreated::class,   // after the model is persisted
        'updated' => UserUpdated::class,   // after an existing model is updated
        'deleted' => UserDeleted::class,   // after a model is soft-deleted or hard-deleted
    ];
    // Now whenever User::create() completes, it dispatches UserCreated event.
}

// ─────────────────────────────────────────────────────────────
// Option 2: Using an Observer (cleaner for multiple event handlers)
// ─────────────────────────────────────────────────────────────
namespace App\Observers;

use App\Models\User;
use Illuminate\Support\Facades\Log;

class UserObserver
{
    /**
     * Handle the User "creating" event.
     * This fires before the model is saved. Return false to abort creation.
     */
    public function creating(User $user): void
    {
        // Enforce invariant: reject banned email domains
        $bannedDomains = ['tempmail.com', 'throwaway.com'];
        $domain = substr(strrchr($user->email, '@'), 1);
        if (in_array($domain, $bannedDomains)) {
            throw new \InvalidArgumentException("Email domain $domain is not allowed.");
        }
    }

    /**
     * Handle the User "created" event.
     * This fires after the model is successfully saved.
     * Avoid heavy I/O here — dispatch a custom event instead.
     */
    public function created(User $user): void
    {
        // Log the creation, but do NOT send email here directly.
        Log::info('User created', ['user_id' => $user->id, 'email' => $user->email]);

        // Dispatch custom event so listeners can handle async side effects
        \App\Events\UserCreated::dispatch($user);
    }

    /**
     * Handle the User "deleting" event.
     * Runs before deletion. Can return false to prevent deletion.
     */
    public function deleting(User $user): void
    {
        // Prevent deletion of admin accounts
        if ($user->isAdmin()) {
            return false; // stops the delete
        }
    }

    /**
     * Handle the User "retrieved" event.
     * Fires whenever a model is fetched from the database.
     * Use for caching or transforming attributes.
     */
    public function retrieved(User $user): void
    {
        // Automatically set a computed attribute
        $user->full_name = trim($user->first_name . ' ' . $user->last_name);
    }
}

// Register the observer in a service provider's boot method:
// \App\Models\User::observe(\App\Observers\UserObserver::class);

<?php
// ─────────────────────────────────────────────────────────────
// Listener that only queues for VIP users
// ─────────────────────────────────────────────────────────────
namespace App\Listeners;

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

class SendWelcomeEmail implements ShouldQueue
{
    use InteractsWithQueue;

    public string $queue = 'emails';
    public int $tries = 3;

    /**
     * Decide whether to queue this listener based on the user's subscription level.
     * Only premium users get the queued email; basic users get a synchronous email.
     */
    public function shouldQueue(UserRegistered $event): bool
    {
        // Only queue for VIP users (premium or enterprise plans)
        return in_array($event->user->subscription_tier, ['premium', 'enterprise']);
    }

    /**
     * Handle the event - this runs either synchronously or via queue
     * depending on shouldQueue()'s return value.
     */
    public function handle(UserRegistered $event): void
    {
        if ($event->user->subscription_tier === 'premium') {
            Mail::to($event->user->email)->send(new WelcomePremiumEmail($event->user));
        } else {
            Mail::to($event->user->email)->send(new WelcomeBasicEmail($event->user));
        }
    }

    public function failed(UserRegistered $event, Throwable $exception): void
    {\n        \\\Log::error('Welcome email failed', [\n            'user_id' => $event->user->id,\n            'tier' => $event->user->subscription_tier,\n        ]);\n    }
}

// ─────────────────────────────────────────────────────────────
// Alternative: Using shouldQueue to skip queue for specific event payloads
// ─────────────────────────────────────────────────────────────
class AuditLogListener implements ShouldQueue
{
    public function shouldQueue($event): bool
    {
        // Don't queue audit logs for read-only events (like 'retrieved')
        // This assumes the event has a $action property.
        if (property_exists($event, 'action') && $event->action === 'read') {
            return false; // run synchronously
        }
        return true;
    }

    public function handle($event): void
    {
        // Write audit log entry
    }
}

<?php
// ─────────────────────────────────────────────────────────────
// Listener with advanced retry configuration
// ─────────────────────────────────────────────────────────────
namespace App\Listeners;

use App\Events\OrderPlaced;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\Middleware\RateLimitedWithRedis;
use Illuminate\Support\Facades\Log;
use Throwable;

class ProcessOrderPayment implements ShouldQueue
{
    use InteractsWithQueue;

    public string $queue = 'payments';
    public string $connection = 'redis';

    /**
     * Retry up to 5 times before calling failed().
     */
    public int $tries = 5;

    /**
     * Exponential backoff in seconds between retries.
     */
    public array $backoff = [10, 30, 60, 120];

    /**
     * Only retry if the exception count is below this limit.
     * Uses the exception count from the job's attempts.
     */
    public int $maxExceptions = 3;

    /**
     * Alternatively, define a retryUntil method:
     */
    // public function retryUntil(): Carbon
    // {
    //     return now()->addMinutes(5); // job will not retry after 5 minutes
    // }

    /**
     * Middleware for rate limiting external API calls.
     */
    public function middleware(): array
    {
        return [
            new RateLimitedWithRedis('payment-gateway')
        ];
    }

    public function handle(OrderPlaced $event): void
    {
        // Attempt to process payment
        // If the payment gateway is down, throw an exception
        // The job will be retried with backoff
        $paymentService = app(PaymentService::class);
        $paymentService->charge($event->order->total, $event->order->paymentToken);
    }

    /**
     * Called after all retry attempts exhausted.
     * This is your last chance to do something — log, alert, or push to a dead-letter store.
     */
    public function failed(OrderPlaced $event, Throwable $exception): void
    {
        Log::critical('Payment processing failed after all retries', [\n            'order_id'  => $event->order->id,\n            'exception' => $exception->getMessage(),\n        ]);

        // Send a Slack notification to the on-call engineer
        // Or change the order status to 'payment_failed'
        $event->order->update(['status' => 'payment_failed']);
    }
}

// ─────────────────────────────────────────────────────────────
// Check failed jobs via artisan:
// php artisan queue:failed
// php artisan queue:retry all (retries all failed jobs)
// php artisan queue:forget 5 (forgets a specific failed job)

// View failed jobs table:
// SELECT * FROM failed_jobs;