Standardized Hooks: Abstract
For cPanel & WHM 11.32
The Standardized Hooks documentation is currently under revision. You should check back shortly for improvements to this information.
Our Standardized Hooks system implements several methods of hooking into cPanel & WHM functionality. For the first time, these hooking systems are unified into a single, standard system.
The Standardized Hooks system is useful for developers and administrators who want to automatically trigger a script or application when a specific action is performed in cPanel. It allows you to customize the way cPanel functions and communicates with external systems across a variety of different scenarios.
Some important features of the Standardized Hooks system are:
- You can run multiple hooks when a single action occurs.
- The system allows you to write a hook as a Perl module or any other script.
- The Standardized Hooks systems is consistent with the management interface (CLI).
- This system provides a framework to determine how a hook should execute and what the hook should do in case of a failure.
- The Standardized Hooks system can hook into most major accounting features, API 1, API 2, and some system functionality.
- This system can deny certain actions.
- The Standardized Hooks system allows your applications to co-exist with other applications on a cPanel & WHM server, without having overlap issues when both applications hook into the same function.
The Standardized Hooks system functions from a hooks database that contains all of the hooks that exist on a system.
This database (sometimes called a registry) contains basic information about the system's hooks. This information includes whether the hook is a module or script, the order in which the hook(s) will run, and the user as which the hook will run. These parameters are all controlled by the
This file contains entries (or multiple entries) for each hook on the system. These entries contain the various attributes that describe how the hook is run.
This file is located at
Each of the following parameters is required
|| The hook insertion point's namespace.
|| The hook insertion point's function within the specified namespace.
|| The stage of the function at which to execute the hook.
|| The path to the application or script (hook) to run.
The following parameters are optional
|| A boolean value that indicates whether the hook should run as
|| A string value that points to another piece of code, which determines whether the hook will run.
|| A string value that points to another piece of code, which executes whenever a hook fails. For more information, view our Advanced Hook Usage documentation.
|| The priority for running the hook. Lower numbers indicate the hook should execute earlier. This value defaults to
1000, and can be set to any integer
0 or greater.
This file does not exist on cPanel & WHM systems until a standardized hook is created.
Contexts (hook insertion points)
cPanel & WHM contains code that defines hook insertion points. These hook insertion points are also called contexts, and are ultimately responsible for calling the Standardized Hooks system.
A hook insertion point is defined with a few parameters.
The following parameters are required
|| The namespace of the function to call. This value determines which hash should be pulled from
/var/cpanel/hooks.yaml. Some examples include
|| The function on which the hook will act (e.g.,
|| The stage of the hook. This value is generally
post, indicating whether the hook should be called before or after the specified action.
All of the required arguments are used within the hooks database. This is because the system uses the parameters defined here, in the context, to determine whether the hook should run.
The following parameters are optional
|| A boolean value that indicates whether or not the call should be allowed to run with
|| A boolean value specifying how the overlying code will behave if the hook fails. This parameter has important implications when dealing with hooks that can roll back (undo) their actions.
When using this system, your hook can be either a Perl module or a script. There are advantages and disadvantages to each method. The following section attempts to compare those advantages and disadvantages.
Generally, it is best to write a Perl module hook unless you have a specific reason to do otherwise. For example, if you have no knowledge or Perl, require escalated privileges, or if a critical Perl module is not compatible with cPanel's internal Perl, you should use a script hook.
- Scripts are slower than modules.
- Scripts do not provide as much access to cPanel & WHM internals as Perl modules.
- Scripts allow you development in multiple languages.
- Scripts can run with escalated privileges.
- Perl modules are faster than scripts because they do not require executing another process.
- Perl modules provide full access to processes that execute the application.
- Perl modules use fewer resources because the system does not need to execute another binary in order to run the module.
- Basic Usage — This document explains two main components of the Standardized Hooks system. We strongly recommend reading this document next.