Create a plugin

Instructions

• The plugin appears as a folder to add in the GLPI directory tree plugins.
• This folder will contain all of the php files (and images). In short, everything that relates to the plugin.
• This directory name must only contain alphanumeric characters (no - _ . etc)
• A plugin will never modify the table structure of GLPI, it merely adds tables to the MySQL database to manage its own data. Existing GLPI tables can be read from and written to via the core GLPI API.

Coding conventions

Table Names

• Your table names must follow the rule : glpi_plugin_<plugin_name>_XXXX
• If you are using dropdown tables (list of values) they must follow the rule : glpi_plugin_<plugin_name>_XXXXdropdowns

Directory Structure

Filenames should be written in lower case.

• "setup.php" file, see How to setup

• "hook.php" file, see How to hook

• "locales" directory : contains langs files

  GLPI uses gettext for translation and the community use transifex service

  • The files must be named with : fr_FR.po / en_GB.po
  • And corresponding compiled files : fr_FR.mo / en_GB.mo

• "docs" directory : contains documentation

  Readme.md, Changelog.md, etc

• "inc" directory : contains classes and functions

  • Files containing functions should follow the rule: <name>.function.php
  • Files containing classes should follow the rule : <name>.class.php

• "front" directory : contains forms

  Filenames should follow the following rules :

  • for forms that create/edit an object : <object>.form.php
  • for forms that display an object : <object>.php

• "pics" directory : contains images

• "ajax" directory : contains everything necessary for AJAX functionality

Class and Function names

• Classes should follow the Pascal Case pattern : class Plugin<Plugin_name>Xxxx (example : PluginExampleDisplay)
• The functions out of the classes should follow the under_scores pattern: function plugin_<plugin_name>_ (example : plugin_example_getType())

Look and feel of the plugin

In order to have a consistent look and feel throughout GLPI, it is best to reuse the classes of formatting already defined and used in GLPI.
You will find all of these definitions in the CSS file of GLPI.

Thank you for following these CSS rules, as it will help integrate the plugins and future developments.

Before you begin

Useful tips :

• enable DEBUG mode
• enabling the tracing logs (in GLPI configuration) is a valuable aid in the development and verification of proper operation
• verify that MySQL is in strict mode. In the [mysqld] section of my.cnf add:

sql-mode = STRICT_ALL_TABLES

and restart MySQL

File structure for plugins and GLPI hooks

• If a plugin is not installed, none of the files are loaded
• When installing setup.php and hook.php are included

The process of instaling and desinstalling a plugin are managed by the GLPI core.
It calls functions defined in the file hook.php

See detailed explanation of files : setup.php : howtosetup hook.php : howtohook

Localization

All of the plugin data to be displayed in GLPI must be saved in a file. This allows easy translation, but just translating a file.
The language files are located in the "locales" directory The convention for naming a language file is the same as GLPI and uses standard i18n. For example :

• fr_FR for French (France),
• nl_NL pour for Dutch
• nl_BE pour for Flemish
• en_GB pour for British (England)

Theses file use the gettext standard to encode strings

Files must use UTF8 encoding

The language file corresponding to the current language of the user will be dynamically loaded. If GLPI is unable to load the current language of the user, then it will use the default languages of English or French.

Other Interactions

Adding Javascript and CSS

You can add custom JavaScript and CSS files using the following syntax :

$PLUGIN_HOOKS['add_javascript']['<plugin_name>']="FILENAME.js";

$PLUGIN_HOOKS['add_css']['<plugin_name>']="FILENAME.css";

Using the GLPI API

Skeleton of a page in GLPI

At a minimum, a PHP page included in GLPI, or one of its plugins, must contain :

• includes the API

include ("../../inc/includes.php");

• Display the GLPI header (including menu)

Html::header("<title>", ["<url>", "<sector>", "<item>", "<option>"]);

• Display The GLPI default footer

Html::footer();

For example : https://github.com/pluginsGLPI/example/blob/master/report.php

Special case for posts and forms:

• the function Html::redirect(""); redirects to another page.

Using CommonDBTM

If you set a new type, you must also define the class associated with the new type.
It must inherit from the class CommonDBTM which allows direct database abstraction. The minimum type definition is :

class PluginExample extends CommonDBTM {
   
};

For more information on the functions you can override, the documentation for the class is here : https://forge.glpi-project.org/embedded/glpi/classCommonDBTM.html