Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

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 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
  • noteNote: 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

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

Topic revision: r14 - 13 Jan 2012 - 15:37:35 - Main.JustinSchaefer
AllDocumentation/AutomationIntegration.LivePHP moved from Sandbox.LivePHP on 14 Apr 2010 - 20:36 by Main.JustinSchaefer