Difference between revisions of "Hooks"

From WHMCS Documentation

(DOCS-6356)
Line 1: Line 1:
 
==What is a Hook?==
 
==What is a Hook?==
  
Action Hooks allow you to add your own code to WHMCS that runs when specific events or actions occur inside the system. WHMCS has over 100 different hook points that you can tie custom code into, and more are being added with each new release.
+
Action Hooks allow you to add your own code to WHMCS. The code will run when specific events or actions occur inside the system. WHMCS has over 100 different hook points. These you can tie custom code into. With each new release, WHMCS adds more hook points.
  
The possibilities with hooks are endless, but some common examples of what you might use them for are:
+
The possibilities with hooks are many, but some common examples of what you might use them for are:
  
*Registering users in another system when they signup via WHMCS
+
*Registering users in another system when they signup via WHMCS.
*Keeping user details in sync with third party applications
+
*Keeping user details in sync with third party applications.
*Performing additional custom actions when an order is placed in WHMCS
+
*Performing extra custom actions when placing an order in WHMCS.
*Sending notifications when certain events occur
+
*Sending notifications when certain events occur.
  
 
{{Hook_Categories}}
 
{{Hook_Categories}}
Line 14: Line 14:
 
==Creating a Hook==
 
==Creating a Hook==
  
Hooks work by defining a function, and then tieing that function into a hook point. Most custom hook functions are created as a standalone hook, and thus reside in the /includes/hooks/ folder. But hooks can also be part of modules (more details later on this).
+
Hooks work by defining a function, and then tying that function into a hook point. Most custom hook functions are standalone hooks, and thus live in the /includes/hooks/ folder. Hooks can also be part of modules (more details later on this).
  
Custom hook functions are usually passed variables when they are called, with the variables depending on the action the hook point relates to. Some hook points will also accept a return from your custom hook function, and that allows you to influence what the system does next from your custom code.
+
Custom hook functions have variables passed when called. The variables depend on the action the hook point relates to. Some hook points will also accept a return from the custom hook function. Returns will allow influence with what the system does next from the custom code.
  
We recommend naming hook functions always starting with "hook_", followed by the filename, and then the particular action or task that hook is performing. For example "hook_filename_action" - "hook_forumsetup_addclient". This helps to ensure that no 2 hook functions from 2 separate developers ever conflict due to naming issues.
+
WHMCS recommends naming hook functions always starting with "hook_". Following this, the filename. Finally the particular action or task that hook is performing. For example "hook_filename_action" - "hook_forumsetup_addclient". This will ensure that no hook functions ever conflict due to naming issues.
  
 
==Sample Code==
 
==Sample Code==
  
The best way to see how hooks work is with an example, so here's an example using the [[Hooks:ClientAdd|Client Signup hook]] event that could be used to create an account on an external system such as a forum:
+
The best way to see how hooks work is with an example. Below is an example using the [[Hooks:ClientAdd|Client Signup hook]] event. A developer could use this event to create an account on an external system such as a forum:
  
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
Line 50: Line 50:
 
==Module Hooks==
 
==Module Hooks==
  
Modules support hooks being defined that relate to a module within the relevant module directory; /modules/addons/ for addon, /modules/servers/ for provisioning and /modules/registrars for registrar modules.
+
Modules support hooks that relate to a module within the relevant module directory. This is /modules/addons/ for addon, /modules/servers/ for provisioning and /modules/registrars/ for registrar modules.
  
To define hooks as part of a module, simple create a file named "hooks.php" within the module folder, and include all module specific hook related code within that file.
+
To define hooks as part of a module, simple create a file named "hooks.php" within the module folder. A developer can then include all module specific hook related code within that file.
  
''Note to Developers:'' Hook files in module folders are only called for active modules. And active modules that contain hooks are cached. So if you add a hooks file to a module retrospectively, once the module is already active, then before the system will detect and start running that module, you must edit and resave either the addon module configuration, product configuration or domain registrar configuration for the respective module for it to be detected.
+
''Note to Developers'': Hook files in module folders are only called for active modules. And active modules that contain hooks become cached. If a developer add a hooks file to a module after activation, the cache must refresh. To refresh the cache, edit and re-save either the appropriate module configuration.
  
 
==Hook Points==
 
==Hook Points==
  
We've divided the hooks up into categories to help make the list more managable. So simply choose an option from below to see the hooks which exist for that category.
+
We've divided the hooks up into categories to help make the list more manageable. So choose an option from below to see the hooks which exist for that category.
  
 
{{Hook_Categories}}
 
{{Hook_Categories}}

Revision as of 07:00, 22 February 2016

What is a Hook?

Action Hooks allow you to add your own code to WHMCS. The code will run when specific events or actions occur inside the system. WHMCS has over 100 different hook points. These you can tie custom code into. With each new release, WHMCS adds more hook points.

The possibilities with hooks are many, but some common examples of what you might use them for are:

  • Registering users in another system when they signup via WHMCS.
  • Keeping user details in sync with third party applications.
  • Performing extra custom actions when placing an order in WHMCS.
  • Sending notifications when certain events occur.

Creating a Hook

Hooks work by defining a function, and then tying that function into a hook point. Most custom hook functions are standalone hooks, and thus live in the /includes/hooks/ folder. Hooks can also be part of modules (more details later on this).

Custom hook functions have variables passed when called. The variables depend on the action the hook point relates to. Some hook points will also accept a return from the custom hook function. Returns will allow influence with what the system does next from the custom code.

WHMCS recommends naming hook functions always starting with "hook_". Following this, the filename. Finally the particular action or task that hook is performing. For example "hook_filename_action" - "hook_forumsetup_addclient". This will ensure that no hook functions ever conflict due to naming issues.

Sample Code

The best way to see how hooks work is with an example. Below is an example using the Client Signup hook event. A developer could use this event to create an account on an external system such as a forum:

/**
 * Add hook function call.
 *
 * @param string $hookPoint The hook point to call
 * @param integer $priority The priority for the given hook function
 * @param string|function Function name to call or anonymous function.
 *
 * @return Depends on hook function point.
 */
add_hook('ClientAdd', 1, function ($vars) 
{
    $userid = $vars['userid'];
    $firstname = $vars['firstname'];
    $lastname = $vars['lastname'];
    $email = $vars['email'];
    $password = $vars['password'];

    // Run code to create remote forum account here...
});
Anonymous functions, also known as closures, are supported for the function to be called as demonstrated in the example above.

Module Hooks

Modules support hooks that relate to a module within the relevant module directory. This is /modules/addons/ for addon, /modules/servers/ for provisioning and /modules/registrars/ for registrar modules.

To define hooks as part of a module, simple create a file named "hooks.php" within the module folder. A developer can then include all module specific hook related code within that file.

Note to Developers: Hook files in module folders are only called for active modules. And active modules that contain hooks become cached. If a developer add a hooks file to a module after activation, the cache must refresh. To refresh the cache, edit and re-save either the appropriate module configuration.

Hook Points

We've divided the hooks up into categories to help make the list more manageable. So choose an option from below to see the hooks which exist for that category.