Child pages
  • UAPI - Create Your Module
Skip to end of metadata
Go to start of metadata

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 install them to production servers.

The Module.pm file

Save your custom module as the  /usr/local/cpanel/Cpanel/API/Module.pm file, where Module represents the 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:

package Cpanel::API::Module;

use strict;

our $VERSION = '1.0';

# Your comments about this custom module.

# Cpanel Dependencies
use Cpanel                   ();
use Cpanel::API              ();
use Cpanel::Locale           ();
use Cpanel::Logger           ();

# Other dependencies go here.
# Defaults go here.
# Constants go here.

# Globals
my $logger;
my $locale;

# Caches go here.
 
# Functions go here.
 
1; 

Package the module

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

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

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

# Cpanel Dependencies
use 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

# Other dependencies go here.
# Defaults go here.
# Constants go here.
 
# Globals
my $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

# Functions go here.

Module files must 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:

1; 

Note:

Perl requires that module files return a true value in order to function. This line fulfills that requirement.