UAPI - Custom Function Basics - Knowledgebase

Introduction

Custom modules contain one or more individual functions.

Warning:

Make certain that you thoroughly test custom modules before you attempt to add them to production servers.

Functions

Notes:

Write all of the functions for a custom module in the same Module.pm file.
The examples below use the following variables:
- Module — The custom module's name.
- function — The name of a function in the custom module.

For each function that you wish to include in your module, we recommend the following format and elements:

#-------------------------------------------------------------------------------------------------
# Name:
#   function - Choose a function name that describes the function's action.
# Desc:
#   A description of the function function's action.
# Arguments:
#   $arg1 - string - A description of the $arg1 parameter.
# Returns:
#   $result1 - string - A description of the $result1 parameter.
#-------------------------------------------------------------------------------------------------
sub function {
 
    my ( $args, $result ) = @_;
    my ( $arg1, $arg2 ) = $args->get( 'arg1', 'arg2' );
 
    # (Optional) Set a feature that the cPanel user must have in order to access the function.
    my $feature = 'featurename';                            
    if ( !main::hasfeature($feature) ) {                    
        $result->error( '_ERROR_FEATURE', $feature );
        return;
    }
  
    # Make the function unusable if the cPanel account is in demo mode.
    if ( $Cpanel::CPDATA{'DEMO'} ) {
        $result->error( '_ERROR_DEMO_MODE', $feature );
        return;
    }
 
    # Validate the required parameters.
    # Sanitize the arguments.
    # Perform the function's action(s).
  
    # Build the results.
    if ($success) {
        $result->data($successful_data);
        return 1;
    }
    else {
        return 0;
    }
}

Function information

#-------------------------------------------------------------------------------------------------
# Name:
#   function - Choose a function name that describes the function's action.
# Desc:
#   A description of the function function's action.
# Arguments:
#   $arg1 - string - A description of the $arg1 parameter.
# Returns:
#   $result1 - string - A description of the $result1 parameter.
#-------------------------------------------------------------------------------------------------

We strongly encourage you to include a summary of each function in the form of comments. This practice is beneficial both to your future self, and to other developers who may use your code.

The function subroutine

sub function { 

Write each function in a UAPI module as a subroutine.

Notes:

We recommend that you use lowercase function names.
If your function name includes multiple words, separate each word with an underscore (_) for readability.
UAPI considers functions with names that begin with an underscore ( _ ) to be private functions.
- You cannot call these functions through UAPI.
- These functions will not display in cPanel's API Shell interface (Home >> Advanced >> API Shell).

For more information about subroutines in Perl, read perldoc.perl.org's perlsub documentation.

Get arguments from @_

Important:

We strongly recommend that all custom functions begin with this line of code. Functions that do not perform this action will experience errors.

my ( $args, $result ) = @_;

This code declares the $args and $result variables, and assigns values from @_.

The Cpanel::Args object allows UAPI calls to receive named parameters.
The Cpanel::Result object allows UAPI calls to return function data.

Use the `get()` method to assign variables

my ( $arg1, $arg2 ) = $args->get( 'arg1', 'arg2' );

This code assumes that the arg1 and arg2 input parameters exist. It uses the Cpanel::Args object's get() method to assign these parameters' values to the $arg1 and $arg2 variables.

Require a feature

You can choose to require specific features in order to call the function. Replace featurename with the name of the feature to require.

# (Optional) Set a feature that the cPanel user must have in order to access the function.
my $feature = 'featurename';                           
if ( !main::hasfeature($feature) ) {                   
    $result->error( '_ERROR_FEATURE', $feature );
    return;
}

This if statement uses built-in cPanel & WHM functionality to check whether the account has access to the specified feature. If the cPanel user does not have the access to the required feature, the function will return an error message and will not perform any other actions.

For example, the following code requires that a cPanel user has the filemanager feature in order to call the function:

my $feature = 'filemanager';                           
if ( !main::hasfeature($feature) ) {                   
    $result->error( '_ERROR_FEATURE', $feature );
    return;
}

Disallow demo mode

In most cases, you should not allow your custom module to function on cPanel accounts that are in demo mode.

# Make the function unusable if the cPanel account is in demo mode.
if ( $Cpanel::CPDATA{'DEMO'} ) {
    $result->error( '_ERROR_DEMO_MODE', $feature );
    return;
}

This if statement uses built-in cPanel & WHM functionality to check whether the cPanel account is a demo account. If a demo cPanel account attempts to call your function, the function call with return an error message and will not perform any other actions.

Perform the desired actions

# Validate the required parameters.
# Sanitize the arguments.
# Perform the function's action(s).

This section of the subroutine is where your function performs its own unique actions.

These actions could combine any of Perl's many functions. Often, this includes the following actions:

Validate the data that you passed into variables in line 13.
Sanitize this data (for example, use the chomp() function to remove trailing newlines).
Check data in other files.
Write data to other files.

Result data and returns

At the end of your function, you can use the Cpanel::Result object's data() method to assign values to a hash or array of hashes of named output parameters.

Output in an array of hashes allows you to use UAPI's filter, sort, and pagination options.
The only meaningful return values in Perl are 1 (for success) and 0 (for failure).
While Perl allows bare return values, we do not recommend that you use them in UAPI functions. In some circumstances, the system may misinterpret bare return values as true.

    # Build the results.
    if ($success) {
        $result->data($successful_data);
        return 1;
    }
    else {
        return 0;
    }
}

This example code assumes that, at some point during the function's actions, the subroutine initialized and assigned values to the $success and $successful_data values.

Note:

In line 35, this example feeds the $successful_data value into the data hash, to return output parameters. The API also returns the standard UAPI metadata. For more information, read our Return Data documentation.

Note:

If your return data contains any strings with Unicode characters that are binary encoded, and that display on a cPanel interface, you will receive a Wide Character warning. To resolve this, use the following code to encode your strings:

use Encode qw(encode);
$result->data( encode( 'utf-8', $successful_data ) );

Knowledgebase

Categories

Categories