Événements et Hooks plugin

Aperçu

Elgg a un événement système qui peut être utilisé pour remplacer ou étendre les fonctionnalités du noyau.

Les plugins influencent le système en créant des gestionnaires ou handlers (appelables tels que des fonctions et des méthodes) et en les enregistrant pour gérer deux types d’événements : les événements Événements Elgg Events et les hooks plugin Hooks plugin.

Quand un événement est déclenché, un jeu des gestionnaires est exécuté par ordre de priorité. Les arguments sont passés à chaque gestionnaire qui peut ainsi influencer le processus. Après exécution, la fonction déclencheuse « trigger » retourne une valeur qui dépend du comportement des gestionnaires.

Voir aussi

• Liste des événements dans le noyau

• Liste des hooks plugin du noyau

Événements Elgg Events vs. Hooks Plugin

Les principales différences entre les événements Événements Elgg Events et les hooks plugin Hooks plugin sont :

1. La majorité des événements Elgg peuvent être annulés ; à moins que l’événement soit un événement « after », un gestionnaire qui retourne false peut annuler l’événement, et plus aucun autre gestionnaire ne sera appelé.

2. Les hooks plugin ne peuvent pas être annulés ; tous les gestionnaires sont toujours appelés.

3. Les hooks plugin passent une valeur arbitraire à travers les gestionnaires, leur donnant à chacun une chance de la modifier en cours de route.

Événements Elgg Events

Les événements Elgg Events sont déclenchés quand un objet Elgg est créé, modifié ou supprimé ; et à différentes étapes importantes du chargement du framework Elgg. Exemples : lors de la création d’un article de blog ou de l’identification d’un utilisateur.

Contrairement aux Hooks plugin, la plupart des événements Elgg peuvent être annulés, ce qui interrompt l’exécution des gestionnaires, et potentiellement annulent certaines actions dans le noyau de Elgg.

Chaque événement Elgg a un nom et un type d’objet (system, user, object, nom de relation, annotation, group) qui décrit le type d’objet passé aux gestionnaires.

Événements antérieurs « Before » et postérieurs « After »

Certains événements sont séparés en « before » -avant- et « after » -après-. Ceci évite la confusion autour de l’état du système en cours de modification. Par ex. Est-ce que l’utilisateur est identifié au cours de l’événement [login, user] ?

Les événements antérieurs « Before » ont des noms qui se terminent par « :before » et sont exécutés avant qu’il ne se passe quelque chose. Comme pour les événements traditionnels, les gestionnaires peuvent annuler l’événement en retournant false.

Les événements postérieurs « After », avec des noms qui se terminent par « :after », sont exécutés après qu’il se soit passé quelque chose. Au contraire des événements traditionnels, ces gestionnaires ne peuvent pas annuler ces événements ; tous les gestionnaires seront toujours appelés.

Là où des événements :before et :after sont disponibles, les développeurs sont encouragés à faire la transition vers eux, même si d’anciens événements resteront supportés pour des raisons de compatibilité descendante.

Gestionnaires d’événement Elgg

Les gestionnaires d’événement Elgg sont appelables :

<?php

/**
 * @param \Elgg\Event $event The event object
 *
 * @return bool if false, the handler is requesting to cancel the event
 */
function event_handler(\Elgg\Event $event) {
    ...
}

Dans event_handler1, l’objet Event dispose de diverses méthodes pour récupérer le nom, le type d’objet, et l’objet de l’événement. Voyez la classe Elgg\Event pour plus d’informations.

Si un gestionnaire renvoie false, l’événement est annulé, ce qui empêche l’exécution des autres gestionnaires. Toutes les autres valeurs de retour sont ignorées.

Enregistrez un gestionnaire d’événement Elgg Event

Enregistrez votre gestionnaire pour un événement en utilisant elgg_register_event_handler :

<?php

elgg_register_event_handler($event, $object_type, $handler, $priority);

Paramètres :

• $event Le nom de l’événement.

• $object_type Le type d’objet (par ex. « user » ou « object ») ou “all” pour tous les types pour lesquels l’événement est déclenché.

• $handler Le callback - la fonction de rappel du gestionnaire.

• $priority La priorité - 0 en premier et la valeur par défaut est 500.

Object ne fait pas ici référence à un ElggObject mais plutôt à une chaîne de caractères qui décrit n’importe quel objet dans le framework : le système, un utilisateur, un objet, une relation, une annotation, un groupe.

Exemple :

<?php

// Register the function myPlugin_handle_create_object() to handle the
// create object event with priority 400.
elgg_register_event_handler('create', 'object', 'myPlugin_handle_create_object', 400);

Avertissement

Si vous gérez l’événement « update » d’un objet, évitez d’appeler save() dans votre gestionnaire d’événement. Tout d’abord ce n’est probablement pas nécessaire car l’objet est enregistré après que l’événement soit terminé, mais aussi parce que save() appelle un autre événement « update » et ne rend plus disponible $object->getOriginalAttributes().

Classes invocables comme gestionnaires

Vous pouvez utiliser une classe avec une méthode __invoke() comme gestionnaire. Enregistrez simplement le nom de la classe et elle sera instanciée (sans argument) pour toute la durée de vie de l’événement (ou du hook).

<?php

namespace MyPlugin;

class UpdateObjectHandler {
    public function __invoke(\Elgg\Event $event) {

    }
}

// in init, system
elgg_register_event_handler('update', 'object', MyPlugin\UpdateObjectHandler::class);

Déclencher un événement Elgg Event

Vous pouvez déclencher un événement personnalisé en utilisant elgg_trigger_event :

<?php

if (elgg_trigger_event($event, $object_type, $object)) {
    // Proceed with doing something.
} else {
    // Event was cancelled. Roll back any progress made before the event.
}

Pour les événements avec des états ambigus, tels que l’identification d’un utilisateur, vous devriez utiliser Événements antérieurs « Before » et postérieurs « After » en appelant elgg_trigger_before_event ou elgg_trigger_after_event. Ceci clarifie pour le gestionnaire d’événement l’état auquel s’attendre et quels événements peuvent être annulés.

<?php

// handlers for the user, login:before event know the user isn't logged in yet.
if (!elgg_trigger_before_event('login', 'user', $user)) {
    return false;
}

// handlers for the user, login:after event know the user is logged in.
elgg_trigger_after_event('login', 'user', $user);

Paramètres :

• $event Le nom de l’événement.

• $object_type Le type d’objet (par ex. « user » ou « object »).

• $object L’objet (par ex. une instance de ElggUser ou ElggGroup)

La fonction va retourner false si n’importe lequel des gestionnaires sélectionnés retourne false et si l’événement est interruptible, sinon elle retournera true.

Déclenche une séquence Elgg Event

Au lieu de déclencher manuellement l’événement :before et after, il est possible de déclencher une séquence d’événements. Cela déclenchera l’événement :before, puis l’événement réel et enfin l’événement :after.

elgg()->events->triggerSequence($event, $type, $object, $callable);

Lorsqu’ils sont appelés avec par exemple 'cache:clear', 'system', les trois événements suivants sont déclenchés

• 'cache:clear:before', 'system'

• 'cache:clear', 'system'

• 'cache:clear:after', 'system'

Paramètres :

• $event Le nom de l’événement.

• $object_type Le type d’objet (par ex. « user » ou « object »).

• $object L’objet (par ex. une instance de ElggUser ou ElggGroup)

• $callable Appelable à exécuter lors d’un événement réussi, avant event:after

Hooks plugin

Les Hooks Plugin fournissent un moyen pour les plugins de déterminer ou de modifier collaborativement une valeur. Par exemple, pour décider si un utilisateur a la permission de modifier une entité ou d’ajouter des options de configurations supplémentaires à un plugin.

Un hook plugin a une valeur passée à la fonction « trigger » déclencheuse, et chaque gestionnaire a la possibilité de modifier cette valeur avant qu’elle soit passée au prochain gestionnaire. Après que le dernier gestionnaire a été exécuté, la valeur finale est retournée par le déclencheur.

Gestionnaires des Hooks plugin

Les gestionnaires de hooks sont appelables avec le prototype suivant :

<?php

/**
 * @param \Elgg\Hook $hook The hook object
 *
 * @return mixed if not null, this will be the new value of the plugin hook
 */
function plugin_hook_handler(\Elgg\Hook $hook) {
    ...
}

Dans plugin_hook_handler, l’objet Hook dispose de diverses méthodes pour récupérer le nom, le type, la valeur et les paramètres du hook. Voyez l’interface Elgg\Hook pour plus d’informations.

Si le gestionnaire ne retourne aucune valeur (ou explicitement la valeur null), la valeur du hook plugin n’est pas altérée. Dans le cas contraire, la valeur renvoyée devient la nouvelle valeur du hook plugin, qui deviendra alors disponible via $hook->getValue() dans le prochain gestionnaire.

Enregistrez un gestionnaire de Hook plugin

Enregistrez votre gestionnaire pour un hook plugin en utilisant elgg_register_plugin_hook_handler :

<?php

elgg_register_plugin_hook_handler($hook, $type, $handler, $priority);

Paramètres :

• $hook Le nom du hook plugin.

• $type Le type de hook, ou “all” pour tous les types.

• $handler Le callback - la fonction de rappel du gestionnaire.

• $priority La priorité - 0 en premier et la valeur par défaut est 500.

Type peut avoir des sens différents. Cela peut signifier un type d’entité Elgg ou quelque chose de spécifique au nom du hook plugin.

Exemple :

<?php

// Register the function myPlugin_hourly_job() to be called with priority 400.
elgg_register_plugin_hook_handler('cron', 'hourly', 'myPlugin_hourly_job', 400);

Déclencher un Hook plugin

Vous pouvez déclencher un hook plugin personnalisé en utilisant elgg_trigger_plugin_hook :

<?php

// filter $value through the handlers
$value = elgg_trigger_plugin_hook($hook, $type, $params, $value);

Paramètres :

• $hook Le nom du hook plugin.

• $type Le type de hook, ou “all” pour tous les types.

• $params Des données arbitraires passées par le déclencheur aux gestionnaires.

• $value La valeur initiale du hook plugin.

Avertissement

Les arguments $params et $value sont inversés entre les gestionnaires de hook plugin et les fonctions de déclenchement !

Dé-enregistrer des gestionnaires d’événement ou de hook

Les fonctions elgg_unregister_event_handler et elgg_unregister_plugin_hook_handler peuvent être utilisées pour retirer des gestionnaires déjà enregistrés par un autre plugin ou par le noyau de Elgg. Les paramètres sont dans le même ordre que pour les fonctions d’enregistrement, excepté qu’il n’y a pas de paramètre de priorité.

<?php

elgg_unregister_event_handler('login', 'user', 'myPlugin_handle_login');

Les fonctions anonymes ou les objets invocables ne peuvent pas être enregistrés, mais des « callbacks », fonctions de rappel de méthode dynamiques peuvent être dé-enregistrés en donnant la version statique de la fonction de rappel :

<?php

$obj = new MyPlugin\Handlers();
elgg_register_plugin_hook_handler('foo', 'bar', [$obj, 'handleFoo']);

// ... elsewhere

elgg_unregister_plugin_hook_handler('foo', 'bar', 'MyPlugin\Handlers::handleFoo');

Même si le gestionnaire d’événement référence un appel à une méthode dynamique, le code ci-dessus va bien supprimer le gestionnaire.

Ordre d’appel des gestionnaires

Les gestionnaires sont d’abord appelés par ordre de priorité, puis par ordre d’enregistrement.

Note

Avant Elgg 2.0, l’enregistrement avec le mot-clef all provoquait un appel tardif des gestionnaires, même s’ils avaient été enregistrés avec des priorités plus faibles.