Child pages
  • Guide to the LiveAPI System - Perl Module
Skip to end of metadata
Go to start of metadata

 

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

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:

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.