Development Guides Home >> Guide to the LiveAPI System

Guide to the LiveAPI System - Perl Module

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. An example ships with cPanel & WHM as the /usr/local/cpanel/base/frontend/jupiter/integration_examples/example.live.pl file.

Basic use

• 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 PHP class 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.
$cpliveapi->end();

Instantiate the Cpanel::LiveAPI object

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

This 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();

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

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

Call cPanel & WHM API 1 functions

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

This uses 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.

• 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.
 $cpliveapi->end();

This 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.