Introduction
Custom modules can define additional hookable events for the Standardized Hooks System. In essence, the system treats non-cPanel code that runs as a cPanel process as a native hookable event.
Requirements
Your custom module must meet the following minimum requirements for hookable events:
-
The calling code must be part of cPanel & WHM's runtime process (for example, a cPanel or WHM plugin).
Note:
It should be possible to leverage the Standardized Hooks System outside of cPanel processes; however, certain features, such as privilege escalation, will not work and will likely encounter errors. Generally speaking, we do not recommend using Standardized Hooks outside of a cPanel process.
- The calling code must be Perl and must use the
Cpanel::Hooksmodule.
We recommend that developers observe the following practices for consistency and expectations:
- In your custom code, bookend the primary logic with both a
preandpoststage. Most cPanel-provided hookable events include these stages. - For
prestages, observe the return value and do not perform the primary logic. While the Standardized Hooks System will handle the rollback actions, the caller must not allow the requested event to occur. - Allow
poststages to occur in a meaningful way with respect to the primary logic. Usually, this you must dispatch thepoststage and provide a dataset that clearly shows whether the primary logic completed successfully.
Examples
The following Perl module includes custom hookable events:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
|
package Cpanel::MyCustom;use strict;use warnings;use Cpanel::Hooks ();sub awesome { my %OPTS = @_; my $return_value = { 'status' => 0, 'status_msg' => undef }; my ( $hook_result, $hook_msgs ) = Cpanel::Hooks::hook( { 'category' => 'MyCustom', 'event' => 'awesome', 'stage' => 'pre', 'blocking' => 1, }, \%OPTS, ); my $awesome_data; if ( !$hook_result ) { my $hooks_msg = ( int @{$hook_msgs} ) ? join( "\n", @{$hook_msgs} ) : ''; $return_value->{'status_msg'} = 'Hook denied completion of ' ."Cpanel::MyCustom::awesome(): $hooks_msg"; } else { # === do primary logic here === # $awesome_data = { 'in_realworld' => 'this likely be the return a a subroutine', 'has_pass_criteria' => 'up to the subroutine that does the work', }; # === set response accordingly === # $return_value->{'data'} = $awesome_data; if ( $awesome_data->{'has_pass_criteria'} ) { $return_value->{'status'} = 1; $return_value->{'status_msg'} = 'Successfully achieved awesomeness.'; } else { $return_value->{'status_msg'} = 'Failed to achieve awesomeness.'; } } Cpanel::Hooks::hook( { 'category' => 'MyCustom', 'event' => 'awesome', 'stage' => 'post', }, $return_value, ); return $return_value;}1; |