CXXXVI. XML-RPC Functions

Wstęp

These functions can be used to write XML-RPC servers and clients. You can find more information about XML-RPC at http://www.xmlrpc.com/, and more documentation on this extension and its functions at http://xmlrpc-epi.sourceforge.net/.

Ostrzeżenie

Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazwy, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.

Wymagania

Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.

Instalacja

XML-RPC support in PHP is not enabled by default. You will need to use the --with-xmlrpc[=DIR] configuration option when compiling PHP to enable XML-RPC support. This extension is bundled into PHP as of 4.1.0.

Konfiguracja czasu wykonywania

Na działanie tych funcji wpływają ustawienia zawarte w pliku php.ini.

Tabela 1. XML-RPC configuration options

Name	Default	Changeable	Changelog
xmlrpc_errors	"0"	PHP_INI_SYSTEM	Available since PHP 4.1.0.
xmlrpc_error_number	"0"	PHP_INI_ALL	Available since PHP 4.1.0.

Szczegóły i definicje dotyczące stałych PHP_INI_* znajdują się w rozdziale Dodatek H.

Typy zasobów

To rozszerzenie nie posiada żadnych rodzajów zasobów.

Stałe predefinopwane

To rozszerzenie nie posiada żadnych stałych.

Spis treści
xmlrpc_decode_request -- Decodes XML into native PHP types
xmlrpc_decode -- Decodes XML into native PHP types
xmlrpc_encode_request -- Generates XML for a method request
xmlrpc_encode -- Generates XML for a PHP value
xmlrpc_get_type -- Gets xmlrpc type for a PHP value
xmlrpc_is_fault -- Determines if an array value represents an XMLRPC fault
xmlrpc_parse_method_descriptions -- Decodes XML into a list of method descriptions
xmlrpc_server_add_introspection_data -- Adds introspection documentation
xmlrpc_server_call_method -- Parses XML requests and call methods
xmlrpc_server_create -- Creates an xmlrpc server
xmlrpc_server_destroy -- Destroys server resources
xmlrpc_server_register_introspection_callback -- Register a PHP function to generate documentation
xmlrpc_server_register_method -- Register a PHP function to resource method matching method_name
xmlrpc_set_type -- Sets xmlrpc type, base64 or datetime, for a PHP string value

User Contributed Notes


I couldn't make the 'xmlrpc_errors' php.ini setting do anything 

noticeable (PHP 4.3.11), so I used the following code to report errors 

from my XMLRPC server. Hope it's helpful for someone.



<?php

function return_xmlrpc_error($errno,$errstr,$errfile=NULL,$errline=NULL

       ,$errcontext=NULL){

    global $xmlrpc_server;

    if(!$xmlrpc_server)die("Error: $errstr in '$errfile', line '$errline'");



    header("Content-type: text/xml; charset=UTF-8");

    print(xmlrpc_encode(array(

        'faultCode'=>$errno

        ,'faultString'=>"Remote XMLRPC Error from 

          ".$_SERVER['HTTP_HOST'].": $errstr in at $errfile:$errline"

    )));

    die();

}    

set_error_handler('return_xmlrpc_error');

?>



In my server function, I just trigger_error("message",E_USER_ERROR)]

 if something can't be completed.



Then on the client side,

<?php

        $data =& xmlrpc_decode($response['body']);



        if(xmlrpc_is_fault($data)){

            trigger_error($data['faultString'],E_USER_ERROR);

        }

?>


To connect to a python xmlrpc server I use:



function do_call($host, $port, $request) {

  

    $url = "http://$host:$port/";

    $header[] = "Content-type: text/xml";

    $header[] = "Content-length: ".strlen($request);

    

    $ch = curl_init();   

    curl_setopt($ch, CURLOPT_URL, $url);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    curl_setopt($ch, CURLOPT_TIMEOUT, 1);

    curl_setopt($ch, CURLOPT_HTTPHEADER, $header);

    curl_setopt($ch, CURLOPT_POSTFIELDS, $request);

    

    $data = curl_exec($ch);       

    if (curl_errno($ch)) {

        print curl_error($ch);

    } else {

        curl_close($ch);

        return $data;

    }

}



$request = xmlrpc_encode_request('add', array(3, 4));

$response = do_call($host, $port, $request);


The PHP XML-RPC project at SourceForge makes life a hell of a lot easier. However, the project uses some function names which are identical to thoses provided by the XML-RPC extention.



If you are on a server with XML-RPC extension compiled in but wish to use the PHP based version then you will have to rename some of the functions.



I notice that sourceforce says there is activity on the project in 2005 but the last release was January 12, 2003.



I recommend that you use this not so friendly PHP extention if available. However this sourceforce project is still a good idea if you don't control which extenions are be available on the server.



http://phpxmlrpc.sourceforge.net/


On "datetime" values:



If you implement an XML-RPC server with these functions and a client calls a method on your server, sending a datetime as parameter (in ISO 8601 format, as specified at http://www.xmlrpc.com/spec), the PHP XML-RPC will pass your registered server method an object as parameter. That object, for example, looks like:

obj->type="datetime"

obj->scalar="20040420T13:32:40"

obj->timestamp=1082460760



If you do xmlrpc_get_type(obj), it will return "datetime", so presumably that function just returns the value of 'type'. 'scalar' seems to be the on-the-wire representation of the datetime (ISO 8601, exactly as received). 'timestamp' appears to be the ISO value in 'scalar' converted into a normal PHP timestamp (i.e. Unix time_t).



Note on 'scalar': Using a MySQL DB, we did something like  "select blah where start_time >= $obj->scalar ;". That actually worked and returned expected results, so MySQL appears to handle that ISO 8601 format correctly.


It took me a while to get a client together without external libraries.  This very basic client/server pair works on my home set-up - hopefully it will save the next xml-rpc virgin some grief.





/* clienttest.php */


<?php


function do_call($host, $port, $request) {


    


    $fp = fsockopen($host, $port, $errno, $errstr);


    $query = "POST /home/servertest.php HTTP/1.0\nUser_Agent: My Egg Client\nHost: ".$host."\nContent-Type: text/xml\nContent-Length: ".strlen($request)."\n\n".$request."\n";





    if (!fputs($fp, $query, strlen($query))) {


        $errstr = "Write error";


        return 0;


    }





    $contents = '';


    while (!feof($fp)) {


        $contents .= fgets($fp);


    }





    fclose($fp);


    return $contents;


}





$host = 'localhost';


$port = 80;


$request = xmlrpc_encode_request('cycle', 'egg');


$response = do_call($host, $port, $request);


/* do something with $response, e.g. print it */


?>





/* servertest.php */


<?php


function lifecycle($method, $params) {


/* $method = 'cycle', $params = (array of) request parameter(s); $data is also passed from xmlrpc_server_call_method, if we had any data to pass */


    switch($params[0]) {


        case 'egg':


            $reply = 'All eggs will be birds one day.';


        break;


        default:


            $reply = 'That must have been an otheregg';


    }


    return $reply;


}





$server = xmlrpc_server_create();





/* register the 'external' name and then the 'internal' name */


xmlrpc_server_register_method($server, "cycle", "lifecycle");





$request = $HTTP_RAW_POST_DATA; // no you don't need 'always on', and no $_POST doesn't work.





/* the parameters here are 'server, xml-string and user data'.  There's supposed to be an optional 'output options' array too, but I can't get it working :( hence header() call */


$response = xmlrpc_server_call_method($server, $request, null);


header('Content-Type: text/xml');


print $response;





xmlrpc_server_destroy($server);


?>


Just a quick addition to my previous xmlrpc_client class: since you cannot use remote methods containing capital letters or methods from subhandlers (like 'system.listMethods()'), I added a 'call(...)' method to the class. 



<?php

    // this method should be copy/pasted in the 

    // xmlrpc_client class



    function call($function)

    {

        $return = NULL;

        $argv = func_get_args();

        array_shift($argv); // remove function argument

        $this->__call($function, $argv, &$return);

        return $return;

    }



    // now, you can also do

    $result = $client->call('system.listMethods');

    $sum = client->call('add', '1', '2');

?>


I use the following code (requires the overload extension) to make developing clients easier:



<?php

include("utils/utils.php"); // from xmlrpc-epi utils



/*

Usage:

    $client = new xmlrpc_client("http://localhost:7080");

    print $client->echo('x')."\n";

    print $client->add(1, 3)."\n";



*/

class xmlrpc_client

{

    var $url;

    var $urlparts;



    function xmlrpc_client($url)

    {

        $this->url = $url;

        $this->urlparts = parse_url($this->url);

        foreach(array('scheme', 'host', 'user', 'pass', 'path',

                      'query', 'fragment')

                as $part) {

            if (!isset($this->urlparts[$part])) { 

                $this->urlparts[$part] = NULL;

                }

            }

    }



    function __call($function, $arguments, &$return)

    {

        $requestprms['host'] = $this->urlparts['host'];

        $requestprms['port'] = $this->urlparts['port'];

        $requestprms['uri'] = $this->urlparts['path'];

        $requestprms['method'] = $function;

        $requestprms['args'] = $arguments;

        $requestprms['debug'] = 0;

        $requestprms['timeout'] = 0;

        $requestprms['user'] = NULL;

        $requestprms['pass'] = NULL;

        $requestprms['secure'] = 0;



        $result = xu_rpc_http_concise($requestprms);

        if (is_array($result) && isset($result['faultCode'])) {

            print('Error in xmlrpc call \''.$function.'\''."\n");

            print('  code   : '.$result['faultCode']."\n");

            print('  message: '.$result['faultString']."\n");

            return false;

            }

        $return = $result;

        return true;

    }



}

overload('xmlrpc_client');



?>


here's how to install it on windows (so it actually works):



- php.ini > enable "php_xmlrpc.dll" in extensions.

- php.ini > make sure "extension_dir" is set correctly to find the dll in your php installation dir /extensions.

- copy iconv.dll from your php install dir /dlls to a directory in your path (ex: c:/windows).



if you got some errors while launching apache prior to trying this I suggest you reboot your machine first... sounds weird I know, but remember... you're running Windowz.

Have fun


If anyone is interested in making XMLRPC requests directly from the client, I have been able to get xmlrpc to 

work with vcXMLRPC javascript backend.



After about 1 week of scanning the market, I found this solution to be the best on Javascript back end.  It uses the Microsoft.HTTP activeX control for IE, or HTTPRequest Object for Mozilla.



You include vc(Virtual Cowboys) vcXMLRPC.js file into your pages and make the rpc calls from with javascript to create the requests.



It works both ways.



Two Notes:



I have tested it on IE 6.02 and you need to change lines in ProcessRequest :

function to read:



  dom = this.getObject("XMLDOM",http.responseText);



and change the getObject function to use the latest ActiveX Control:



 MSXML2.XMLHTTP.3.0  (or 4.0)

 MSXML2.DOMDocument.3.0  (or 4.0)



The controls are found on MSDN in the Web Services -> XML area.



As another note, you DO NOT NEED the rpcproxy.cgi script to use this.  That is a proxy script to get around JS Security.  You can use PHP to build the proxy.  But, I was able to get the CGI working with GCC compiler on Solaris (change the -KPCI, depend and -x03 optimizer settings in the Makefile )


There's a handy library by Keith Devens (version 2.2.1) at 


http://www.keithdevens.com/software/xmlrpc/





Here is a sample client. It remotely calls sample.sumAndDifference


with two parameters (3 and 5).


It returns:





sum => 8


difference => -2





<?php


include ("kd_xmlrpc.php");


// define("XMLRPC_DEBUG", 0);    // Set to 1 for handy debugging





$method = "sample.sumAndDifference";


$params = XMLRPC_prepare(array(3,5));





$site = "xmlrpc-c.sourceforge.net";


$location = "/api/sample.php";





list($success, $result) = XMLRPC_request( $site, $location, $method, $params );





// XMLRPC_debug_print();    // uncomment for debugging





foreach ( $result as $key => $value ) {


          echo(" $key => $value \n");


}





?>