Plugin Creator Tool

A GLPI plugin developer usually has a lot of things to worry about such as the basic layout of their plugin required to work with GLPI, the XML file needed for their plugin to work with both plugin marketplaces the one at https://plugins.glpi-project.org and the one built into GLPI (locked behind a GLPI Network registration key), migrating from one version to another, etc. This tool tries to shorten the amount of time needed to have a basic plugin up and working. This is crucial for proof of concepts or internal plugins that are being developed to address a particular business need. The whole point of this tool is to enable IT department staff who may not know PHP or may not have the time to bother with it to create GLPI plugins to extend the capabilities of their GLPI installation to meet their needs. As a side effect it also offers a solid jumping off point for plugin developers who are also competent with PHP.

The tool uses a PHP code generator to generate a lot of the basic PHP code for you.

So far, this tool presents a simple form broken up into two sections:

• Plugin info
  • Name: The display name of the plugin
    • The directory/internal name is generated based on this (lowercase without spaces)
  • Plugin Version: The current version of the plugin. Usually this is going to be 1.0.0, but it is up to you if you want to use a different initial version.
  • Minimum GLPI Version: The lowest version of GLPI that your plugin is guaranteed to work with.
  • Maximum GLPI Version: The highest version of GLPI that your plugin is guaranteed to work with (exclusive).
  • Authors: A comma separated list of all authors to be credited in this plugin. This can be individuals or a company name.
  • License: The license this plugin is distributed under
    • The plugin currently recognizes AGPL 3, GPL 2, and GPL 3 and for those licenses it will automatically add the appropriate LICENSE file and copyright headers in the generated code files. You may use any license you wish, but the plugin won't create the appropriate LICENSE file or headers. You may manually add those yourself or create a Pull Request with the associated header and license templates. The curernt plugin creator tool code should automatically be able to recognize any correctly named license template files.
  • Homepage: This should be the URL for your project's website, GitHub page, etc. If this is an internal plugin, it is OK to leave this blank or put your business' website.
  • Language: The primary language for your plugin.
  • Description (Short): A quick one or two line description of the plugin.
  • Description (Long): The full description of the plugin.
• Generator Options
  • Use Unit Tests: Toggle for creating the base code needed for adding Atoum tests for your plugin code.
  • Prepare for Plugin Directory and Marketplace: Toggle for creating the plugin's XML file which is what the plugin directory and marketplace uses.
  • Use Plugin Migration System: Adds a special class to your code which you would put all your migration code in instead of the plugin_myplugin_install function in hook.php. See the section below on the Migration class.

This form will automatically create the plugin folder structure and base code files needed for your plugin.

Migration Class

This is a special class added by the Plugin Creator tool to your plugin which handles your migrations from one version of your plugin to another. If you choose to use it in the generator options, the hook.php file is generated so that it is automatically called in the plugin_myplugin_install function. To add migration code, usually database schema related, simply add a function to the class named for your version. For example, a migration to version 2.1.2 would have its code in the function apply_2_1_2_migration. The code in each migration function should only include the changes since the last version. Additionally, all code in the migration functions should be repeatable. For example, you want to add a new table glpi_plugin_myplugin_example in version 2.0.0. You should check to see if that table already exists before trying to create the table. The same goes for creating columns, renaming columns, adding indexes, etc. The reason is so that we can replay failed updates or replay previous updates in case we forget which version is currently installed.

There are two important properties set in the migration class:

• db: The database abstraction class being used by GLPI. This is just assigned the value of the $DB global currently, but could change in the future if GLPI switches to using dependency injection instead of globals (The explanation of which is not in the scope of this wiki). This plugin will try to adapt the migration class as GLPI's code changes since all user-specific code should be done in the apply_x_x_x_migration functions.
• glpiMigration: The Migration class used by GLPI for their own update code. It has useful functions for handling the modification of the database and is generally what you want to use instead of direct queries through the db property when possible.

This migration class will automatically track the last successfully installed version of your plugin and when updating, will intelligently apply only the needed migrations. For example, you try upgrading from version 1.1.0 to 2.1.0 and the upgrade fails after the 2.0.0 upgrade. The last recorded version of the plugin would be 2.0.0 so when the issue blocking the upgrade is resolved, the plugin upgrade will continue from the 2.0.0 version instead of the 1.1.0 version.

The function for the base version apply_1_0_0_migration is automatically created. All your initial database tables should be created here.

The Future (AKA the .devplugin file)

In preparation of some more involved features of this tool, I thought it necessary to record some known plugin information in an easily parsable JSON file. Currently, this includes a lot of the same information available in the XML file used by the plugin directory and marketplace but is much easier to parse in code because, you know, it isn't XML. This is meant to be a known state for your plugin that this tool can reference for modifying existing code or adding new code. Although not confirmed yet, this tool may include the ability to create a lot of the plugin code from a graphical interface instead of writing PHP code yourself. For example:

• Upload or write CSS/JS code using a code editor field (like the Custom CSS field in Entity configurations) and have it automatically tied into the add_css or add_js hooks for your plugin.
• Automatically generate the Config or Profile (permissions) forms based on a known set of classes and rights and automatically register the tabs for them.
• Create new item types/classes from a graphical interface.

If you used the Plugin Creator tool before the .devplugin file was implemented, you could rename your plugin folder then regenerate it using the Plugin Creator and copy the changed files from your copy of the plugin. You could also generate a temporary plugin and use the generated .devplugin file as a reference to create your own for your plugin. The exact schema for this file is not included here because it is expected to change as new features get added. As the tool's feature set stabilizes, the schema may be included in this wiki article.

How is this different from using The empty plugin?

The empty plugin provided by the GLPI Project is a static starting point for plugin developers but this tool is dynamic and can adapt to the needs of the plugin developer through the use of a graphical interface and PHP code generation library.