Troubleshooting & Debugging Hooks
Hooks are a way to customise and allow you to execute your own code when specific events occur inside WHMCS.
When creating a hook you will often want to know if the hook point was triggered and, once triggered, did the code load or execute? You may also want to output the values of your variables or arrays, during various stages, to check to see if the code did execute correctly for debugging purposes.
This guide steps through the various methods of debugging and troubleshooting hooks.
To Check if your Hook is Loading
Navigate to Configuration > System Settings > General Settings > Other Tab
1. Check the Hooks Debug Mode checkbox.
2. Click Save Changes.
3. Perform the action to trigger the action hook point.
Hook activity will now be logged in the Activity Log.
NOTE: Enabling this option will result in a large number of Activity Log entries, so it should be used sparingly and only when debugging hook problems. It should then promptly be switched off.
To view the Activity log, navigate to Configuration > System Logs.
For more information regarding Log Activity, please see our Logging developer documentation.
To Check that your Hooks are Triggering
Once we know that a custom hook file was loaded, we still need to check to see if the hook point used in that file is actually being triggered. The distinction here is the triggering or firing of the hook, which is also a means to check and confirm if a particular hook point is working.
In this log entry, for example, we can see that the AdminAreaFooterOutput hook point was triggered.
To Check if your Hook Code is Executing
Once you know the hook point is being triggered, you will want to check to see if your code is executing. One way to do this is by simply using is the logActivity() function. The advantage to this is that you can debug and check to see what variables are present when the hook is triggered.
Add the following at the end of your code:
logActivity('Hook variables: '.print_r($vars, true));Here is how it would be implemented using the AdminAreaFooterOutput as an example:
<?php
if(!defined('WHMCS')) {
die('This hook should not be run directly');
}
add_hook('AdminAreaFooterOutput', 1,function($vars) {
logActivity("AdminAreaFooterOutput hook has run. Posted Vars: ". print_r($vars, true));
});While Hooks Debug Logging is enabled, you will see these variables in the Activity Log for debugging purposes.
To Ensure Module Hooks Run
Hooks may be inserted into modules. If you want your hook to only run for specific products, you would need to add checks for that in your code.
The hook code will be triggered every time a module command is run for any module as long as the module that has the hook is active under Configuration > System Settings > Addon Modules.
Please note: If a module is already active, then deactivating it can result in data loss. Therefore, it is always wise to create a backup of both your files and data before deactivation of a module is attempted.
To Ensure Changes to Module Hooks Run on Active Modules
Generally speaking, hook files will be detected and loaded by WHMCS on every page load. However, this may vary depending on the module type.
For module hooks, hook files are detected at the time a provisioning, registrar, or addon module is activated. However, if a hook file is added or modified after the module has already been activated, some additional steps may need to be performed to rebuild the hook cache and for WHMCS to recognize it.
- For Provisioning Modules, this can be accomplished by accessing the Module Settings tab of an applicable product under Configuration > System Settings > Products/Services and clicking Save Changes.
- For a Registrar Module, re-saving the settings for it under Configuration > System Settings > Products/Services > Domain Registrars would be sufficient.
- For Addon Modules, re-saving the settings under Configuration > System Settings > Addon Modules will address this.
For further information, visit Defining Hooks Within A Module.