The Community Forums

Interact with an entire community of cPanel & WHM users!
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

XMLAPI php class

Discussion in 'cPanel Developers' started by MattDees, Mar 26, 2009.

Thread Status:
Not open for further replies.
  1. MattDees

    MattDees cPanel Product Owner
    Staff Member

    Joined:
    Apr 29, 2005
    Messages:
    417
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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:
    Code:
    $xmlapi->listaccts() can be used to list accounts
    
    Some functions are called with normal arguments:

    f.ex:
    Code:
    $xmlapi->addip($ip,$netmask)
    
    On top of this, some functions require associative arrays (hashes) to be passed to them:

    Code:
    $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.
    Code:
    $xmlapi = new xmlapi($ip);
    $xmlapi->hash_auth("root",$root_hash);
    
    f.ex. with password auth.
    Code:
    $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.
    Code:
    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
    Code:
    $xmlapi->set_debug(1);
    $xmlapi->listips();
    
    will result in an output similar to:
    Code:
    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
     
    #1 MattDees, Mar 26, 2009
    Last edited: Jul 30, 2009
  2. yanayun

    yanayun Member

    Joined:
    May 14, 2005
    Messages:
    22
    Likes Received:
    0
    Trophy Points:
    1
    How to know result "Success" or "No"
    it's very important for condition in my scripts.
     
  3. MattDees

    MattDees cPanel Product Owner
    Staff Member

    Joined:
    Apr 29, 2005
    Messages:
    417
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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:

    Code:
    $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.
     
  4. yanayun

    yanayun Member

    Joined:
    May 14, 2005
    Messages:
    22
    Likes Received:
    0
    Trophy Points:
    1
    some function can't report result :
    passwd
    accoutsummary
    listaccts
     
  5. MattDees

    MattDees cPanel Product Owner
    Staff Member

    Joined:
    Apr 29, 2005
    Messages:
    417
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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".
     
  6. arpowers

    arpowers Registered

    Joined:
    Apr 25, 2009
    Messages:
    3
    Likes Received:
    0
    Trophy Points:
    1
    How come the forum won't let me download this code?
    I am logged in...
     
  7. DaveUsedToWorkHere

    DaveUsedToWorkHere Well-Known Member

    Joined:
    Dec 28, 2001
    Messages:
    689
    Likes Received:
    1
    Trophy Points:
    18
    Are you getting an error? If so, what is it?
     
  8. davidn

    davidn Member

    Joined:
    May 5, 2009
    Messages:
    7
    Likes Received:
    0
    Trophy Points:
    1
    Could we see a bit more please?

    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.
     
  9. cPanelDavidG

    cPanelDavidG Technical Product Specialist

    Joined:
    Nov 29, 2006
    Messages:
    11,279
    Likes Received:
    8
    Trophy Points:
    38
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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.
     
  10. Bdzzld

    Bdzzld Well-Known Member

    Joined:
    Apr 3, 2004
    Messages:
    356
    Likes Received:
    1
    Trophy Points:
    18
    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.
     
  11. cPanelDavidG

    cPanelDavidG Technical Product Specialist

    Joined:
    Nov 29, 2006
    Messages:
    11,279
    Likes Received:
    8
    Trophy Points:
    38
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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.
     
  12. Bdzzld

    Bdzzld Well-Known Member

    Joined:
    Apr 3, 2004
    Messages:
    356
    Likes Received:
    1
    Trophy Points:
    18
    Hi,

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

    Bdzzld Well-Known Member

    Joined:
    Apr 3, 2004
    Messages:
    356
    Likes Received:
    1
    Trophy Points:
    18
    Bug: function "hostname" should be "gethostname" in the class ;)
     
    #13 Bdzzld, May 19, 2009
    Last edited: May 21, 2009
  14. takabanana

    takabanana Member

    Joined:
    Mar 4, 2005
    Messages:
    8
    Likes Received:
    0
    Trophy Points:
    1
    Location:
    Atlanta, GA
    Access Denied to [cPanel account]

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

    Code:
    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:
    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>"
                    ) );
    
     
    #14 takabanana, May 20, 2009
    Last edited: May 20, 2009
  15. cPanelDavidG

    cPanelDavidG Technical Product Specialist

    Joined:
    Nov 29, 2006
    Messages:
    11,279
    Likes Received:
    8
    Trophy Points:
    38
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    rforest_rforest doesn't appear to be a valid cPanel username (longer than 8 characters).
     
  16. takabanana

    takabanana Member

    Joined:
    Mar 4, 2005
    Messages:
    8
    Likes Received:
    0
    Trophy Points:
    1
    Location:
    Atlanta, GA
    Hrm - ok - so I fixed the username, and I am getting these errors - any ideas?

    Code:
    RAW XML:
    
    [an error occurred while processing this directive]  
        2
        addforwarder
        Email
    
    Warning:  simplexml_load_string() [function.simplexml-load-string]: Entity: line 1: parser error : Extra content at the end of the document in /home/rforest/public_html/inc/xmlapi.php.inc on line 92
    
    Warning:  simplexml_load_string() [function.simplexml-load-string]: <error>[an error occurred while processing this directive]</error>  <cpanelresul in /home/rforest/public_html/inc/xmlapi.php.inc on line 92
    
    Warning:  simplexml_load_string() [function.simplexml-load-string]:                                                                     ^ in /home/rforest/public_html/inc/xmlapi.php.inc on line 92
    
    bool(false)
    SIMPLEXML OBJ:
    
    Warning:  simplexml_load_string() [function.simplexml-load-string]: Entity: line 1: parser error : Extra content at the end of the document in /home/rforest/public_html/inc/xmlapi.php.inc on line 94
    
    Warning:  simplexml_load_string() [function.simplexml-load-string]: <error>[an error occurred while processing this directive]</error>  <cpanelresul in /home/rforest/public_html/inc/xmlapi.php.inc on line 94
    
    Warning:  simplexml_load_string() [function.simplexml-load-string]:                                                                     ^ in /home/rforest/public_html/inc/xmlapi.php.inc on line 94
    
    FAIL:
    
     
  17. DaveUsedToWorkHere

    DaveUsedToWorkHere Well-Known Member

    Joined:
    Dec 28, 2001
    Messages:
    689
    Likes Received:
    1
    Trophy Points:
    18
    Sounds like a possible input issue. What's in /usr/local/cpanel/logs/error_log?
     
  18. takabanana

    takabanana Member

    Joined:
    Mar 4, 2005
    Messages:
    8
    Likes Received:
    0
    Trophy Points:
    1
    Location:
    Atlanta, GA
    I don't think I have access to that - it's on a shared web server...
    Anything I can do to help debug this?
     
  19. cPanelDavidG

    cPanelDavidG Technical Product Specialist

    Joined:
    Nov 29, 2006
    Messages:
    11,279
    Likes Received:
    8
    Trophy Points:
    38
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    The error_log is the most efficient way of debugging this. However, knowing this function and common mistakes in its use, for your fwdemail parameter, did you have just the part before the @ (which is correct) or the entire email address (incorrect)?
     
  20. takabanana

    takabanana Member

    Joined:
    Mar 4, 2005
    Messages:
    8
    Likes Received:
    0
    Trophy Points:
    1
    Location:
    Atlanta, GA
    fwdemail has the whole email address - because I wanted the domain (for which the cPanel is being manipulated) to forward to an external email address (i.e. gmail).

    I am currently having to do this (add/remove forwarding email addresses) for 30 or so accounts every so often. They are all forwarded to off-domain accounts.

    If that is the incorrect format for fwdemail - how do I add/remove forwarders that get forwarded to a different domain?
     
Loading...
Thread Status:
Not open for further replies.

Share This Page