XMLAPI php class

[cPanelMatt]

I have been working on an XMLAPI PHP class for awhile now, this is intended completely as reference code and is not supported by cPanel. Feel free to modify this and reuse this code as needed.

I want to start out by stating that I am not a PHP programmer, my background is mostly in working with perl, so if you see any stupid developer errors, please let me know and I will gladly adjust them. If you find any bugs, please report them in this thread or by PM'ing me (we will work out better communication methods later on). When reporting bugs, please state the version number.

This class is written for PHP5 and relies on curl & simplexml to work correctly. This include file should only be used as a class.

A basic explanation of how to use this should be obvious from the example scripts attached, however I will go over what this is capable of:

All xml-api functions are implemented in this, provided with an easy interface:

f.ex:

$xmlapi->listaccts() can be used to list accounts

Some functions are called with normal arguments:

f.ex:

$xmlapi->addip($ip,$netmask)

On top of this, some functions require associative arrays (hashes) to be passed to them:

$acct = array( username => "someuser", password => "pass123", domain => "thisdomain.com");
$xmlapi->createacct($acct);

When instantiating this class it needs to call both the constructor and an authenticator function. This class support both password authentication and hash authentication, called via password_auth(user,pass) and hash_auth(user,authhash) respectively.

f.ex with hash auth.

$xmlapi = new xmlapi($ip);
$xmlapi->hash_auth("root",$root_hash);

f.ex. with password auth.

$xmlapi = new xmlapi($ip);
$xmlapi->password_auth("root",$root_pass);

Another feature is that this object can generate the API1 and API2 code automatically:

f.ex.

print $xmlapi->api1_query($account, "Email", "addpop", array($email_user, $email_password, $email_domain) );

Along with this, some debugging functions are provided with a simple boolean interface.

The first of these is set_debug which will show all URLs generated, API1/API2 XML and responses in XML and SimpleXML formats:

f.ex. call

$xmlapi->set_debug(1);
$xmlapi->listips();

will result in an output similar to:

QUERY:
https://127.0.0.1:2087/xml-api/listips?

RAW XML:

<listips>
  <result>
    <active>1</active>
    <if>eth1</if>
    <ip>127.0.0.1</ip>
    <mainaddr>1</mainaddr>
    <removable>0</removable>
    <used>1</used>
  </result>
  <result>
    <active>1</active>
    <if>eth1:1</if>
    <ip>127.0.0.2</ip>
    <mainaddr>0</mainaddr>
    <removable>0</removable>
    <used>1</used>
  </result>
  <result>
    <active>1</active>
    <if>eth1:3</if>
    <ip>127.0.0.3</ip>
    <mainaddr>0</mainaddr>
    <removable>1</removable>
    <used>0</used>
  </result>
  <result>
    <active>1</active>
    <if>eth1:4</if>
    <ip>127.0.0.4</ip>
    <mainaddr>0</mainaddr>
    <removable>1</removable>
    <used>0</used>
  </result>
</listips>

<!-- Web Host Manager  (c) cPanel, Inc. 2008 http://cpanel.net/  Unauthorized copying is prohibited. -->


object(SimpleXMLElement)#2 (1) {
  ["result"]=>
  array(4) {
    [0]=>
    object(SimpleXMLElement)#3 (6) {
      ["active"]=>
      string(1) "1"
      ["if"]=>
      string(4) "eth1"
      ["ip"]=>
      string(14) "127.0.0.1"
      ["mainaddr"]=>
      string(1) "1"
      ["removable"]=>
      string(1) "0"
      ["used"]=>
      string(1) "1"
    }
    [1]=>
    object(SimpleXMLElement)#4 (6) {
      ["active"]=>
      string(1) "1"
      ["if"]=>
      string(6) "eth1:1"
      ["ip"]=>
      string(14) "127.0.0.2"
      ["mainaddr"]=>
      string(1) "0"
      ["removable"]=>
      string(1) "0"
      ["used"]=>
      string(1) "1"
    }
    [2]=>
    object(SimpleXMLElement)#5 (6) {
      ["active"]=>
      string(1) "1"
      ["if"]=>
      string(6) "eth1:3"
      ["ip"]=>
      string(14) "127.0.0.3"
      ["mainaddr"]=>
      string(1) "0"
      ["removable"]=>
      string(1) "1"
      ["used"]=>
      string(1) "0"
    }
    [3]=>
    object(SimpleXMLElement)#6 (6) {
      ["active"]=>
      string(1) "1"
      ["if"]=>
      string(6) "eth1:4"
      ["ip"]=>
      string(14) "127.0.0.4"
      ["mainaddr"]=>
      string(1) "0"
      ["removable"]=>
      string(1) "1"
      ["used"]=>
      string(1) "0"
    }
  }
}

There is also a return_xml object that will just return the XML as a string rather than a SimpleXML object.


Edit: This has been re-released under a modified BSD license, please see the link below to download this version (there have been no changes in this library, a new version is coming after 11.25 is released)
http://sdk.cpanel.net/lib/cp_xmlapi_php.tar.gz

[yanayun]

How to know result "Success" or "No"
it's very important for condition in my scripts.

[cPanelMatt]

The result is actually returned inside of the xml-api call itself, usually it is returns like:

<actionname>
<result>
<status>BOOLEAN</status>
</result>
</actionname>

so to access this inside of a result from the class, you might do something like:

$result = $xmlapi->createacct(....);


if ($result->result->status) {
print "Creation of account worked successfully!";
}
else {
print "Creation Failed:" $result->result->statusmsg;
}

You can either enable debugging mode or run "var_dump $result" on the returned result from the function to see what is actually happening and what values you have available to you.

[yanayun]

some function can't report result :
passwd
accoutsummary
listaccts

[cPanelMatt]

Yanayun, please try running var_dump on the result returned from the library, this will show you the location of a status. The result returned by this are not uniform, they correspond directly to what is returned by the xml-api. I apologize for not being clear with that earlier. The result hash key will not always exist, for example, for list accounts you would test via just "$result->status".

[arpowers]

How come the forum won't let me download this code?
I am logged in...

[daveformerlyof]

How come the forum won't let me download this code?
I am logged in...

Are you getting an error? If so, what is it?

[davidn]

Could you kindly take us through one tiny but complete working php example, right from <?php ... to..... ?>

Yes I'm sure your code means everything to a cPanel expert, but for me it just generates errors however I try and run it.

"$xmlapi->listaccts() can be used to list accounts" Well, no, not a hope, with this code alone, I can't get a list of accounts, whatever I try and do.

I'm trying to use listpopswithdisk to find out if an email account exists, and getting nowhere.

Many thanks

David.

[cPanelDavidG]

Could you kindly take us through one tiny but complete working php example, right from <?php ... to..... ?>

Yes I'm sure your code means everything to a cPanel expert, but for me it just generates errors however I try and run it.

"$xmlapi->listaccts() can be used to list accounts" Well, no, not a hope, with this code alone, I can't get a list of accounts, whatever I try and do.

I'm trying to use listpopswithdisk to find out if an email account exists, and getting nowhere.

Many thanks

David.

There is a code sample for API2 within the compressed file posted, from <?php to ?>. This code sample for API2 is named api2_example.php

As for listaccts, you could use one of the XML API examples like listzones_example.php. However, for XML API functions (rather than API1 and API2 functions from cPanel), you will need to authenticate as a reseller.

Let me know once you have mastered these basics and I can then help you move towards your goal of detecting if an email account exists by means of using this PHP class.

[Bdzzld]

Hi,

As with other classes accessing WHM, I'm missing some kind of error message when an incorrect password or access key has been supplied. How would one extend the class wit that ?

Thanks,
Bdzzld.

[cPanelDavidG]

Hi,

As with other classes accessing WHM, I'm missing some kind of error message when an incorrect password or access key has been supplied. How would one extend the class wit that ?

Thanks,
Bdzzld.

In such a scenario, WHM will return the login screen rather than a XML response. You could build an error catching routine to detect HTML elements like <form ..> and <input ..> and use that to determine that an incorrect password or access key has been supplied.

[Bdzzld]

Hi,

I've already done so as you described, but was thinking there might be some alternate way I overlooked. Thanks for sharing though...

[Bdzzld]

Bug: function "hostname" should be "gethostname" in the class

[takabanana]

Any ideas why I would get an Access Denied to the cPanel account I am trying to access to add a forwarder?

RAW XML:

1textAccess Denied to rforest_rforest.

object(SimpleXMLElement)#2 (3) {
  ["apiversion"]=>
  string(1) "1"
  ["type"]=>
  string(4) "text"
  ["data"]=>
  object(SimpleXMLElement)#3 (1) {
    ["result"]=>
    string(33) "Access Denied to rforest_rforest."
  }
}
SIMPLEXML OBJ:



SimpleXMLElement Object
(
    [apiversion] => 1
    [type] => text
    [data] => SimpleXMLElement Object
        (
            [result] => Access Denied to rforest_rforest.
        )

)
FAIL:

Here's the code:

include("inc/xmlapi.php.inc");

$xmlapi = new xmlapi("127.0.0.1");
$xmlapi->password_auth("<WHM User>","<WHM PW>");
$xmlapi->set_debug(1);

    $result = $xmlapi->api2_query("rforest_rforest", "Email", "addforwarder",
                array(
                    fwdemail=>"<MY EMAIL ACCT>",
                    email=>"test_cpanel",
                    domain=>"<DOMAIN OF cPanel USER>"
                ) );

[cPanelDavidG]

Any ideas why I would get an Access Denied to the cPanel account I am trying to access to add a forwarder?

...
    $result = $xmlapi->api2_query("rforest_rforest", "Email", "addforwarder",
                array(
                    fwdemail=>"<MY EMAIL ACCT>",
                    email=>"test_cpanel",
                    domain=>"<DOMAIN OF cPanel USER>"
                ) );

rforest_rforest doesn't appear to be a valid cPanel username (longer than 8 characters).