Travailler avec les events Laravel

Quand j'ai commencé à développer pour le Joomla CMS (c'était il y a 15 ans, en 2009), l'une des choses que j'ai le plus appréciées était la notion d'events.

Par exemple Un article est sur le point d'être publié, Un article a été publié, Un utilisateur s'est enregistré : ce sont des actions annoncées par le CMS et auxquelles vous pouvez réagir.

Quand Un article est sur le point d'être affiché est généré, vous pouvez avoir un (ou plusieurs) morceaux de code qui interagissent avec cet event. Vous pouvez ajouter du contenu dynamique, vous pouvez aussi empêcher l'affichage de l'article si certaines conditions ne sont pas remplies.

Ce qu'un event vous apporte concrètement​

Voici une route Laravel qui crée un employé et affiche son nom. Un listener est branché sur l'event qu'elle déclenche :

$ curl localhost

FIRSTNAME is Georges
NAME      is Washington
PSEUDO    is cavo789
▋

Maintenant exactement la même route, avec ce listener commenté. Même URL, même code appelant, pas une ligne changée dans le controller :

$ curl localhost

FIRSTNAME is John
NAME      is Doe
PSEUDO    is cavo789
▋

L'employé retrouve son nom par défaut, et rien n'a planté. C'est toute la promesse des events : une fonctionnalité peut être ajoutée ou retirée sans que le code qui déclenche l'event en sache quoi que ce soit.

Pourquoi ça fonctionne​

1. La route crée un nouvel employee basé sur la classe Employee, puis déclenche un SampleEvent qui transporte cet objet.
2. Tout listener enregistré reçoit l'event et, à travers lui, ce même objet employé ; il peut le modifier.
3. La route affiche ensuite le prénom et le nom de l'employé, sans jamais savoir si un listener a fait quelque chose ou non.

La mise en place​

Quatre petits fichiers et une ligne de câblage. Suivons le flux, en commençant par le point d'entrée.

Pour notre exemple, votre routes/web.php peut ressembler à ceci :

Cette classe va initialiser notre employé et fournir un setter et un getter. Par défaut, notre employé s'appellera John Doe (cavo789).

Notre event va recevoir un employé et le stocker dans une propriété privée :

La logique de notre listener. SampleListener va recevoir le SampleEvent en paramètre et, donc, a accès à toutes ses méthodes publiques. Nous allons ici mettre à jour le prénom et le nom, mais pas le pseudo :

<?php

namespace App\Listeners;?

use App\Events\SampleEvent;

class SampleListener
{
    public function handle(SampleEvent $event): void?
    {
        $event->setFirstName('Georges')->setLastName('Washington');?
    }
}

Et enfin le câblage, c'est-à-dire le fichier qui dit à Laravel quel listener répond à quel event :

Pour reproduire le second terminal montré en haut de cet article, commentez le listener dans ce fichier :

Sous le capot (passez cette section si vous voulez juste l'utiliser)​

Les trois setters de l'event sont publics volontairement : c'est la seule raison pour laquelle un listener, qui vit dans un fichier totalement différent, a le droit de mettre à jour le prénom et le nom.

Le pseudo, lui, est seulement initialisé et jamais mis à jour par le listener ; c'est la partie de l'objet qui reste sous le contrôle du code qui a déclenché l'event. Décider ce qu'un listener peut toucher ou pas, c'est exactement le travail de conception qu'une classe d'event vous demande.

La même idée en dehors de Laravel​

Les events ne sont pas une invention de Laravel. En PHP pur, la librairie League\Event (https://event.thephpleague.com/) vous donne le même couple dispatcher/listener, sans aucun framework.

Conclusion​

Tout se résume aux deux sorties de terminal du début : une fonctionnalité a été retirée et le code appelant ne s'en est pas aperçu. Écrivez des events même dans votre propre code, même quand vous êtes sûr de savoir quoi en faire, parce que dans deux ans, quelqu'un (probablement vous) voudra y brancher quelque chose.

Les events sont, par nature, invisibles : ils sont déclenchés quelque part et quelque chose se passe ailleurs. Laravel Telescope les rend à nouveau visibles, ce qui aide vraiment pour déboguer une application découplée comme celle-ci.