Introduction
To create a custom module, you must first create the Module.pm file.
Warning:
Make certain that you thoroughly test custom modules before you attempt to add them to production servers.
The Module.pm file
Save your custom module as the /usr/local/cpanel/Cpanel/API/Module.pm file, where Module is the custom module's name.
Notes:
- We recommend that you use a CamelCase module name.
- UAPI modules cannot use the same name as an existing UAPI module.
- UAPI module names should not begin with an underscore (
_).
We recommend that you begin with the following file template:
|
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
|
package Cpanel::API::Module;use strict;our $VERSION = '1.0';# Your comments about this custom module.# Cpanel Dependenciesuse Cpanel ();use Cpanel::API ();use Cpanel::Locale ();use Cpanel::Logger ();# Other dependencies go here.# Defaults go here.# Constants go here.# Globalsmy $logger;my $locale;# Caches go here. # Functions go here. 1; |
Package the module
|
1
|
package Cpanel::API::Module; |
This declaration instructs Perl to treat all of the file's functions as a part of the Cpanel::API::Module namespace.
For more information, read perldoc.perl.org's package documentation.
Set the strict pragma
|
3
|
use strict; |
This declaration instructs Perl to return errors if the file contains potentially unsafe code.
For more information, read perldoc.perl.org's strict documentation.
Declare a module version
|
5
|
our $VERSION = '1.0'; |
This declaration creates the variable $VERSION and sets it to 1.0. This allows you to differentiate between this and future versions of your module.
cPanel dependencies
|
9
10
11
12
13
|
# Cpanel Dependenciesuse Cpanel ();use Cpanel::API ();use Cpanel::Locale ();use Cpanel::Logger (); |
While UAPI calls do not require that you include these dependencies, we recommend that you include them.
For more information, read perldoc.perl.org's use documentation.
Note:
If you include the use Cpanel::API statement, your functions can call functions from any other custom or cPanel-provided UAPI module. Remember that those UAPI functions may have additional feature list requirements.
Additional dependencies, defaults, and constants
|
15
16
17
18
19
20
21
22
23
|
# Other dependencies go here.# Defaults go here.# Constants go here. # Globalsmy $logger;my $locale; # Caches go here. |
Use the lines below the Cpanel:: dependencies to declare dependencies on additional Perl modules, declare default values for variables, set constant values, and set caches.
UAPI modules that use the Cpanel::Logger and Cpanel::Locale objects should also declare the $logger and $locale global variables.
Functions
|
25
|
# Functions go here. |
Module files contain at least one function.
For more information, read our Custom Function Basics documentation.
End the module file
End your module file with the following line:
|
27
|
|
Note:
Perl requires that module files return true in order to function. This line fulfills that requirement.