Guide to the LiveAPI System - Perl Module - Knowledgebase

Introduction

The LiveAPI Perl Module provides an environment for Perl applications. You can find this Perl module in the /usr/local/cpanel/Cpanel/LiveAPI.pm file.

Note:

An example script ships with cPanel & WHM in the /usr/local/cpanel/base/frontend/x3/test.live.pl file. Because this script uses LiveAPI to execute through cPanel & WHM, it will not run successfully from the command line.

Basic use

Remember:

Perl applications that use the LiveAPI Perl module must instantiate the Cpanel::LiveAPI object.
Perl scripts' filenames must end in either the .livepl or .live.pl file extensions.
Save files to the /usr/local/base/frontend/theme/ directory, where theme is the cPanel theme, or create a symlink to the appropriate files.

The following example script uses the LiveAPI Perl module to call the DomainInfo::domains_data UAPI function:

#!/usr/bin/perl 
 
# Instantiate the Cpanel::LiveAPI object.
use Cpanel::LiveAPI ();
 
# Connect to cPanel - only do this once.
my $cpliveapi = Cpanel::LiveAPI->new();
 
# Get domain user data.
my $get_userdata = $cpliveapi->uapi(
    'DomainInfo', 'domains_data',
    {
        'format'    => 'hash',
    }
);
 
# Perform the desired actions.
 
# Disconnect from cPanel - only do this once.
$cpanel->end();

Instantiate the `Cpanel::LiveAPI` object

# Instantiate the Cpanel::LiveAPI object.
use Cpanel::LiveAPI ();

Line 4 instantiates the Cpanel::LiveAPI object. This ensures that the script or application uses the LiveAPI Perl module. For more information, read the perldoc.perl.org perlobj documentation.

Connect to cPanel & WHM

# Connect to cPanel - only do this once.
my $cpliveapi = Cpanel::LiveAPI->new();

Line 7 uses the LiveAPI new() method to connect to cPanel & WHM. For more information, read our LiveAPI Methods documentation.

Important:

You must include this line in all LiveAPI Perl code.
Only include this line once in any file.

Call cPanel & WHM API functions

# Get domain user data.
my $get_userdata = $cpliveapi->uapi(
    'DomainInfo', 'domains_data',
    {
        'format'    => 'hash',
    }
);

Lines 10 through 15 use the uapi() method to call the DomainInfo::domains_data UAPI function, and assign the function's output as a hash reference to the $get_userdata variable.

Notes:

You can call multiple functions in a single file.
For more information and use examples, read that function's documentation. All cPanel API 1, cPanel API 2, and UAPI function documents include specific examples for the LiveAPI Perl module.

Perform the desired actions

# Perform the desired actions.

Your script or application's actions could combine any of Perl's many functions. Often, this includes the following actions:

Validate data.
Sanitize data (for example, use the chomp() function to remove trailing newlines).
Check data in other files.
Write data to other files.

Disconnect from cPanel & WHM

# Disconnect from cPanel - only do this once.
$cpanel->end();

Line 19 uses the end() method to deconstruct the Cpanel::LiveAPI object and close the connection to cPanel & WHM. For more information, read our LiveAPI Methods documentation.

Warning:

You must close the connection to cPanel & WHM at the end of LiveAPI scripts and applications.

Knowledgebase

Categories

Categories