Événements

Contenu

Aperçu
Événements Elgg Events

Aperçu 

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

Les plugins modifient le système en créant des gestionnaires (callables tels que des fonctions et des méthodes) et en les enregistrant pour gérer les événements.

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

É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.

Ces événements sont principalement utilisés pour informer le reste du système que quelque chose s’est produit.

Certains événements sont également utilisés pour modifier la sortie, la configuration ou le comportement du système.

Chaque événement Elgg a un nom et un type (système, utilisateur, objet, nom de relation, annotation, groupe) décrivant 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 Précédents ont des noms se terminant par « :before » et sont déclenchés avant que quelque chose ne se produise. Les gestionnaires peuvent annuler l’événement en renvoyant false. Lorsque false est renvoyé par un gestionnaire, les gestionnaires suivants ne seront pas appelés.

After Events, with names ending in « :after », are triggered after something happened. Handlers cannot cancel these events; all handlers will always be called.

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.

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, $type, $handler, $priority);

Paramètres :

$event Le nom de l’événement.
$type Le type d’événement (par exemple « user » ou « object ») ou “all” pour tous les types sur 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.

Exemple :

<?php

// Register the function myPlugin_handle_create_object() to handle the
// create object event with priority 400.
elgg_register_event_handler('create:after', '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 il sera instancié (sans argument) pour toute la durée de vie de l’événement.

<?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éclencher un Événement avec des résultats 

Les Événements avec résultats permettent aux plugins de déterminer ou de modifier une valeur de manière collaborative. Par exemple, pour décider si un utilisateur est autorisé à modifier une entité ou à ajouter des options de configuration supplémentaires à un plugin.

Un événement a une valeur transmise à la fonction de déclenchement, et chaque gestionnaire a la possibilité de modifier cette valeur avant qu’elle ne soit transmise au gestionnaire suivant. Une fois le dernier gestionnaire terminé, la valeur finale est renvoyée par le déclencheur.

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

<?php

// filter $value through the handlers
$value = elgg_trigger_event_results($name, $type, $params, $value);

Paramètres :

$name Le nom de l’événement.
$type Le type d’événement ou « all » pour tous les types.
$params Des données arbitraires passées par le déclencheur aux gestionnaires.
$value La valeur initiale de l’événement.

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);

// or if you wish to have a result sequence
$result = elgg->events->triggerResultsSequence($name, $type, $params, $value, $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

Note

As of Elgg 6.0 the :after event will no longer be triggered if the result of the callable is false. This was done in order to prevent the system from thinking something was done which wasn’t successful. For example the 'delete', 'user' event sequence. If the callback (which handles the actual removal from the database) wasn’t successful the :after event implied that the user was deleted. Now this is only triggered when the user is actually removed from the database.

Dés-inscrire des Gestionnaires d’événement 

Les fonctions elgg_unregister_event_handler peuvent être utilisées pour supprimer les gestionnaires déjà enregistrés par un autre plugin ou le coeur de Elgg. Les paramètres sont dans le même ordre que les fonctions d’enregistrement, sauf 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_event_handler('foo', 'bar', [$obj, 'handleFoo']);

// ... elsewhere

elgg_unregister_event_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.