Events & Listeners

What are events?

Laravel’s event system implements the observer pattern. When something notable happens in your application—an order ships, a user registers—you dispatch an event. One or more listeners respond to that event independently. This decouples your core business logic from side effects like sending emails or updating analytics. You can add, remove, or change listeners without touching the code that raised the event.

Generating events and listeners

Use Artisan to scaffold events and listeners:

php artisan make:event OrderShipped

php artisan make:listener SendShipmentNotification --event=OrderShipped

Running the commands without arguments prompts you interactively for names.

Registering events and listeners

Event discovery (automatic)

By default, Laravel scans app/Listeners automatically and registers any listener method that begins with handle or __invoke. The event it listens to is determined by the type-hint in the method signature:

use App\Events\OrderShipped;

class SendShipmentNotification
{
    /**
     * Handle the event.
     */
    public function handle(OrderShipped $event): void
    {
        // ...
    }
}

No manual registration needed. Cache the manifest before deploying to production:

php artisan event:cache

# Clear the cache
php artisan event:clear

Manual registration

use App\Events\OrderShipped;
use App\Listeners\SendShipmentNotification;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(
        OrderShipped::class,
        SendShipmentNotification::class,
    );
}

Closure listeners

use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(function (OrderShipped $event) {
        // ...
    });
}

Defining events

An event is a data container. It holds the information needed by listeners—nothing more:

<?php

namespace App\Events;

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

class OrderShipped
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(
        public Order $order,
    ) {}
}

SerializesModels ensures Eloquent models serialize correctly when the event is used with a queued listener.

Defining listeners

Listeners receive the event in their handle method. The service container injects any constructor dependencies automatically:

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use App\Services\ShipmentNotifier;

class SendShipmentNotification
{
    /**
     * Create the event listener.
     */
    public function __construct(
        protected ShipmentNotifier $notifier,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderShipped $event): void
    {
        $this->notifier->notify($event->order->user);
    }
}

Return false from handle to stop the event from propagating to other listeners.

Dispatching events

Call dispatch on the event class:

use App\Events\OrderShipped;

OrderShipped::dispatch($order);

Dispatch after the current database transaction commits, so listeners only run when the data is actually saved:

use App\Events\OrderShipped;

OrderShipped::dispatchAfterCommit($order);

Queued listeners

Listeners that send emails or call external APIs should run in the background. Implement ShouldQueue to push the listener onto the queue automatically:

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * The number of times the queued listener may be attempted.
     */
    public int $tries = 3;

    /**
     * Handle the event.
     */
    public function handle(OrderShipped $event): void
    {
        // Runs in a background queue worker...
    }

    /**
     * Handle a listener failure.
     */
    public function failed(OrderShipped $event, \Throwable $exception): void
    {
        // Clean up or notify on failure...
    }
}

Customize the queue connection and name:

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

Debouncing event listeners

When the same event is dispatched repeatedly for a short period, you may want to handle only the latest instance. Add the DebounceFor attribute to a queued listener to debounce events within the specified period:

<?php

namespace App\Listeners;

use App\Events\ProductUpdated;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\DebounceFor;

#[DebounceFor(30)]
class UpdateProductSearchIndex implements ShouldQueue
{
    public function handle(ProductUpdated $event): void
    {
        // Update the product's search index...
    }

    public function debounceId(ProductUpdated $event): string
    {
        return (string) $event->product->getKey();
    }
}

In this example, repeatedly dispatching ProductUpdated events for the same product within 30 seconds debounces the listener so that only the latest event is handled. Events with different debounce IDs are handled independently. To cap how long a frequently dispatched event can defer a listener, provide the maxWait argument:

#[DebounceFor(30, maxWait: 120)]
class UpdateProductSearchIndex implements ShouldQueue
{
    // ...
}

Customize the cache store used for debounce tracking with a debounceVia method. The method receives the event and should return a cache repository:

use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;

public function debounceVia(ProductUpdated $event): Repository
{
    return Cache::driver('redis');
}

Debounced and unique listeners are mutually exclusive. A listener using DebounceFor should not implement ShouldBeUnique. If events are dispatched from multiple web servers or containers, ensure they all use the same shared cache server.

Queueable closure listeners

Wrap a closure with queueable to run it on the queue:

use App\Events\OrderShipped;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;

Event::listen(queueable(function (OrderShipped $event) {
    // Runs in the background...
})->onQueue('notifications'));

Event subscribers

An event subscriber is a single class that handles multiple events. Implement a subscribe method and register the class:

<?php

namespace App\Listeners;

use App\Events\OrderPlaced;
use App\Events\OrderShipped;
use Illuminate\Events\Dispatcher;

class OrderEventSubscriber
{
    public function handleOrderPlaced(OrderPlaced $event): void
    {
        // ...
    }

    public function handleOrderShipped(OrderShipped $event): void
    {
        // ...
    }

    /**
     * Register the listeners for the subscriber.
     */
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(OrderPlaced::class, [self::class, 'handleOrderPlaced']);
        $events->listen(OrderShipped::class, [self::class, 'handleOrderShipped']);
    }
}

use App\Listeners\OrderEventSubscriber;
use Illuminate\Support\Facades\Event;

Event::subscribe(OrderEventSubscriber::class);

End-to-end example

Create the event

php artisan make:event OrderShipped

<?php

namespace App\Events;

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

class OrderShipped
{
    use Dispatchable, SerializesModels;

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

Create the listener

php artisan make:listener SendShipmentNotification --event=OrderShipped

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use App\Mail\OrderShippedMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;

class SendShipmentNotification implements ShouldQueue
{
    public function handle(OrderShipped $event): void
    {
        Mail::to($event->order->user->email)
            ->send(new OrderShippedMail($event->order));
    }
}

Dispatch from the controller

use App\Events\OrderShipped;
use App\Models\Order;

public function ship(Order $order): RedirectResponse
{
    $order->update(['shipped_at' => now()]);

    OrderShipped::dispatch($order);

    return redirect()->route('orders.show', $order);
}

Testing events

Fake all events to assert they were dispatched without triggering listeners:

Pest
PHPUnit

use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;

test('order can be shipped', function () {
    Event::fake();

    $order = Order::factory()->create();

    $this->post("/orders/{$order->id}/ship");

    Event::assertDispatched(OrderShipped::class, function ($event) use ($order) {
        return $event->order->id === $order->id;
    });
});

use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;

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

    $order = Order::factory()->create();

    $this->post("/orders/{$order->id}/ship");

    Event::assertDispatched(OrderShipped::class, function ($event) use ($order) {
        return $event->order->id === $order->id;
    });
}

Queues

Learn how to run queued listeners and background jobs at scale.

Architecture

Database

Eloquent

Security

Events

Mail and Notifications

Payments

Asynchronous Processing

Real-time Communication

Scheduling

Cache and Optimization

Internationalization

Files and Storage

Debugging and Monitoring

Console and CLI

Performance

Frontend

AI Development

Development Environment

What are events?

Generating events and listeners

Registering events and listeners

Event discovery (automatic)

Manual registration

Closure listeners

Defining events

Defining listeners

Dispatching events

Queued listeners

Debouncing event listeners

Queueable closure listeners

Event subscribers

End-to-end example

Testing events

Queues

​What are events?

​Generating events and listeners

​Registering events and listeners

​Event discovery (automatic)

​Manual registration

​Closure listeners

​Defining events

​Defining listeners

​Dispatching events

​Queued listeners

​Debouncing event listeners

​Queueable closure listeners

​Event subscribers

​End-to-end example

​Testing events

Queues

What are events?

Generating events and listeners

Registering events and listeners

Event discovery (automatic)

Manual registration

Closure listeners

Defining events

Defining listeners

Dispatching events

Queued listeners

Debouncing event listeners

Queueable closure listeners

Event subscribers

End-to-end example

Testing events