Événements système¶

Le Gestionnaire d’Événement Global¶

En plus des gestionnaires au niveau des instances d’événement, CakePHP fournit un gestionnaire d’événements global qui vous permet d’écouter tout événement déclenché dans une application. C’est utile quand attacher des écouteurs à une instance spécifique semble lent ou difficile. Le gestionnaire global est une instance singleton de Cake\Event\EventManager qui reçoit chaque événement avant que les gestionnaires d’instance ne le reçoivent. En plus de recevoir les événements en premier, le gestionnaire global maintient aussi une pile de priorité distincte pour les écouteurs. Une fois qu’un événement a été dispatché au gestionnaire global, il sera dispatché au gestionnaire au niveau de l’instance. Vous pouvez accéder au gestionnaire global en utilisant une méthode statique:

// Dans tout fichier de configuration ou partie de code qui s'execute avant l'événement
use Cake\Event\EventManager;

EventManager::instance()->on(
    'Model.Order.afterPlace',
    $aCallback
);

Une chose importante que vous devriez considérer est que les événements qui seront attrapés auront le même nom mais des sujets différents, ainsi le vérifier dans l’objet event est habituellement nécessaire dans toute fonction qui devient attachée globalement afin d’éviter tout bug. Rappelez-vous que la flexibilité du gestionnaire global entraîne une complexité supplémentaire à gérer.

La méthode Cake\Event\EventManager::dispatch() accepte l’objet event en argument et notifie à tous les écouteurs et les callbacks qui passent cet objet. Les écouteurs vont gérer toute la logique supplémentaire autour de l’événement afterPlace, vous pouvez enregistrer l’horodatage dans les journaux, envoyer les emails, mettre à jour les statistiques d’un utilisateur, si possible dans des objets séparés et même le déléguer à des tâches offline si vous avez ce besoin.

Suivre la Trace des Événements¶

Pour garder une liste des événements qui sont déclenchés pour un EventManager en particulier, vous pouvez activer le tracking d’événements. Pour ce faire, attachez simplement une Cake\Event\EventList au gestionnaire:

EventManager::instance()->setEventList(new EventList());

Après avoir déclenché un événement sur le gestionnaire, vous pouvez le récupérer à partir de la liste d’événements:

$eventsFired = EventManager::instance()->getEventList();
$firstEvent = $eventsFired[0];

Le tracking peut être désactivé en retirant la liste d’événements ou en appelant Cake\Event\EventList::trackEvents(false)

Enregistrer des Écouteurs Anonymes¶

Alors que les objets listener d’événement sont généralement une meilleure façon d’intégrer des listeners, vous pouvez aussi lier tout callable comme un listener d’événement. Par exemple si nous souhaitons mettre toutes les commandes dans des fichiers de log, nous pourrions utiliser une simple fonction anonyme pour le faire:

use Cake\Log\Log;

$this->Orders->eventManager()->on('Model.Orders.afterPlace', function ($event) {
    Log::write(
        'info',
        'A new order was placed with id: ' . $event->getSubject()->id
    );
});

En plus des fonctions anonymes, vous pouvez utiliser tout autre type callable que PHP supporte:

$events = [
    'email-sending' => 'EmailSender::sendBuyEmail',
    'inventory' => [$this->InventoryManager, 'decrement'],
];
foreach ($events as $callable) {
    $eventManager->on('Model.Orders.afterPlace', $callable);
}

Quand vous travaillez avec des plugins qui ne déclenchent pas d’événement spécifique, vous pouvez utiliser les listeners d’événements sur les événements utilisés par défaut. Prenons un exemple d’un plugin “UserFeedback” qui gère les formulaires de feedback des utilisateurs. A partir de votre application, vous voudrez savoir quand un enregistrement Feedback a été enregistré et en définitive agir sur lui. Vous pourriez écouter l’événement global Model.afterSave. Cependant, vous pouvez utiliser une approche plus directe et écouter seulement l’événement dont vous avez réellement besoin:

// Vous pouvez créer ce qui suit avant l'opération de sauvegarde
// par exemple dans config/bootstrap.php
use Cake\ORM\TableRegistry;
// Si envoi d'emails
use Cake\Mailer\Email;

// Prior to 3.6 use TableRegistry::get('ThirdPartyPlugin.Feedbacks')
TableRegistry::getTableLocator()->get('ThirdPartyPlugin.Feedbacks')
    ->eventManager()
    ->on('Model.afterSave', function($event, $entity)
    {
        // Par exemple nous pouvons envoyer un email à l'admin
        // Avant 3.4, utilisez les méthodes from()/to()/subject()
        $email = new Email('default');
        $email->setFrom(['[email protected]' => 'Your Site'])
            ->setTo('[email protected]')
            ->setSubject('New Feedback - Your Site')
            ->send('Body of message');
    });

Vous pouvez utiliser cette même approche pour lier les objets listener.

Interagir avec les Listeners Existants¶

En supposant que plusieurs écouteurs d’événements ont été enregistrés, la présence ou l’absence d’un modèle d’événements particulier peut être utilisé comme base de certaines actions:

// Attacher les écouteurs au EventManager.
$this->eventManager()->on('User.Registration', [$this, 'userRegistration']);
$this->eventManager()->on('User.Verification', [$this, 'userVerification']);
$this->eventManager()->on('User.Authorization', [$this, 'userAuthorization']);

// Quelque part ailleurs dans votre application.
$events = $this->eventManager()->matchingListeners('Verification');
if (!empty($events)) {
    // Perform logic related to presence of 'Verification' event listener.
    // For example removing the listener if present.
    $this->eventManager()->off('User.Verification');
} else {
    // Logique liée à l'absence de l'écouteur d'événement 'Verification'
}

Etablir des Priorités¶

Dans certains cas vous voulez contrôler la commande que les listeners appellent. Par exemple, si nous retournons à notre exemple des statistiques d’utilisateur. Ce serait idéal si le listener était appelé à la fin de la pile. En l’appelant à la fin de la pile, nous pouvons assurer que l’événement n’a pas été annulé et qu’aucun autre listener ne lève d’exception. Nous pouvons aussi obtenir l’état final des objets dans le cas où d’autres listeners ont modifié le sujet ou l’objet event.

Les priorités sont définies comme un nombre entier lors de l’ajout d’un listener. Plus le nombre est haut, plus la méthode sera lancée tardivement. La priorité par défaut pour tous les listeners est 10. Si vous avez besoin que votre méthode soit lancée plus tôt, en utilisant toute valeur avant que celle par défaut ne fonctionne. D’un autre côté, si vous souhaitez lancer le callback après les autres, utiliser un nombre au-dessus de 10 le fera.

Si deux callbacks ont la même valeur de priorité, elles seront exécutées selon l’ordre dans lequel elles ont été attachées. Vous définissez les priorités en utilisant la méthode on pour les callbacks et en la déclarant dans la fonction implementedEvents() pour les listeners d’événement:

// Définir la priorité pour un callback
$callback = [$this, 'doSomething'];
$this->eventManager()->on(
    'Model.Orders.afterPlace',
    ['priority' => 2],
    $callback
);

// Définir la priorité pour un listener
class UserStatistic implements EventListener
{
    public function implementedEvents()
    {
        return [
            'Model.Orders.afterPlace' => [
                'callable' => 'updateBuyStatistic',
                'priority' => 100
            ],
        ];
    }
}

Comme vous le voyez, la principale différence pour les objets EventListener est que vous avez besoin d’utiliser un tableau pour spécifier la méthode callable et la préférence de priorité. La clé callable est une entrée de tableau spécial que le gestionnaire va lire pour savoir quelle fonction dans la classe il doit appeler.

Obtenir des Données d’Event en Paramètres de Fonction¶

Quand les événements ont des données fournies dans leur constructeur, les données fournies sont converties en arguments pour les listeners. Un exemple de la couche View est la callback afterRender:

$this->eventManager()
    ->dispatch(new Event('View.afterRender', $this, ['view' => $viewFileName]));

Les listeners de la callback View.afterRender doivent avoir la signature suivante:

function (Event $event, $viewFileName)

Chaque valeur fournie au constructeur d’Event sera convertie dans les paramètres de fonction afin qu’ils apparaissent dans le tableau de données. Si vous utilisez un tableau associatif, les résultats de array_values vont déterminer l’ordre des arguments de la fonction.

Stopper les Events¶

Un peu comme les événements DOM, vous voulez peut-être stopper un événement pour éviter aux autres listeners d’être notifiés. Vous pouvez voir ceci pendant les callbacks de mode(par ex beforeSave) dans lesquels il est possible de stopper l’opération de sauvegarde si le code détecte qu’il ne peut pas continuer.

Afin de stopper les événements, vous pouvez soit retourner false dans vos callbacks ou appeler la méthode stopPropagation() sur l’objet event:

public function doSomething($event)
{
    // ...
    return false; // stoppe l'event
}

public function updateBuyStatistic($event)
{
    // ...
    $event->stopPropagation();
}

Stopper un événement va éviter à toute callback supplémentaire d’être appelée. En plus, le code attrapant l’événement peut se comporter différemment selon que l’événement est stoppé ou non. Généralement il n’est pas sensé stopper “après” les événements, mais stopper “avant” les événements est souvent utilisé pour empêcher toutes les opérations de se passer.

Pour vérifier si un événement a été stoppé, vous appelez la méthode isStopped() dans l’objet event:

public function place($order)
{
    $event = new Event('Model.Orders.beforePlace', $this, ['order' => $order]);
    $this->eventManager()->dispatch($event);
    if ($event->isStopped()) {
        return false;
    }
    if ($this->Orders->save($order)) {
        // ...
    }
    // ...
}

Dans l’exemple précédent, la commande ne serait pas sauvegardée si l’événement est stoppé pendant le processus beforePlace.

Obtenir des Résultats d’Evenement¶

A chaque fois qu’un callback retourne une valeur non nulle et non false, elle sera stockée dans la propriété $result de l’objet event. C’est utile quand vous voulez permettre aux callbacks de modifier l’exécution de l’événement. Prenons à nouveau notre exemple beforePlace et laissons les callbacks modifier la donnée $order.

Les résultats d’Event peuvent être modifiés soit en utilisant directement la propriété de résultat de l’objet event, soit en retournant la valeur dans le callback elle-même:

// Un callback listener
public function doSomething($event)
{
    // ...
    $alteredData = $event->getData('order') + $moreData;
    return $alteredData;
}

// Un autre callback listener
public function doSomethingElse($event)
{
    // ...
    $event->setResult(['order' => $alteredData] + $this->result());
}

// Utiliser les résultats d'event
public function place($order)
{
    $event = new Event('Model.Orders.beforePlace', $this, ['order' => $order]);
    $this->eventManager()->dispatch($event);
    if (!empty($event->getResult()['order'])) {
        $order = $event->getResult()['order'];
    }
    if ($this->Orders->save($order)) {
        // ...
    }
    // ...
}

Il est possible de modifier toute propriété d’un objet event et d’avoir les nouvelles données passées à la prochaine callback. Dans la plupart des cas, fournir des objets en données d’event ou en résultat et directement modifier l’objet est la meilleure solution puisque la référence est la même et les modifications sont partagées à travers tous les appels de callback.

Retirer les Callbacks et les Listeners¶

Si pour certaines raisons, vous voulez retirer toute callback d’un gestionnaire d’événements, appelez seulement la méthode Cake\Event\EventManager::off() en utilisant des arguments les deux premiers paramètres que vous utilisiez pour l’attacher:

// Attacher une fonction
$this->eventManager()->on('My.event', [$this, 'doSomething']);

// Détacher une fonction
$this->eventManager()->off([$this, 'doSomething']);

// Attacher une fonction anonyme.
$myFunction = function ($event) { ... };
$this->eventManager()->on('My.event', $myFunction);

// Détacher la fonction anonyme
$this->eventManager()->off('My.event', $myFunction);

// Attacher un EventListener
$listener = new MyEventLister();
$this->eventManager()->on($listener);

// Détacher une clé d'événement unique d'un listener
$this->eventManager()->off('My.event', $listener);

// Détacher tous les callbacks intégrés par un listener
$this->eventManager()->off($listener);

Les événements sont une bonne façon de séparer les préoccupations dans votre application et rend les classes à la fois cohérentes et découplées des autres, néanmoins l’utilisation des événements n’est pas la solution à tous les problèmes. Les Events peuvent être utilisés pour découpler le code de l’application et rendre les plugins extensibles.

Gardez à l’esprit que beaucoup de pouvoir implique beaucoup de responsabilité. Utiliser trop d’événements peut rendre le debug plus difficile et nécessiter des tests d’intégration supplémentaires.