Les événements permettent d'interagir avec les fonctionnalités internes du CMS, comme la connexion d'un utilisateur ou l'envoi d'un mail, et ce peut importe le type de plugin. Cette fonctionnalité est particulièrement pratique pour créer une table dans la base de donnée à l'installation d'un plugin par exemple.

Pour ce faire, créez un dossier events/, puis pour chaque événement vous devez créer un fichier par son nom (attention aux majuscules !). Vous pouvez avoir la liste des événements sur cette page.

Les événements sont enregistrés lorsque le plugin est installé, donc vous ne pouvez pas ajouter/supprimer des événements alors qu'il est déjà installé, sauf en modifiant la base de données directement (table cms_extensions).

Il faut aussi savoir que votre fichier est toujours appelé, même si l'événement à été annulé.

De plus, il ne faut pas oublier la sécurité PHP pour éviter qu'on appelle directement le script en mettant ceci tout en haut:

<?php
 
defined('IN_ENV') or die;

Lorsque le script sera appelé, vous avez 2 variables à votre disposition: $plugin et $event.

$plugin (Array): Tableau associatif contenant toutes les infos du plugin et la configuration (config)
$event (Objet): Objet contenant les données de l'événement et des méthodes pour l'annuler

Un moyen de comprendre rapidement comment fonctionne l'événement, est d'afficher ses données/caractéristiques avec $event→debug();

A savoir: un événement peut être utilisé pour transmettre des données, et être modifiées via $event→get($key) et $event→set($key, $value).

Nous allons voir un exemple concret: lors de l'installation d'un plugin, nous allons déterminé si celui est compatible avec l'hébergement ou non.

onPluginInstall.php

<?php
 
// Sécurité
defined('IN_ENV') or die;
 
// Si l'événement est annulé, on s'arrête la car le plugin ne sera pas installé
if ($event->isCancelled())
    return;
 
// $event->get() permet de retourner une donnée spécifique à l'événement
// Dans le cas de l'événement onPluginInstall, "pluginName" représente le plugin qui est installé
// $plugin['name'] représente le plugin courant, c'est à dire le votre
// Donc on intervient pas si on installe un plugin autre que le notre
if ($event->get('pluginName') !== $plugin['name'])
    return;
 
// On vérifie si la version de PHP est inférieur à 5.4
if (version_compare(PHP_VERSION, '5.4', '<')) {
    // Lorsqu'un plugin est appelé dans un événement, le CMS n'ajoute pas automatiquement les traductions
    // Il suffit alors de les ajouter manuellement, le CMS cherchera alors dans votre dossier ''lang/''
    Translate::addPlugin($plugin);
    // On annule l'événement en précisant la raison (via le tag de traduction)
    // Ainsi, le plugin ne sera pas installé
    $event->cancelEvent('SLIDER.PHP_VERSION_5_4_REQUIRED');
}

Vous pouvez vous aussi lancer vos propres événements pour interagir avec les autres plugins, et ce très facilement. Un événement est constitué de 2 choses:
- Les données qu'il contient
- Son statut (annulable ou pas, annulé ou pas)

Les données peuvent être défini n'importe quand, cependant vous devez préciser lors du constructeur si l'événement est annulable ou non. Vous pouvez aussi préciser les données via un tableau associatif. L'ordre des arguments n'a pas d'importance. Et par défaut, un événement peut être annulé.

// Créé un événement qu'on ne peut pas annuler
$event = new Event(false);
 
// Créé un événement annulable, avec des données
$event = new Event(array('number' => time()));
 
// Créé un événement, qu'on ne peut pas annuler
$event = new Event(array('number' => 374), false);
 
// Créé un événement, qu'on peut annuler
$event = new Event;
$event->set('number', -1);

Maintenant, nous allons propager l'événement, rien de plus simple: EventManager::fire($eventName, $event);. N'oubliez pas de préfixer le nom de l'événement par votre plugin suivi d'un point.

$event = new Event;
EventManager::fire('Slider.onDiplay', $event);
 
$isCancelled = $event->isCancelled(); // Retourne true si l'événement a été annulé
$cancelReason = $event->cancelReason(); // Retourne la raison de l'annulation. Elle n'est pas toujours précisée

Voici un petit d'exemple:

$event = new Event;
$event->set('slide', 3);
 
EventManager::fire('Slider.onDisplay', $event);
 
if ($event->isCancelled()) {
    // L'événement a été annulé
    if ($event->cancelReason()) {
        respond(false, $event->cancelReason());
    } else {
        respond(false, 'SLIDER.SLIDE_CANCELLED');
    }
} else {
    // L'événement n'a pas été annulé
    // Cependant, les données ont pu être modifiées
    $slide = $event->get('slide');
}

Page suivante: Fonctionnalités avancées