The LiveAPI PHP Class

For cPanel & WHM 11.30

Introduction

The LiveAPI PHP class is a PHP environment you can utilize within cPanel. This PHP environment provides PHP scripts with a local socket to the cPanel binary, cpsrvd.

This method prevents you from having to:

• Embed cPanel tags.
• Use cpphp or phpcp tags.
• Make remote API calls via XML or JSON APIs, as these calls require greater network overhead.

/usr/local/cpanel/php/cpanel.php is a PHP class that provides common elements for this integration.

API calls are executed by the system's user and will fail if the user has insufficient permissions. The same rules apply to LiveAPI as apply to API tags or API calls made through the XML or JSON APIs.

To begin, you must ensure that your application meets the following 3 criteria:

1. You must include usr/local/cpanel/php/cpanel.php and instantiate the CPANEL object.
2. Your PHP scripts' file names must end in either .livephp or .live.php
3. You must place your PHP script in /usr/local/cpanel/base/frontend/$THEME. Symlinks are permitted.
   • Note: You will need to replace $THEME in the example above with the name of your theme (e.g., x3 in most cases).

This document is a transcription of the PHP DocBlock comments within the cpanel.php class. PHP developers will find more exact information within the comment blocks.

Synopsis

require_once "/usr/local/cpanel/php/cpanel.php";
$cpanel = new CPANEL();
$live_api_result_array = $cpanel->api2( $module, $function, array( 'key1' => 'value1', 'key2' => 'value2') );

The CPANEL PHP Class

Class Description

Class Description	Class Variables	Class Methods

This class provides an interface to the local system's cPanel binary. It allows you to make API calls from a PHP object and avoid the use of cPanel tag markup. Both API 1 and API 2 are available through this class.

• Version: 2.1 — You can find this class at /usr/local/cpanel/php/cpanel.php
• Copyright: cPanel, Inc.
• License: Modified BSD
• Note: Old versions of this class, as well as versions of cPanel prior to 11.28, depend on /usr/local/cpanel/php/xml.php for backward compatibility.

Class Variable Summary

Class Description	Class Variables	Class Methods

Environment Variables

• There are two environment variables that can affect the behavior of this class at object instantiation:
  • LIVEPHP_DEBUG_LEVEL — Enable or disable debugging (can be overridden by accessor methods set_debug()).
  • LIVEPHP_DEBUG_LOG — The absolute path and filename for a debug log. By default, a random log will be created in user's home directory (e.g., ~/.cpanel/livephp.log.$rand ) .

Public Variables

• N/A

Private Variables

• Private variables are not itemized here. See cpanel.php

Class Method Summary

Class Description	Class Variables	Class Methods

Public Methods

• object __construct ()
• array api ( string $reqtype, string $version, string $module, string $func, mixed $args)
• array api1 (string $module, string $func, array $args)
• array api2 (string $module, string $func, array $args)
• boolean cpanelfeature (string $feature)
• boolean cpanelif (string $code)
• string cpanellangprint (string $key)
• string cpanelprint (string $var)
• void end ()
• array exec (string $code[, boolean $skip_return])
• array fetch (string $var)
• integer get_debug_level ()
• string get_debug_log ()
• mixed get_result ()
• void set_debug (integer $debug_level)

Private Methods

• Private variables are not itemized here. See cpanel.php.

Class Method Details

__construct()

Description	Instantiates the CPANEL object. Responsible for establishing communication with the cPanel API engine.
Return	object — An object to perform API queries.
Access	Public
Example	new CPANEL ()

api()

Note: The api1(), api2(), and cpanel*() methods are preferred, as they call this method internally.

Description	Executes a cPanel API call.
Return	array — Returned response in an array data structure.
Access	Public
Example	api ($reqtype, $version, $module, $func, $args)

Parameters:

• $reqtype (string) — The type of request. This value is usually exec.
• $version (integer) — The API version. This value is either 1 or 2.
• $module (string) — The API 1 or API 2 module to execute.
• $func (string) — The API 1 or API 2 function to execute.
• $args (mixed) — Any arguments you wish to pass to the API function. API 1 arguments must be in an ordered array, while API 2 arguments are an associative array; string for non exec $reqtypes.

api1()

Description	Executes an API 1 query.
Return	array — Returned response from the API1 function.
Access	Public
Example	api1 ($module, $func, $args)

Parameters:

• $module (string) — The module's namespace (e.g., SSL).
• $func (string) — The function you wish to call (e.g., showcrt).
• $args (array) — The arguments you wish to pass to the function (e.g., array(0=>'foo.tld', 1=>0) ).
  • Note: Arguments should be passed in an ordinal array (e.g., array(0=>'funcArg1', 1=>'funcArg2')).

api2()

Description	Executes an API 2 query.
Return	array — Returned response from the API2 function.
Access	Public
Example	api2 ($module, $func, $args)

Parameters:

• $module (string) — The module's namespace (e.g., SSL).
• $func (string) — The function you wish to call (e.g., listsslitems).
• $args (array) — The arguments you wish to pass to the function (e.g., array('domains'=>'foo.tld|bar.tld', 'items'=>'key|crt') ).
  • Note: Arguments should be passed in an associative array.

cpanelfeature()

Description	This method functions as a wrapper for cPanel feature tags.
Return	boolean — Whether the current cPanel account has access to the feature.
Access	Public
Example	cpanelfeature ($feature)

Parameters:

• $feature (string) — A feature name or logical expression related to a cPanel feature. For more information, visit our documentation about using cPanel feature tags.

cpanelif()

Description	This method functions as a wrapper for the cpanelif tag.
Return	boolean — Whether the $code expression evaluates as true or false.
Access	Public
Example	cpanelif ($code)

Parameters:

• $code (string) — A cPvar or logical test condition. For more information, please visit our documentation about conditionals.

cpanellangprint()

Description	This method functions as a wrapper for the cPanel langprint function.
Return	string — Translated version of the requested language key.
Access	Public
Example	cpanellangprint ($key)

Parameters:

• $key (string) — A language key.

cpanelprint()

Description	This method functions as a wrapper for the cPanel print function.
Return	string — The value of the queried ExpVar or text.
Access	Public
Example	cpanelprint ()$var)

Parameters:

• $var (string) — An expression that may contain a ExpVar or text. For more information, please visit our ExpVar reference document.

end()

Description	Deconstructs the class object.
Note	void — This method's use is not required. We provided this method for backwards compatibility with older LivePHP scripts.
Access	Public
Example	end ()

exec()

Description	Executes a cPanel tag. Calling exec directly is discouraged.
Return	array — Returned response in an array data structure.
Access	Public
Example	exec ($code [,$skip_return])

Parameters:

• $code (string) — A cPanel tag that contains an API, ExpVar, or a Dynamic UI construct.
• $skip_return (boolean) — (optional) If set to true, this method will return nothing.

fetch()

Description	This method functions as a wrapper for the cPanel API print function. It returns the entire response as a PHP array. If you only want the data result, use cpanelprint.
Return	array — An array response containing the evaluated value of $var.
Access	Public
Example	fetch ($var)

Parameters:

• $var (string) — An expression that may contain an ExpVar or text. For more information, please visit our ExpVar reference document.

get_debug_log()

Description	Gets the filename of the debug log currently in use.
Return	string — The filename of the LivePHP debug log.
Access	Public
Example	get_debug_log ()

get_debug_level()

Description	Gets the current debug level.
Return	integer — The current debug level.
Access	Public
Example	get_debug_level ()

set_debug()

Description	Sets debugging mode to a specific level.
Return	void
Access	Public
Example	set_debug ($debug_level)

Parameters:

• $debug_level (integer) — Desired debug level.
  • 0 — disable logging. 0 is the default value.
  • 1 — Write socket transactions to the log file.

get_result()

Description	A convenience method for fetching the data result node of the last call.
Return	mixed — The contents within the ['cpanelresult']['data']['result'] node of the last returned response. If the previous call was an API 1 function, a string is returned. If the last call was an API 2 function, an array of associative arrays is returned.
Access	Public
Example	get_result ()

Licensing Information

Version	2.1
Copyright	cPanel, Inc.
License	Modified BSD