Guidelines¶

Directories structure¶

Real structure will depend of what your plugin propose. See requirements to find out what is needed. You may also want to take a look at GLPI File Hierarchy Standard.

Warning

The main directory name of your plugin may contain only alphanumeric characters (no - or _ or accented characters or else).

The plugin directory structure should look like the following:

MyPlugin
- front
  - …
- inc and/or src
  - …
- locale
  - …
- tools
  - …
- README.md
- LICENSE
- setup.php
- hook.php
- MyPlugin.xml
- MyPlugin.png
- …
- …
front will host all PHP files directly used to display something to the user,
inc is the legacy way to host all classes,
src is the new way to host classes; relying on PSR-4 autoload,
if you internationalize your plugin, localization files will be found under the locale directory,
if you need any scripting tool (like something to extract or update your translatable strings), you can put them in the tools directory
a README.md file describing the plugin features, how to install it, and so on,
a LICENSE file containing the license,
MyPlugin.xml and MyPlugin.png can be used to reference your plugin on the plugins directory website,
the required setup.php and hook.php files.

PSR-4 autoload¶

Added in version 10.0.

In order to use the Composer PSR-4 autoloader in your plugin, must place your PHP class files in the /src directory instead of /inc. In this scenario the /inc directory should no longer be present in the plugin folder structure.

The convention to be used is (Case sensitive): namespace GlpiPluginMyplugin;. The namespace should be added to every class in the /src directory and per the PSR-12 PHP convention be placed in the top of your class. Classes using the GlpiPluginMyplugin` namespaces will be loaded from: `GLPI_ROOTpluginsmypluginsrc`. To include folders inside the `/src directory simply add them to your namespace and use keywords i.e. `namespace GlpiPluginMypluginSubFolder` will load from `GLPI_ROOTpluginsmypluginsrcSubFolder`.

Directive	Composer mapping
GlpiPlugin	maps (virtually) to /plugins or /marketplace
MyPlugin	maps to: /myplugin/src converted strtolower
SubFolder	maps to /src/SubFolder/ using provided case
ClassName	maps to ../ClassName.php using provided case apending .php

GLPI_ROOT/marketplace/myplugin/src/Test.php

<?php

  namespace GlpiPlugin\MyPlugin;

  class Test extends CommonDBTM
  {
    \\ Your class code...
  }

?>

GLPI_ROOT/marketplace/myplugin/src/ChildClass/ResultOutcomes.php

<?php

  namespace GlpiPlugin\MyPlugin\ChildClass;

  class ResultOutcomes extends CommonDBTM
  {
    \\ Your class code...
  }

?>

GLPI_ROOT/marketplace/myplugin/setup.php

<?php

use GlpiPlugin\MyPlugin\Test;
use GlpiPlugin\Myplugin\ChildClass\ResultOutcomes;

function usingTest() : void
{
  $t = new Test();
  $r = new ResultOutcomes();
}

?>

Where to write files?¶

Warning

Plugins may never ask user to give them write access on their own directory!

The GLPI installation already ask for administrator to get write access on its files directory; just use GLPI_PLUGIN_DOC_DIR/{plugin_name} (that would resolve to glpi_dir/files/_plugins/{plugin_name} in default basic installations).

Make sure to create the plugin directory at install time, and to remove it on uninstall.

Versionning¶

We recommend you to use semantic versionning for you plugins. You may find existing plugins that have adopted another logic; some have reasons, others don’t… Well, it is up to you finally :-)

Whatever the versioning logic you adopt, you’ll have to be consistent, it is not easy to change it without breaking things, once you’ve released something.

ChangeLog¶

Many projects make releases without providing any changelog file. It is not simple for any end user (whether a developer or not) to read a repository log or a list of tickets to know what have changed between two releases.

Keep in mind it could help users to know what have been changed. To achieve this, take a look at Keep an ChangeLog, it will explain you some basics and give you guidelines to maintain sug a thing.

Third party libraries¶

Just like GLPI, you should use the composer tool to manage third party libraries for your plugin.