Taxonomy of the Standardized Hooks System

The Standardized Hooks System is contained within the Cpanel::Hooks Perl namespace and the manage_hooks executable.

The Standardized Hooks System consists of 6 parts. The following sections provide explanations of these parts.

The Standardized Hooks System observer & dispatch subsystems

The Standardized Hooks System utilizes an observer pattern. When cPanel & WHM code signals the Standardized Hooks System that a particular event is occurring, the system observes the signal and starts a dispatch loop. This signal point is referred to as a hookable event.

The dispatch loop will iterate through each piece of registered hook action code, executing them, and tracking their return value.

Hookable event descriptors and attributes

category

event

stage

When cPanel & WHM code invokes the Standardized Hooks System to perform a hookable event, the invoker is responsible for specifying the descriptors. They are used by the system when sourcing hook action code from the hooks database, prior to executing the dispatch subsystem.

The invoker is also responsible for providing any attributes that should be used with constructing the dispatch loop.

blocking

Note: when the blocking attribute is specified in the construction of the dispatch loop, the rollback logic is imported.

escalateprivs

Please note that the descriptors and attributes above have been defined from the perspective of the cPanel & WHM code that is implementing the hookable event. For more information, please see the hookable events section.

The Hook action code

Hook action code is custom code, either a script or a Perl module, authored by a developer or system administrator. This code is executed by cPanel & WHM at specific points called hookable events. Without hook action code, the Standardized Hooks System will remain dormant while cPanel & WHM performs its routines.

Hook action code is used as a subject by the observer subsystem and provided to the dispatch subsystem. A dispatch loop is constructed and iterated through, executing each related hook action.

For information about creating hook action code, please review the getting started? section.

The Standardized Hooks management interface

Hook action code must be associated with a hookable event so that it is executed by cPanel & WHM within respective runtime processes. These associations are established using the Standardized Hooks management CLI utility. You can use this utility to add, delete, list, or get help about registered Standardized Hooks on the local server.

The CLI utility takes Standardized Hooks descriptors and a reference to the hook action code, creating an entry in the Standardized Hooks System database.

For a complete guide on using this utility, please review our Standardized Hooks Management document.

The Standardized Hooks System database

The Standardized Hooks System database is a datastore that contains registry entries. These entries link hook action code to particular cPanel & WHM routines, known as hookable events. The entries are managed using the CLI utility, mentioned above.

For more information on how Standardized Hooks are managed, please review our Standardized Hooks Management document.

Standardized Hooks debugging

The observer and dispatch subsystems can log their actions using the system's debug mode. Debugging is enabled on the server level, with several levels of verbosity from which to choose. Additionally, Perl developers can use a supplied Perl module that provides a limited set of subroutines to selectively trace actions when debugging code.

For information about how to use this utility, you should review the debugging section of the getting started guide.