cPanel® Blog

BETA Release of PublicAPI PHP, the cPanel PHP Library, and cPanel PEAR

We are pleased to announce that our PublicAPI PHP client is ready! This API query client is the sibling to Cpanel::PublicAPI that was announced last month.

You can download the PublicAPI PHP client at our github repository as well as the new cPanel PEAR channel.

One of the key distinctions of the PublicAPI PHP client class is that it’s distributed as part of the cPanel PHP Library. The cPanel PHP library is a collection of PHP classes for interfacing with cPanel systems.

When we began working on the PublicAPI PHP client, we had three goals in mind:

  • Create a PHP-based API client for developers that adheres to the PublicAPI interface
  • Provide compatibility with existing scripts that use the XML-API client
  • Provide support for LivePHP

Because LivePHP and XML-API work on two different query mechanisms (file sockets and HTTP, respectively) it was immediately apparent that the code responsible for transmitting and receiving the server response would need to be abstracted.

We also had to consider that the Public API, XML-API, and LivePHP interfaces defined their own set of query methods. This meant that any instance of the client object would need to be smart enough to know about each interfaces’ methods, understand their context, and validate each methods’ arguments.

The most direct solution would have been to lump all of the query calls together in one class. However, this solution would have put us back to square one if a new interface or cPanel service were to be introduced. Instead, we made a series of inherited models that would function ‘under the hood,’ while the ‘top’ would be a customizable object that could be tailored as necessary.

Long story short, about 2000 lines into it, we realized that this was no longer a client but a full-fledged library — a group of components that are (mostly) decoupled. The result being that any one or more components can be used to build an entirely different client or application. Thus, the cPanel PHP Library was born.

The README.markdown file in the repo (also in the PEAR package) offers a good summarization of what is included in the distribution as well as an introduction to the cPanel PHP Library and PublicAPI. Please take the time to read that file and checkout the *Examples/* directory in the distribution.

As an example, here is a little script I wrote while answering a quick forum post related to Analog Stats queries via API1 and API2:
array(
'whm' => array(
'host'=>'127.0.0.1',
'user'=>'root',
'hash'=>$hash,
),
),
);
$cp = Cpanel_PublicAPI::getInstance();
// just a quick poll of what cPanel version I'm running
$response = $cp->whm_api('version');
echo "Version: {$response->version}n";
// Test the output of API2 Stats::listanalog
// call should produce a list of domains that have stats
$mf = array(
'module' => 'Stats',
'function' => 'listanalog',
'user' => 'cppirum',
);
$api2_list = $cp->cpanel_api2_request('whostmgr', $mf);
echo "List from API2 Stats::listanalogn";
/**
* For debugging I could just dump the "array" format
* var_dump ($api2_list->getResponse('array'));
*
* But I'd rather have a nice loop on the object
*/
foreach ( $api2_list->cpanelresult->data as $stat_holder) {
echo "tDomain '{$stat_holder->domain}' has stats.n";
}
echo "n";
// Same thing here, only we'll look at API1 Stats::analoglist, which generates HTML
$mf = array(
'module' => 'Stats',
'function' => 'analoglist',
'user'=>'cppirum',
);
// This API call requires a domain
$args = array('pear.cppirum.net');
$api1_list = $cp->cpanel_api1_request('whostmgr', $mf, $args);
echo "list from API1 Stats::analoglistn";
$html = $api1_list->data->result;
$xml = '' . trim($html) . '';
$sxml = simplexml_load_string($xml);
foreach ($sxml->a as $url) {
$attributes = $url->attributes();
echo "tStats for {$url} can be found at 'https://{$args[0]}:2083{$attributes['href']}'.n";
}
echo "n";
?>

As you can see, I used the the whm_api(), cpanel_api1_request(), and cpanel_api2_request() query methods of the PublicAPI interface. The arguments for each of those methods are the same as in the Perl PublicAPI client.

Download it and give it whirl. This is BETA software so you may encounter some quirky behavior. If you experience any problems, please let use know by using the [github issue tracker](http://github.com/CpanelInc/publicapi-php/issues). There are several features within the library that we hope to refine, as it matures to a STABLE release over the next several months.

In the coming days, we hope to provide more detailed documentation on sdk.cpanel.net concerning PublicAPI (Perl and PHP) and the cPanel PHP library. In the meantime, you can checkout the POD (Perl) and DocBlock (PHP) documentation that’s included in the code.

Regards & Happy Coding!

cPanel

The web hosting industry’s most reliable, intuitive control panel since 1997. With our first-class support and rich feature set, it’s easy to see why our customers and partners make cPanel & WHM their hosting platform of choice. For more information, visit cPanel.com.