INCUTIO HOME | SCRIPTS | CONTACT

Manual Index

Basic Client Construction

IXR allows you to make requests to XML-RPC servers using the IXR_Client class. Before you make a connection you will need to know the host, path and port of the XML-RPC server you wish to communicate with, and know which method on the server you wish to access. A list of public XML-RPC services can be found here.

First you will need to create an IXR_Client object. You must supply the details of the server you wish to connect to when you create the object, either as a URL or as a hostname, path and port:

// Specifying a server by URL (port 80 is assumed):
$client = new IXR_Client('http://scripts.incutio.com/xmlrpc/simpleserver.php');

// Specifying a client by host, path and port
$client = new IXR_Client('scripts.incutio.com', '/xmlrpc/simpleserver.php', 80);

The next step is to make your XML-RPC call using the query() method. The method accepts a XML-RPC methodName with a variable number of arguments, which will be passed to the server along with the request. The query() method returns true or false depending on whether or not your request has been successful. Should your request fail the getErrorCode and getErrorMessage methods will usually provide a more detailed explanation of what went wrong.

if (!$client->query('test.add', 3, 4)) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

Presuming the method was successful, you can access the data returned by the XML-RPC server using the getResponse() method. This will return a single value or an array of values, depending on the data structure returned by the server.

echo $client->getResponse();

So far, so good. Now let's try for something a bit more complicated. I've set up an example web service what interfaces with FOLDOC, the Free On-Line Dictionary of Computing. Let's see what it knows about PHP:

// Create the client object
$client = new IXR_Client('http://scripts.incutio.com/xmlrpc/foldoc/server.php');

// Run a query for PHP
if (!$client->query('foldoc.getEntry', 'php')) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

// Display the result
echo '<pre>';
print_r($client->getResponse());
echo '</pre>';

You should see something that looks like this:
Array
(
    [term] => php
    [definition] => {PHP: Hypertext Processor}
    [related] => Array
        (
            [0] => PHP: Hypertext Processor
        )

    [categories] => Array
        (
        )

    [date] => 
)

Not much information there - all there is is a reference to the full PHP entry, entitled 'PHP: Hypertext Processor'. Now run a search for that and you should see:

Array
(
    [term] => PHP: Hypertext Processor
    [definition] => <World-Wide Web, programming> (PHP) A {server-side},
{cross-platform}, {HTML}-embedded {scripting language} used to
create dynamic {web pages}.  PHP is {Open Source} software.

{PHP Home (http://www.php.net/)}.

[Features?]
    [related] => Array
        (
            [0] => server-side
            [1] => cross-platform
            [2] => HTML
            [3] => scripting language
            [4] => web pages
            [5] => Open Source
        )

    [categories] => Array
        (
            [0] => World-Wide Web
            [1] => programming
        )

    [date] => 2002-01-03
)

That's a nice big data structure ready for formatting, processing or doing whatever else you might want to do with it.

Debugging

Should you need to debug your client procedure calls at any tiem you can do so with the debug flag:

$client = new IXR_Client('http://scripts.incutio.com/xmlrpc/foldoc/server.php');

$client->debug = true;

// Run a query for PHP
if (!$client->query('foldoc.getEntry', 'php)) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

With the debug flag turned on, IXR_Client will display the full contents of all outgoing and incoming XML-RPC messages.

scripts.incutio.com light logo