This is a translation of the original English documentation page. Help us make it better.

20. Modules

Aperçu

Il est possible d'améliorer la fonctionnalité frontale de Zabbix en ajoutant des modules tiers ou en développant vos propres modules sans avoir à modifier le code source de Zabbix.

Notez que le code du module s'exécutera avec les mêmes privilèges que le code source Zabbix. Ça signifie:

  • Les modules tiers peuvent être dangereux. Vous devez faire confiance aux modules que vous installez ;
  • Des erreurs dans le code d'un module tiers peuvent faire planter l'interface. Si cela se produit, supprimez simplement le code du module de l'interface. Dès que vous rechargez l'interface Zabbix, vous verrez une note indiquant que certains modules sont absents. Allez dans Administration du module (dans AdministrationGénéralModules) et cliquez à nouveau sur Scanner le répertoire pour supprimer les modules inexistants de la base de données .

Installation

Veuillez toujours lire le manuel d'installation d'un module particulier. Il est recommandé d'installer les nouveaux modules un par un pour gérer facilement les pannes.

Juste avant d'installer un module :

  • Assurez-vous d'avoir téléchargé le module à partir d'une source fiable. L'installation de code nuisible peut entraîner des conséquences, telles que la perte de données
  • Différentes versions d'un même module (même ID) peuvent être installées en parallèle, mais une seule version peut être activée à la fois

Étapes pour installer un module :

  • Décompressez votre module dans son propre dossier dans le dossier modules de l'interface Zabbix
  • Assurez-vous que votre dossier de module contient au moins le fichier manifest.json
  • Accédez à l'Administration du module et cliquez sur le bouton Analyser le répertoire
  • Le nouveau module apparaîtra dans la liste avec sa version, son auteur, sa description et son statut
  • Activer le module en cliquant sur son statut

Dépannage |Problème|Solution|:

Problem Solution
Le module n'apparait pas dans la liste Assurez-vous que le fichier manifest.json existe dans le dossier modules/your-module/ de l'interface Zabbix. Si c'est le cas, cela signifie que le module ne convient pas à la version actuelle de Zabbix. Si le fichier manifest.json n'existe pas, vous avez probablement décompressé dans le mauvais répertoire.
L'interface s'est crashée Le code du module n'est pas compatible avec la version actuelle de Zabbix ou la configuration du serveur. Veuillez supprimer les fichiers du module et recharger l'interface. Vous verrez un avis indiquant que certains modules sont absents. Allez dans l'Administration du module et cliquez une nouvelle fois sur le bouton Analyser le répertoire pour supprimer les modules inexistants de la base de données.
Un message d'erreur concernant un namespadce, un ID ou des actions identiques s'affiche Le nouveau module a essayé d'enregistrer un namespace, un ID ou des actions qui sont déjà enregistrés par d'autres modules activés. Désactivez le module en conflit (mentionné dans le message d'erreur) avant d'activer le nouveau.
Des messages d'erreur technique apparaissent Signalez les erreurs au développeur du module.

Développer des modules

Les modules sont écrits en langage PHP. La conception de modèles logiciels modèle-vue-contrôleur (MVC) est préférée, car elle est également utilisée dans l'interface Zabbix et facilitera le développement. Le typage PHP strict est également le bienvenu mais pas obligatoire.

Veuillez noter qu'avec les modules, vous pouvez facilement ajouter de nouveaux éléments de menu et des vues et actions respectives à l'interface Zabbix. Actuellement, il n'est pas possible d'enregistrer une nouvelle API ou de créer de nouvelles tables de base de données via des modules.

Structure des modules

Chaque module est un répertoire (placé dans le répertoire modules) avec des sous-répertoires contenant des contrôleurs, des vues et tout autre code :

exemple_repertoire_module/           (obligatoire)
           manifest.json                   (obligatoire)  Définition des métadonnées et des actions.
           Module.php                                  Initialisation du module et gestion des événements.
           actions/                                    Fichiers de contrôleur d'action.
               SomethingView.php
               SomethingCreate.php
               SomethingDelete.php
               data_export/                                 
                   ExportAsXml.php
                   ExportAsExcel.php
           views/                                      Fichiers des vues.
               example.something.view.php
               example.something.delete.php
               js/                                     Fichiers JavaScript utilisés dans views.example.something.view.js.php
           partials/                                   Fichiers partiels des vues.
               example.something.reusable.php
               js/                                     Fichiers JavaScript utilisés dans les partiels.
                   example.something.reusable.js.php

Comme vous pouvez le voir, le seul fichier obligatoire dans le répertoire du module personnalisé est manifest.json. Le module ne s'enregistrera pas sans ce fichier. Module.php est responsable de l'enregistrement des éléments de menu et du traitement des événements tels que 'onBeforeAction' et 'onTerminate'. Les répertoires actions, views et partials contiennent le code PHP et JavaScript nécessaire aux actions du module.

Convention de nommage

Avant de créer un module, il est important de s'entendre sur la convention de nommage des différents éléments du module, tels que les répertoires et les fichiers, afin que nous puissions garder les choses bien organisées. Vous pouvez également trouver des exemples ci-dessus, dans la section Structure du module.

Élément Règles de nommage Exemple
Répertoire du module Minuscules [a-z], underscores et chiffres décimaux exemple_v2
Sous-répertoires d'action Minuscules [a-z] et underscores data_export
Fichiers d'action Cas d'usage, se terminant par le type d'action SomethingView.php
fichiers vues et partiels Minuscules [a-z]
Mots séparés par un point
Préfixé par module. suivi du nom du module
Se terminant par le type d'action et l'extension de fichier .php
module.example.something.view.php
Fichiers Javascript Les mêmes règles s'appliquent que celles pour les fichiers vues et partiels, à l'exception de l'extension de fichier .js.php. module.example.something.view.js.php

Notez que le préfixe 'module' et l'inclusion de nom sont obligatoires pour les noms de vue et de fichiers partiels, sauf si vous devez remplacer les vues principales ou partielles de Zabbix. Cette règle, cependant, ne s'applique pas aux noms de fichiers d'action.

Préparation du manifeste

Chaque module doit avoir un fichier manifest.json avec les champs suivants au format JSON :

Paramètre Requis Type Par défaut Description
manifest_version Oui Double - Version manifeste du module. La version actuellement prise en charge est 1.
id Oui Chaîne - ID du module. Un seul module avec un ID donné peut être activé en même temps.
name Yes Chaîne - Nom du module tel qu'affiché dans la section Administration.
version Oui Chaîne - Version du module telle qu'affichée dans la section Administration.
namespace Oui Chaîne - Espace de noms PHP pour Module.php et les classes d'action.
author No Chaîne "" Auteur du module tel qu'affiché dans la section Administration.
url No Chaîne "" URL du module tel qu'affiché dans la section Administration.
description No Chaîne "" Description du module telle qu'affichée dans la section Administration.
actions Non Objet {} Actions à enregistrer avec ce module. Voir Actions.
config Non Objet {} Configuration du module.

Pour référence, veuillez consulter un exemple de manifest.json dans la section Réference.

Actions

Le module aura le contrôle sur les actions frontales définies dans l'objet actions du fichier manifest.json. De cette façon, de nouvelles actions sont définies. De la même manière, vous pouvez redéfinir des actions existantes. Chaque clé d'actions doit représenter le nom de l'action et la valeur correspondante doit contenir les clés class et éventuellement layout et view.

Une action est définie par quatre contreparties : nom, contrôleur, vue et mise en page. La validation et la préparation des données sont généralement effectuées dans le contrôleur, le formatage de la sortie est effectué dans la vue ou les partiels, et la mise en page est responsable de la décoration de la page avec des éléments tels que le menu, l'en-tête, le pied de page et autres.

Les actions du module doivent être définies dans le fichier manifest.json en tant qu'objet actions :

Paramètre Requis Type Par défaut Description
*key* Oui Chaîne - Nom de l'action, en minuscules [a-z], séparant les mots par un point.
class Oui Chaîne - Nom de la classe d'action, y compris le chemin du sous-répertoire (le cas échéant) dans le répertoire actions.
layout Non Chaîne "layout.htmlpage" Mise en page de l'action.
view Non Chaîne null Vue de l'actions.

Il existe plusieurs mises en page prédéfinies, comme layout.json ou layout.xml. Celles-ci sont destinés aux actions qui produisent un résultat différent de celui d'un HTML. Vous pouvez explorer les mises en page prédéfinies dans le répertoire app/views/ ou même créer les vôtres.

Parfois, il est nécessaire de redéfinir uniquement la partie vue d'une action en laissant le contrôleur intact. Dans ce cas, placez simplement la vue nécessaire et/ou les fichiers partiels dans le répertoire views du module.

Pour référence, veuillez consulter un exemple de fichier de contrôleur d'action dans la section Référence. N'hésitez pas à explorer les actions courrantes du code source de Zabbix, situées dans le répertoire app/.

Module.php

Ce fichier PHP facultatif est responsable de l'initialisation du module ainsi que de la gestion des événements. La classe 'Module' devrait être définie dans ce fichier, étendant la classe de base \Core\CModule. La classe Module doit être définie dans l'espace de noms spécifié dans le fichier manifest.json.

<?php
       
       namespace Modules\Example;
       use Core\CModule as BaseModule;
       
       class Module extends BaseModule {
           ...
       }

Pour référence, veuillez consulter un exemple de Module.php dans la section Référence.

Référence

Cette section contient les versions de base des différents éléments de module présentés dans les sections précédentes.

manifest.json

{
           "manifest_version": 1.0,
           "id": "example_module",
           "name": "Example module",
           "version": "1.0",
           "namespace": "Example",
           "author": "John Smith",
           "url": "http://module.example.com",
           "description": "Short description of the module.",
           "actions": {
               "example.something.view": {
                   "class": "SomethingView",
                   "view": "module.example.something.view"
               },
               "example.something.create": {
                   "class": "SomethingCreate",
                   "layout": null
               },
               "example.something.delete": {
                   "class": "SomethingDelete",
                   "layout": null
               },
               "example.something.export.xml": {
                   "class": "data_export/ExportAsXml",
                   "layout": null
               },
               "example.something.export.excel": {
                   "class": "data_export/ExportAsExcel",
                   "layout": null
               }
           },
           "config": {
               "username": "john_smith"
           }
       }

Module.php

<?php declare(strict_types = 1);
       
       namespace Modules\Example;
       
       use APP;
       use CController as CAction;
       
       /**
        * Please see Core\CModule class for additional reference.
        */
       class Module extends \Core\CModule {
       
           /**
            * Initialize module.
            */
           public function init(): void {
               // Initialize main menu (CMenu class instance).
               APP::Component()→get('menu.main')
                   →findOrAdd(_('Reports'))
                       →getSubmenu()
                           →add((new \CMenuItem(_('Example wide report')))
                               →setAction('example.report.wide.php')
                           )
                           →add((new \CMenuItem(_('Example narrow report')))
                               →setAction('example.report.narrow.php')
                           );
           }
       
           /**
            * Event handler, triggered before executing the action.
            *
            * @param CAction $action  Action instance responsible for current request.
            */
           public function onBeforeAction(CAction $action): void {
           }
       
           /**
            * Event handler, triggered on application exit.
            *
            * @param CAction $action  Action instance responsible for current request.
            */
           public function onTerminate(CAction $action): void {
           }
       }

Contrôleur Action

<?php declare(strict_types = 1);
       
       namespace Modules\Example\Actions;
       
       use CControllerResponseData;
       use CControllerResponseFatal;
       use CController as CAction;
       
       /**
        * Example module action.
        */
       class SomethingView extends CAction {
       
           /**
            * Initialize action. Method called by Zabbix core.
            *
            * @return void
            */
           public function init(): void {
               /**
                * Disable SID (Sessoin ID) validation. Session ID validation should only be used for actions which involde data
                * modification, such as update or delete actions. In such case Session ID must be presented in the URL, so that
                * the URL would expire as soon as the session expired.
                */
               $this→disableSIDvalidation();
           }
       
           /**
            * Check and sanitize user input parameters. Method called by Zabbix core. Execution stops if false is returned.
            *
            * @return bool true on success, false on error.
            */
           protected function checkInput(): bool {
               $fields = [
                   'name'  => 'required|string',
                   'email' => 'required|string',
                   'phone' => 'string'
               ];
       
               // Only validated data will further be available using $this→hasInput() and $this→getInput().
               $ret = $this→validateInput($fields);
       
               if (!$ret) {
                   $this→setResponse(new CControllerResponseFatal());
               }
       
               return $ret;
           }
       
           /**
            * Check if the user has permission to execute this action. Method called by Zabbix core.
            * Execution stops if false is returned.
            *
            * @return bool
            */
           protected function checkPermissions(): bool {
               $permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
       
               return in_array($this→getUserType(), $permit_user_types);
           }
       
           /**
            * Prepare the response object for the view. Method called by Zabbix core.
            *
            * @return void
            */
           protected function doAction(): void {
               $contacts = $this→getInput('email');
       
               if ($this→hasInput('phone')) {
                   $contacts .= ', '.$this→getInput('phone');
               }
       
               $data = [
                   'name' => $this→getInput('name'),
                   'contacts' => $contacts
               ];
       
               $response = new CControllerResponseData($data);
       
               $this→setResponse($response);
           }
       }

Vue Action

<?php declare(strict_types = 1);
       
       /**
        * @var CView $this
        */
       
       $this→includeJsFile('example.something.view.js.php');
       
       (new CWidget())
           →setTitle(_('Something view'))
           →addItem(new CDiv($data['name']))
           →addItem(new CPartial('module.example.something.reusable', [
               'contacts' => $data['contacts']
           ])
           →show();