Recipe 14.12. Calling an XML-RPC Method

Recipe 14.12. Calling an XML-RPC Method 14.12.1. Problem You want to be an XML-RPC client and make requests of a server. XML-RPC lets PHP make function calls to web servers, even if they don't use PHP. The retrieved data is then automatically converted to PHP variables for use in your application. 14.12.2. Solution Use PHP's built-in XML-RPC extension with some helper functions. PHP bundles the xmlrpc-epi extension. Unfortunately, xmlrpc-epi does not have any native C functions for taking an XML-RPC-formatted string and making a request. However, the folks behind xmlrpc-epi have a series of helper functions written in PHP available for download at http://xmlrpc-epi.sourceforge.net/. The only file used here is the one named utils.php, which is located in sample/utils. To install it, just copy that file to a location where PHP can find it in its include_path. Here's client code that calls a function on an XML-RPC server that returns state names: <?php // this is the default file name from the package // kept here to avoid confusion over the file name require 'utils.php'; // server settings $host = 'betty.userland.com'; $port = 80; $uri = '/RPC2'; // request settings // pass in a number from 1-50; get the nth state in alphabetical order // 1 is Alabama, 50 is Wyoming $method = 'examples.getStateName'; $args = array(32); // data to be passed // make associative array out of these variables $request = compact('host', 'port', 'uri', 'method', 'args'); // this function makes the XML-RPC request $result = xu_rpc_http_concise($request); print "I love $result!\n"; ?> 14.12.3. Discussion XML-RPC, a format created by Userland Software, allows you to make a request to a web server using HTTP. The request itself is a specially formatted XML document. As a client, you build up an XML request to send that fits with the XML-RPC specification. You then send it to the server, and the server replies with an XML document. You then parse the XML to find the results. In the Solution, the XML-RPC server returns a state name, so the code prints: I love New York! Unlike earlier implementations of XML-RPC, which were coded in PHP, the current bundled extension is written in C, so there is a significant speed increase in processing time. To enable this extension while configuring PHP, add --with-xmlrpc. The server settings tell PHP which web site to contact to make the request. The $host is the hostname of the machine; $port is the port the web server is running on, which is usually port 80; and $uri is the pathname to the XML-RPC server you wish to contact. This request is equivalent to http://betty.userland.com:80/RPC2. If no port is given, the function defaults to port 80, and the default URI is the web server root, /. The request settings are the function to call and the data to pass to the function. The method examples.getStateName takes an integer from 1 to 50 and returns a string with the name of the U.S. state, in alphabetical order. In XML-RPC, method names can have periods, while in PHP, they cannot. If they could, the PHP equivalent to passing 32 as the argument to the XML-RPC call to examples.getStateName is calling a function named examples.getStateName( ): examples.getStateName(32); In XML-RPC, it looks like this: <?xml version='1.0' encoding="iso-8859-1" ?> <methodCall> <methodName>examples.getStateName</methodName> <params><param><value> <int>32</int> </value> </param> </params> </methodCall> The server settings and request information go into a single associative array that is passed to xu_rpc_http_concise( ). As a shortcut, call compact( ), which is identical to: $request = array('host' => $host, 'port' => $port, 'uri' => $uri, 'method' => $method, 'args' => $args); The xu_rpc_http_concise( ) function makes the XML-RPC call and returns the results. Since the return value is a string, you can print $results directly. If the XML-RPC call returns multiple values, xu_rpc_http_concise( ) returns an array. There are 10 different parameters that can be passed in the array to xu_rpc_http_concise( ), but the only one that's required is host. The parameters are shown in Table 14-1. Table 14-1. Parameters for xu_rpc_http_concise( ) Name Description host Server hostname uri Server URI (default /) port Server port (default 80) method Name of method to call args Arguments to pass to method debug Debug level (0 to 2: 0 is none, 2 is lots) timeout Number of seconds before timing out the request; a value of 0 means never timeout user Username for Basic HTTP Authentication, if necessary pass Password for Basic HTTP Authentication, if necessary secure Use SSL for encrypted transmissions; requires PHP to be built with SSL support (pass any true value) 14.12.4. See Also Recipe 15.9 for more on XML-RPC servers; PHP helper functions for use with the xmlrpc-epi extension at http://xmlrpc-epi.sourceforge.net/; Programming Web Services with XML-RPC by Simon St.Laurent, Joe Johnston, and Edd Dumbill (O'Reilly); more on XML-RPC at http://www.xml-rpc.com .