Events
Contenu
Aperçu
Elgg a un événement système qui peut être utilisé pour remplacer ou étendre les fonctionnalités du noyau.
Plugins influence the system by creating handlers (callables such as functions and methods) and registering them to handle the events.
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
É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.
These events are mostly used to notify the rest of the system that something has happened.
There are also events that are used to influence output, configuration or behaviour of the system.
Each Elgg event has a name and a type (system, user, object, relationship name, annotation, group) describing the type of object passed to the handlers.
É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] ?
Before Events have names ending in « :before » and are triggered before
something happens. Handlers can cancel the event by returning false
.
When false
is returned by a handler, following handlers will not be called.
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 The event type (e.g. « user » or « object ») or “all” for all types on which the event is fired.
$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
You may use a class with an __invoke()
method as a handler. Just register the class name and it will be instantiated (with no arguments)
for the lifetime of the event.
<?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
ouElggGroup
)
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
.
Trigger an Event with results
Events with results provide a way for plugins to collaboratively determine or alter a value. For example, to decide whether a user has permission to edit an entity or to add additional configuration options to a plugin.
An event has a value passed into the trigger function, and each handler has an opportunity to alter the value before it’s passed to the next handler. After the last handler has completed, the final value is returned by the trigger.
You can trigger a custom event using elgg_trigger_event_results
:
<?php
// filter $value through the handlers
$value = elgg_trigger_event_results($name, $type, $params, $value);
Paramètres :
$name The name of the event.
$type The type of the event or “all” for all types.
$params Des données arbitraires passées par le déclencheur aux gestionnaires.
$value The initial value of the event.
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
ouElggGroup
)$callable Appelable à exécuter lors d’un événement réussi, avant event:after
Unregister Event Handlers
The functions elgg_unregister_event_handler
can be used to remove
handlers already registered by another plugin or Elgg core. The parameters are in the same order as the registration
functions, except there’s no priority parameter.
<?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.