Événements et listeners

Qu’est-ce qu’un événement

Le système d’événements de Laravel implémente le pattern observateur. Vous déclenchez des « événements » représentant des faits survenus dans l’application, et des listeners y réagissent, ce qui minimise les dépendances entre composants. Par exemple, un événement « commande validée » peut déclencher indépendamment « envoyer l’e-mail de confirmation », « décrémenter le stock » et « notifier Slack ». Le code de la commande ignore complètement l’implémentation de l’envoi de mails ou de Slack.

Les classes d’événement vont dans app/Events, les listeners dans app/Listeners. Ces dossiers sont créés automatiquement par les commandes Artisan.

Générer événements et listeners

Utilisez make:event et make:listener.

php artisan make:event UserRegistered

php artisan make:listener SendWelcomeEmail --event=UserRegistered

Sans arguments, la commande est interactive.

php artisan make:event

php artisan make:listener

Enregistrement des listeners

Auto-discovery

Par défaut, Laravel scanne app/Listeners et enregistre les listeners. La classe/méthode handle ou __invoke est inspectée : le type de son argument détermine l’événement écouté.

use App\Events\UserRegistered;

class SendWelcomeEmail
{
    public function handle(UserRegistered $event): void
    {
        // Envoi de l'e-mail de bienvenue
    }
}

Un type union PHP permet de gérer plusieurs événements dans la même méthode.

public function handle(UserRegistered|UserUpdated $event): void
{
    // ...
}

Pour des listeners hors de ce dossier, ajoutez des chemins de scan dans bootstrap/app.php.

->withEvents(discover: [
    __DIR__.'/../app/Domain/Orders/Listeners',
])

Wildcards autorisés :

->withEvents(discover: [
    __DIR__.'/../app/Domain/*/Listeners',
])

Liste des listeners enregistrés :

php artisan event:list

En production, mettez le manifest en cache : php artisan optimize ou php artisan event:cache. Videz-le avec php artisan event:clear.

Enregistrement manuel

Via Event dans AppServiceProvider::boot.

use App\Events\UserRegistered;
use App\Listeners\SendWelcomeEmail;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(
        UserRegistered::class,
        SendWelcomeEmail::class,
    );
}

Ou via closure.

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

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

Définir un événement

Une classe d’événement n’est qu’un conteneur de données. Elle porte les informations liées à l’événement, sans logique.

<?php

namespace App\Events;

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

class UserRegistered
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public User $user,
    ) {}
}

Le trait SerializesModels garantit une bonne sérialisation des modèles Eloquent quand le listener est en file.

Déclencher un événement

Utilisez la méthode statique dispatch ou le helper event().

use App\Events\UserRegistered;

// Statique
UserRegistered::dispatch($user);

// Helper
event(new UserRegistered($user));

Il existe aussi les variantes conditionnelles.

UserRegistered::dispatchIf($condition, $user);

UserRegistered::dispatchUnless($condition, $user);

Après la commit d’une transaction

Pour ne dispatcher qu’après commit d’une transaction, implémentez ShouldDispatchAfterCommit. En cas de rollback, l’événement est ignoré.

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered implements ShouldDispatchAfterCommit
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public User $user,
    ) {}
}

Implémenter un listener

La méthode handle reçoit l’événement. Le constructeur peut recevoir des dépendances via le conteneur.

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail
{
    public function __construct() {}

    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user->email)
            ->send(new WelcomeMail($event->user));
    }
}

Retourner false depuis handle interrompt la propagation aux listeners suivants.

Listeners en file (queued)

Pour les traitements longs (mail, HTTP…), exécutez le listener en asynchrone. Implémentez ShouldQueue : Laravel enfile automatiquement le listener lors du dispatch.

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        // Exécuté en asynchrone par le worker
    }
}

Nécessite la configuration de la queue et le démarrage d’un worker. Voir Queues et jobs.

Debounce des listeners

Lorsqu’un même événement est déclenché de nombreuses fois dans un court intervalle, il peut être souhaitable de ne traiter que le dernier événement. En ajoutant l’attribut DebounceFor à un listener en file d’attente, vous pouvez regrouper les événements sur une période donnée.

<?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
    {
        // Met à jour l'index de recherche des produits
    }

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

Dans cet exemple, si des événements ProductUpdated sont émis à répétition sur un même produit pendant 30 secondes, le listener est « debounced » et seul le dernier événement est traité. Les événements avec un debounceId différent sont traités indépendamment. Pour limiter la durée maximale pendant laquelle des événements très fréquents peuvent différer l’exécution du listener, précisez maxWait.

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

Vous pouvez changer le store de cache utilisé pour suivre le debounce via la méthode debounceVia, qui reçoit l’événement.

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

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

Les listeners debouncés et les listeners uniques ne sont pas combinables. N’implémentez pas ShouldBeUnique sur un listener qui utilise l’attribut DebounceFor. Lorsque les événements sont déclenchés depuis plusieurs serveurs web ou conteneurs, configurez tous les serveurs pour utiliser le même serveur de cache partagé.

Personnaliser connexion, queue et délai

Utilisez les attributs PHP.

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Delay;
use Illuminate\Queue\Attributes\Queue;

#[Connection('redis')]
#[Queue('emails')]
#[Delay(10)]
class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        // ...
    }
}

Ou via des méthodes dynamiques.

public function viaConnection(): string
{
    return 'redis';
}

public function viaQueue(): string
{
    return 'emails';
}

public function withDelay(UserRegistered $event): int
{
    return 10;
}

Nombre max d’essais et timeout

use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;

#[Tries(3)]
#[Timeout(30)]
class SendWelcomeEmail implements ShouldQueue
{
    // ...
}

Gestion des échecs

La méthode failed est appelée après épuisement des tentatives.

use Throwable;

public function failed(UserRegistered $event, Throwable $exception): void
{
    // Notifier un administrateur, par exemple
}

Souscripteurs d’événements

Un souscripteur regroupe plusieurs handlers dans une même classe.

Créer un souscripteur

subscribe renvoie la table événement → handler.

<?php

namespace App\Listeners;

use Illuminate\Auth\Events\Login;
use Illuminate\Auth\Events\Logout;
use Illuminate\Events\Dispatcher;

class UserActivitySubscriber
{
    public function handleLogin(Login $event): void
    {
        // Login
    }

    public function handleLogout(Logout $event): void
    {
        // Logout
    }

    /**
     * @return array<string, string>
     */
    public function subscribe(Dispatcher $events): array
    {
        return [
            Login::class => 'handleLogin',
            Logout::class => 'handleLogout',
        ];
    }
}

Enregistrement

Avec l’auto-discovery, les souscripteurs retournant un tableau sont enregistrés automatiquement. Sinon, dans AppServiceProvider::boot, appelez Event::subscribe.

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

public function boot(): void
{
    Event::subscribe(UserActivitySubscriber::class);
}

Exemple : e-mail de bienvenue à l’inscription

Créer l'événement

php artisan make:event UserRegistered

Ajoutez une propriété pour l’utilisateur.

<?php

namespace App\Events;

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

class UserRegistered
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public User $user,
    ) {}
}

Créer le listener

php artisan make:listener SendWelcomeEmail --event=UserRegistered

Implémentez ShouldQueue pour un envoi asynchrone.

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user->email)
            ->send(new WelcomeMail($event->user));
    }
}

Dispatcher l'événement depuis le contrôleur

Après la création de l’utilisateur.

<?php

namespace App\Http\Controllers\Auth;

use App\Events\UserRegistered;
use App\Models\User;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class RegisterController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $user = User::create($request->validated());

        UserRegistered::dispatch($user);

        return redirect('/dashboard');
    }
}

RegisterController ignore l’implémentation de l’envoi de mail. Ajouter plus tard un « notifier Slack » ne modifie pas le contrôleur.

Démarrer un worker

Pour traiter les listeners en file.

php artisan queue:work

Avec l’auto-discovery, aucun enregistrement manuel n’est requis dans AppServiceProvider.

Vérifiez régulièrement php artisan event:list pour détecter d’éventuels listeners inattendus.

Architecture

Base de données

Eloquent

Sécurité

Événements

E-mails et notifications

Paiements

Traitement asynchrone

Communication temps réel

Planification

Cache et optimisation

Internationalisation

Fichiers et stockage

Débogage et supervision

Console et CLI

Performance

Frontend

Développement IA

Environnement de développement

Qu’est-ce qu’un événement

Générer événements et listeners

Enregistrement des listeners

Auto-discovery

Enregistrement manuel

Définir un événement

Déclencher un événement

Après la commit d’une transaction

Implémenter un listener

Listeners en file (queued)

Debounce des listeners

Personnaliser connexion, queue et délai

Nombre max d’essais et timeout

Gestion des échecs

Souscripteurs d’événements

Créer un souscripteur

Enregistrement

Exemple : e-mail de bienvenue à l’inscription

​Qu’est-ce qu’un événement

​Générer événements et listeners

​Enregistrement des listeners

​Auto-discovery

​Enregistrement manuel

​Définir un événement

​Déclencher un événement

​Après la commit d’une transaction

​Implémenter un listener

​Listeners en file (queued)

​Debounce des listeners

​Personnaliser connexion, queue et délai

​Nombre max d’essais et timeout

​Gestion des échecs

​Souscripteurs d’événements

​Créer un souscripteur

​Enregistrement

​Exemple : e-mail de bienvenue à l’inscription

Qu’est-ce qu’un événement

Générer événements et listeners

Enregistrement des listeners

Auto-discovery

Enregistrement manuel

Définir un événement

Déclencher un événement

Après la commit d’une transaction

Implémenter un listener

Listeners en file (queued)

Debounce des listeners

Personnaliser connexion, queue et délai

Nombre max d’essais et timeout

Gestion des échecs

Souscripteurs d’événements

Créer un souscripteur

Enregistrement

Exemple : e-mail de bienvenue à l’inscription