20. Mòduls

Vista general

És possible millorar la funcionalitat frontal de Zabbix afegint mòduls de tercers o desenvolupant els vostres propis mòduls sense haver de modificar el codi font de Zabbix.

Tingueu en compte que el codi del mòdul s'executarà amb els mateixos privilegis que el codi font de Zabbix. Això vol dir:

• Els mòduls de tercers poden ser perillosos. Heu de confiar en els mòduls que instal·leu;
• Els errors en el codi d'un mòdul de tercers poden provocar que la interfície es bloquegi. Si això passa, simplement traieu el codi del mòdul de la interfície. Tan bon punt torneu a carregar la interfície Zabbix, veureu una nota que manquen alguns mòduls. Aneu a Administració de mòduls (a Administració → General → Mòduls) i torneu a fer clic a Escanejar el directori per esborrar els mòduls inexistents de la base de dades.

Instal·lació

Si us plau, llegiu sempre el manual d'instal·lació d'un mòdul concret. Es recomana instal·lar els nous mòduls un per un per gestionar fàcilment els errors.

Just abans d'instal·lar un mòdul:

• Assegureu-vos que l'heu descarregat des d'una font de confiança. La instal·lació de codi nociu pot tindre conseqüències, com ara la pèrdua de dades
• Es poden instal·lar diferents versions del mateix mòdul (mateix ID) en paral·lel, però només es pot activar una versió alhora

Passes per instal·lar un mòdul:

• Descomprimiu el vostre mòdul a la seva pròpia carpeta dins de la carpeta modules de la interfície Zabbix
• Assegureu-vos que la carpeta del mòdul contingui almenys el fitxer manifest.json
• Navegueu a Administració de mòduls i feu clic al botó Analitzar directori
• El nou mòdul apareixerà a la llista amb la seva versió, autor, descripció i estat
• Activa el mòdul fent clic al seu estat

Resolució de problemes |Problema|Solució|:

|Problema|Solució| |---------|---------------------------------------- -| |El mòdul no apareix al llistat|Assegureu-vos que el fitxer manifest.json és a la carpeta modules/your-module/ de la interfície Zabbix. Si és així, vol dir que el mòdul no és adequat per a la versió actual de Zabbix. Si el fitxer manifest.json no hi és, segurament l'heu descomprimit al directori incorrecte.| |GUI fallida|El codi del mòdul no és compatible amb la versió actual de Zabbix o la configuració del servidor. Si us plau, esborreu els fitxers del mòdul i torneu a carregar la interfície. Veureu un avís que manquen alguns mòduls. Aneu a Administració de mòduls i torneu a fer clic al botó Analitzar directori per esborrar mòduls inexistents de la base de dades.| |Apareix un missatge d'error sobre un espai de noms, ID o accions idèntiques|El nou mòdul ha intentat registrar un espai de noms, ID o accions que ja són registrades per altres mòduls activats. Desactiveu el mòdul conflictiu (esmentat al missatge d'error) abans d'habilitar el nou.| |Apareixen missatges d'error tècnic|Informa d'errors al desenvolupador del mòdul.|

Desenvolupar mòduls

Els mòduls són escrits en llenguatge PHP. Es prefereix el disseny de patró de programari Model-View-Controller (MVC), ja que també s'empra a la interfície Zabbix i facilitarà el desenvolupament. L'estricta mecanografia PHP també és benvinguda, però no és necessària.

Tingueu en compte que amb els mòduls podeu afegir fàcilment nous elements de menú i vistes i accions respectives a la interfície de Zabbix. Actualment, no és possible registrar una nova API ni crear taules de bases de dades noves mitjançant mòduls.

Estructura dels mòduls

Cada mòdul és un directori (ubicat al directori "mòduls") amb subdirectoris que contenen controladors, vistes i altres codis:

 directori_mòdul_exemple/ (obligatori)
            manifest.json (obligatori) Definició de metadades i accions.
            Module.php Inicialització del mòdul i gestió d'esdeveniments.
            accions/fitxers del controlador d'accions.
                SomethingView.php
                SomethingCreate.php
                SomethingDelete.php
                exportació_dades/
                    ExportaAsXml.php
                    Exporta com a Excel.php
            visualitzacions/ Veure fitxers.
                exemple.algunacosa.veure.php
                exemple.algunacosa.suprimir.php
                js/ Fitxers JavaScript emprats a views.example.something.view.js.php
            parcials/ Fitxers de visualització parcial.
                exemple.alguna cosa.reutilitzable.php
                js/ Fitxers JavaScript emprats a parcials.
                    exemple.alguna cosa.reutilitzable.js.php

Com podeu veure, l'únic fitxer necessari al directori del mòdul personalitzat és manifest.json. El mòdul no es registrarà sense aquest fitxer. Module.php és responsable de registrar els elements del menú i gestionar esdeveniments com ara 'onBeforeAction' i 'onTerminate'. Els directoris accions, visualitzacions i parcials contenen el codi PHP i JavaScript necessaris per a les accions del mòdul.

Convenció de nomenclatura

Abans de crear un mòdul, és important acordar la convenció de nomenclatura dels diferents elements del mòdul, com ara directoris i fitxers, per tal de poder mantindre les coses organitzades. També podeu trobar exemples més amunt, a la secció Estructura del mòdul.

Tingueu en compte que el prefix del "mòdul" i la inclusió del nom són obligatoris per als noms de fitxers de visualització i parcials, tret que hàgiu de substituir les vistes principals o parcials de Zabbix. Aquesta regla, però, no s'aplica als noms dels fitxers d'acció.

Preparació del manifest

Cada mòdul hauria de tindre un fitxer manifest.json amb els camps següents en format JSON:

Per a referència, consulteu un exemple de manifest.json a la secció Referència.

Accions

El mòdul tindrà control sobre les accions frontals definides a l'objecte accions del fitxer manifest.json. D'aquesta manera, es defineixen noves accions. De la mateixa manera, podeu redefinir les accions existents. Cada clau d'acció ha de representar el nom de l'acció i el valor corresponent ha de contindre les claus classe' i, opcionalment, les teclesdisseny' i visualitza.

Una acció és definida per quatre homòlegs: nom, controlador, vista i disseny. La validació i preparació de dades es fa normalment al controlador, el format de sortida es fa a la vista o parcials, i el disseny de la pàgina s'encarrega de decorar la pàgina amb coses com el menú, l'encapçalament, el peu de pàgina i altres.

Les accions del mòdul s'han de definir al fitxer manifest.json com a objecte accions:

Hi ha diversos dissenys predefinits, com ara layout.json o layout.xml. Són per a accions que produeixen un resultat diferent de l'HTML. Podeu explorar els dissenys predefinits al directori app/views/ o fins i tot crear els vostres.

De vegades cal redefinir només la part vista d'una acció deixant el controlador intacte. En aquest cas, només cal col·locar la vista necessària i/o els fitxers parcials al directori views del mòdul.

Per a referència, consulteu un exemple de fitxer de controlador d'acció a la secció Referència. No dubteu a explorar les accions habituals del codi font de Zabbix, que es troba al directori app/.

Module.php

Aquest fitxer PHP opcional és responsable de la inicialització del mòdul i de la gestió d'esdeveniments. La classe 'Mòdul' s'hauria de definir en aquest fitxer, ampliant la classe base ''. La classe del mòdul s'ha de definir a l'espai de noms especificat al fitxer manifest.json.

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

Per a referència, consulteu un exemple de Module.php a la secció Referència.

Referència

Aquesta secció conté les versions de base dels diferents elements de mòdul presentats a les seccions anteriors.

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 $actionAction instance responsible for current request.
       */
       public function onBeforeAction(CAction $action): void {
       }
       
       /**
       * Event handler, triggered on application exit.
       *
       * @param CAction $actionAction instance responsible for current request.
       */
       public function onTerminate(CAction $action): void {
       }
       }

Action controller

<?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 (Session ID) validation. Session ID validation should only be used for actions which involve 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);
       }
       }

Vista acció

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