Hooks¶

GLPI provides a certain amount of “hooks”. Their goal is for plugins (mainly) to work on certain places of the framework; like when an item has been added, updated, deleted, …

This page describes current existing hooks; but not the way they must be implemented from plugins. Please refer to the plugins development documentation.

Standards Hooks¶

Usage¶

Aside from their goals or when/where they’re called; you will see three types of different hooks. Some will receive an item as parameter, others an array of parameters, and some won’t receive anything. Basically, the way they’re declared into your plugin, and the way you’ll handle that will differ.

All hooks called are defined in the setup.php file of your plugin; into the $PLUGIN_HOOKS array. The first key is the hook name, the second your plugin name; values can be just text (to call a function declared in the hook.php file), or an array (to call a static method from an object):

<?php
//call a function
$PLUGIN_HOOKS['hook_name']['plugin_name'] = 'function_name';
//call a static method from an object
$PLUGIN_HOOKS['other_hook']['plugin_name'] = ['ObjectName', 'methodName'];

Without parameters¶

Those hooks are called without any parameters; you cannot attach them to any itemtype; basically they’ll permit you to display extra information. Let’s say you want to call the display_login hook, in you setup.php you’ll add something like:

<?php
$PLUGIN_HOOKS['display_login']['myPlugin'] = 'myplugin_display_login';

You will also have to declare the function you want to call in you hook.php file:

<?php
/**
  * Display information on login page
  *
  * @return void
  */
public function myplugin_display_login () {
   echo "That line will appear on the login page!";
}

The hooks that are called without parameters are: display_central, post_init init_session, change_entity, change_profile`, display_login and add_plugin_where.

With item as parameter¶

Those hooks will send you an item instance as parameter; you’ll have to attach them to the itemtypes you want to apply on. Let’s say you want to call the pre_item_update hook for Computer and Phone item types, in your setup.php you’ll add something like:

<?php
$PLUGIN_HOOKS['pre_item_update']['myPlugin'] = [
   'Computer'  => 'myplugin_updateitem_called',
   'Phone'     => 'myplugin_updateitem_called'
];

You will also have to declare the function you want to call in you hook.php file:

<?php
/**
 * Handle update item hook
 *
 * @param CommonDBTM $item Item instance
 *
 * @return void
 */
public function myplugin_updateitem_called (CommonDBTM $item) {
   //do everything you want!
   //remember that $item is passed by reference (it is an object)
   //so changes you will do here will be used by the core.
   if ($item::getType() === Computer::getType()) {
      //we're working with a computer
   } elseif ($item::getType() === Phone::getType()) {
      //we're working with a phone
   }
}

The hooks that are called with item as parameter are: item_empty, pre_item_add, post_prepareadd, item_add, pre_item_update, item_update, pre_item_purge, pre_item_delete, item_purge, item_delete, pre_item_restore, item_restore, autoinventory_information, item_add_targets, item_get_events, item_action_targets, item_get_datas.

With array of parameters¶

These hooks will work just as the hooks with item as parameter expect they will send you an array of parameters instead of only an item instance. The array will contain two entries: item and options, the first one is the item instance, the second options that have been passed:

<?php
/**
 * Function that handle a hook with array of parameters
 *
 * @param array $params Array of parameters
 *
 * @return void
 */
public function myplugin_params_hook(array $params) {
   print_r($params);
   //Will display:
   //Array
   //(
   //   [item] => Computer Object
   //      (...)
   //
   //   [options] => Array
   //      (
   //            [_target] => /front/computer.form.php
   //            [id] => 1
   //            [withtemplate] =>
   //            [tabnum] => 1
   //            [itemtype] => Computer
   //      )
   //)
}

The hooks that are called with an array of parameters are: post_item_form, pre_item_form, pre_show_item, post_show_item, pre_show_tab, post_show_tab, pre_itil_info_section, post_itil_info_section, item_transfer.

Some hooks will receive a specific array as parameter, they will be detailed below.

Unclassified¶

Hooks that cannot be classified in above categories :)

secured_fields

Added in version 9.4.6.

An array of fields names (with table like glpi_mytable.myfield) that are stored using GLPI encrypting methods. This allows plugins to add some fields to the glpi:security:changekey command.

Warning

Plugins have to ensure crypt migration on their side is OK; and once using it, they must properly declare fields.

All fields that would use the key file without being listed would be unreadable after key has been changed (and stored data would stay potentially unsecure).

secured_configs

Added in version 9.4.6.

An array of configuration entries that are stored using GLPI encrypting methods. This allows plugins to add some entries to the glpi:security:changekey command.

Warning

Plugins have to ensure crypt migration on their side is OK; and once using it, they must properly declare fields.

All configuration entries that would use the key file without being listed would be unreadable after key has been changed (and stored data would stay potentially unsecure).

add_javascript

Add javascript in all pages headers

Added in version 9.2: Minified javascript files are checked automatically. You will just have to provide a minified file along with the original to get it used!

The name of the minified plugin.js file must be plugin.min.js

add_css

Add CSS stylesheet on all pages headers

Added in version 9.2: Minified CSS files are checked automatically. You will just have to provide a minified file along with the original to get it used!

The name of the minified plugin.css file must be plugin.min.css

add_javascript_anonymous_page

Add javascript in all anonymous pages headers

Added in version 10.0.18: Minified javascript files are checked automatically. You will just have to provide a minified file along with the original to get it used!

The name of the minified plugin_anonymous.js file must be plugin_anonymous.min.js

add_javascript_module_anonymous_page

Add javascript module in all anonymous pages headers

Added in version 10.0.18: Minified javascript files are checked automatically. You will just have to provide a minified file along with the original to get it used!

The name of the minified mymodule_anonymous.js file must be mymodule_anonymous.min.js

add_css_anonymous_page

Add CSS stylesheet on all anonymous pages headers

Added in version 10.0.18: Minified CSS files are checked automatically. You will just have to provide a minified file along with the original to get it used!

The name of the minified plugin_anonymous.css file must be plugin_anonymous.min.css

add_header_tag_anonymous_page

Add header tags in all anonymous pages headers

Added in version 10.0.18.

display_central

Displays something on central page

display_login

Displays something on the login page

status

Displays status

post_init

After the framework initialization

rule_matched

After a rule has matched.

This hook will receive a specific array that looks like:

<?php
$hook_params = [
   'sub_type'  => 'an item type',
   'rule_id'   => 'rule id',
   'input'     => array(), //original input
   'output'    => array()  //output modified by rule
];

redefine_menus

Add, edit or remove items from the GLPI menus.

This hook will receive the current GLPI menus definition as an argument and must return the new definition.

init_session

At session initialization

change_entity

When entity is changed

change_profile

When profile is changed

pre_kanban_content

Added in version 9.5.

Set or modify the content that shows before the main content in a Kanban card.

This hook will receive a specific array that looks like:

<?php
$hook_params = [
   'itemtype'  => string, //item type that is showing the Kanban
   'items_id'  => int, //ID of itemtype showing the Kanban
   'content'   => string //current content shown before main content
];

post_kanban_content

Added in version 9.5.

Set or modify the content that shows after the main content in a Kanban card.

This hook will receive a specific array that looks like:

<?php
$hook_params = [
   'itemtype'  => string, //item type that is showing the Kanban
   'items_id'  => int, //ID of itemtype showing the Kanban
   'content'   => string //current content shown after main content
];

kanban_filters

Add new filter definitions for Kanban by itemtype.

This data is set directly in $PLUGIN_HOOKS like:

<?php
$PLUGIN_HOOKS['kanban_filters']['tag'] = [
   'Ticket' => [
      'tag' => [
         'description' => _x('filters', 'If the item has a tag'),
         'supported_prefixes' => ['!']
      ],
      'tagged' => [
         'description' => _x('filters', 'If the item is tagged'),
         'supported_prefixes' => ['!']
      ]
   ],
   'Project' => [
      'tag' => [
         'description' => _x('filters', 'If the item has a tag'),
         'supported_prefixes' => ['!']
      ],
      'tagged' => [
         'description' => _x('filters', 'If the item is tagged'),
         'supported_prefixes' => ['!']
      ]
   ];
]

kanban_item_metadata

Set or modify the metadata for a Kanban card. This metadata isn’t displayed directly but will be used by the filtering system.

This hook will receive a specific array that looks like:

<?php
$hook_params = [
   'itemtype'  => string, //item type that is showing the Kanban
   'items_id'  => int, //ID of itemtype showing the Kanban
   'metadata'  => array //current metadata array
];

vcard_data

Add or modify data in vCards such as IM contact information

<?php
$hook_params = [
   'item'   => CommonDBTM, //The item the vCard is for such as a User or Contact
   'data'   => array, //The current vCard data for the item
];

filter_actors

Add or modify data actor fields provided in the right panel of ITIL objects

<?php
$hook_params = [
   'actors' => array, // actors array send to select2 field
   'params' => array, // actor field param
];

helpdesk_menu_entry

Add a link to the menu for users with the simplified interface

<?php
$PLUGIN_HOOKS['helpdesk_menu_entry']['example'] = 'MY_CUSTOM_LINK';

helpdesk_menu_entry_icon

Add an icon for the link specified by the helpdesk_menu_entry hook

<?php
$PLUGIN_HOOKS['helpdesk_menu_entry_icon']['example'] = 'fas fa-tools';

debug_tabs

Add one or more new tabs to the GLPI debug panel. Each tab must define a title and display_callable which is what will be called to print the tab contents.

<?php
$PLUGIN_HOOKS['debug_tabs']['example'] = [
  [
     'title' => 'ExampleTab',
     'display_callable' => 'ExampleClass::displayDebugTab'
  ]
];

post_plugin_install

Called after a plugin is installed

post_plugin_enable

Called after a plugin is enabled

post_plugin_disable

Called after a plugin is disabled

post_plugin_uninstall

Called after a plugin is uninstalled

post_plugin_clean

Called after a plugin is cleaned (removed from the database after the folder is deleted)

Notifications¶

Hooks that are called from notifications

item_add_targets

When a target has been added to an item

item_get_events

After notifications events have been retrieved

item_action_targets

After target addresses have been retrieved

item_get_datas

After data for template have been retrieved

add_recipient_to_target

Added in version 9.4.0.

When a recipient is added to targets.

The object passed as hook method parameter will contain a property recipient_data which will be an array containing itemtype and items_id fields corresponding to the added target.

Functions hooks¶

Usage¶

Functions hooks declarations are the same than standards hooks one. The main difference is that the hook will wait as output what have been passed as argument.

<?php
/**
 * Handle hook function
 *
 * @param array $data Array of something (assuming that's what we're receiving!)
 *
 * @return array
 */
public function myplugin_updateitem_called ($data) {
   //do everything you want
   //return passed argument
   return $data;
}

Existing hooks¶

unlock_fields: After a fields has been unlocked. Will receive the $_POST array used for the call.
restrict_ldap_auth: Additional LDAP restrictions at connection. Must return a boolean. The dn string is passed as parameter.
undiscloseConfigValue: Permit plugin to hide fields that should not appear from the API (like configuration fields, etc). Will receive the requested fields list.
infocom: Additional infocom information oin an item. Will receive an item instance as parameter, is expected to return a table line (<tr>).
retrieve_more_field_from_ldap: Retrieve additional fields from LDAP for a user. Will receive the current fields lists, is expected to return a fields list.
retrieve_more_data_from_ldap: Retrieve additional data from LDAP for a user. Will receive current fields list, is expected to return a fields list.
display_locked_fields: To manage fields locks. Will receive an array with item and header entries. Is expected to output a table line (<tr>).
migratetypes: Item types to migrate, will receive an array of types to be updated; must return an array of item types to migrate.

Automatic hooks¶

Some hooks are automated; they’ll be called if the relevant function exists in you plugin’s hook.php file. Required function must be of the form plugin_{plugin_name}_{hook_name}.

MassiveActionsFieldsDisplay

Add massive actions. Will receive an array with item (the item type) and options (the search options) as input. These hook have to output its content, and to return true if there is some specific output, false otherwise.

dynamicReport

Add parameters for print. Will receive the $_GET array used for query. Is expected to return an array of parameters to add.

AssignToTicket

Declare types an ITIL object can be assigned to. Will receive an empty array adn is expected to return a list an array of type of the form:

<?php
return [
   'TypeClass' => 'label'
];

MassiveActions

If plugin provides massive actions (via $PLUGIN_HOOKS['use_massive_actions']), will pass the item type as parameter, and expect an array of additional massive actions of the form:

<?php
return [
   'Class::method' => 'label'
];

getDropDown

To declare extra dropdowns. Will not receive any parameter, and is expected to return an array of the form:

<?php
return [
   'Class::method' => 'label'
];

rulePrepareInputDataForProcess

Provide data to process rules. Will receive an array with item (data used to check criteria) and params (the parameters) keys. Is expected to retrun an array of rules.

executeActions

Actions to execute for rule. Will receive an array with output, params ans action keys. Is expected to return an array of actions to execute.

preProcessRulePreviewResults

Todo

Write documentation for this hook.

use_rules

Todo

Write documentation for this hook. It looks a bit particular.

ruleCollectionPrepareInputDataForProcess

Prepare input data for rules collections. Will receive an array of the form:

<?php
array(
   'rule_itemtype'   => 'name fo the rule itemtype',
   'values'          => array(
      'input'  => 'input array',
      'params' => 'array of parameters'
   )
);

Is expected to return an array.

preProcessRuleCollectionPreviewResults

Todo

Write documentation for this hook.

ruleImportComputer_addGlobalCriteria

Add global criteria for computer import. Will receive an array of global criteria, is expected to return global criteria array.

ruleImportComputer_getSqlRestriction

Adds SQL restriction to links. Will receive an array of the form:

<?php
array(
   'where_entity' => 'where entity clause',
   'input'        => 'input array',
   'criteria'     => 'complex criteria array',
   'sql_where'    => 'sql where clause as string',
   'sql_from'     => 'sql from clause as string'
)

Is expected to return the input array modified.

getAddSearchOptions

Adds search options, using “old” method. Will receive item type as string, is expected to return an array of search options.

getAddSearchOptionsNew

Adds search options, using “new” method. Will receive item type as string, is expected to return an indexed array of search options.

Hooks¶

Standards Hooks¶

Usage¶

Without parameters¶

With item as parameter¶

With array of parameters¶

Unclassified¶

Items business related¶

Items display related¶

Notifications¶

Functions hooks¶

Usage¶

Existing hooks¶

Automatic hooks¶