Basic server construction

Basic servers in IXR are constructed using the IXR_Server class. The methodology is simple - create PHP functions (or class methods if you want to go the OOP route), then call the IXR_Server constructor with an array that "maps" XML-RPC method names to the names of your functions. The IXR_Server class will then call the relevant functions based on information from the client.

Your callback functions can return normal PHP variables (strings, integers, arrays, indexed arrays or even objects) and IXR will convert the return values in to an XML-RPC response and send it back to the client.

Here is a simple IXR server:

<?php

include('IXR_Library.inc.php');

function sayHello($args) {
    return 'Hello!';
}
function addTwoNumbers($args) {
    $number1 = $args[0];
    $number2 = $args[1];
    return $number1 + $number2;
}
$server = new IXR_Server(array(
    'demo.sayHello' => 'sayHello',
    'demo.addTwoNumbers' => 'addTwoNumbers'
));

?>

The above code will create an XML-RPC server with two available methods - demo.sayHello which returns the string 'Hello!', and demo.addTwoNumbers which accepts two integer values, adds them together and returns them.

Note that both of the callback functions accept a single argument - $args. $args is an array of paramaters received from the XML-RPC client. If there is only one argument, $args will be that argument rather than an array with only one element.

Sending Errors

XML-RPC has a flexible error system, which you can use in your server implementations. An XML-RPC error consists of an error number (an integer) and a descriptive string. The number you use is pretty much up to you as the application developer, but it is important you keep a consistent numbering scheme. You can send errors back to the client using the following code:

function myCallbackFunction($args) {
    if ($args[0] != 'thesecretpassword') {
        return new IXR_Error(-1, 'You did not provide the correct password');
    }
    // Rest of function here
}

The above function will return an error if the first argument sent by the client is anything other than 'thesecretpassword' - it can be used to form a very basic (and not particularly secure) authentication system.

Dates and base64 encoded data

XML-RPC has support for two types that do not have a direct corresponding type in PHP - dates and base64 encoded data. To return data in these formats, you can use the following:

function myFunction($args) {
    $data = 'a string to be transmitted as base64 encoded data';
    $time = time();
    return array(
        'data' => new IXR_Base64($data),
        'time' => new IXR_Date($time)
    );
}

The above function returns an indexed array (an XML-RPC struct) consisting of a base64 encoded data chunk and an iso encoded date. As you can see, the details of the encoding are kept hidden from the web service programmer.

The Object Oriented Approach

Writing web services with callback functions is all well and good, but IXR can also be used to create web services as PHP classes. This can be achieved by creating a server class that extends IXR_Server and defining methods that you wish to use as XML-RPC procedures in thew new class. You can then call the IXR_Server constructor with the now familiar callback array, with one small difference - each of your callback functions should be prefixed with "this:", to inform IXR that you wish to call a class method rather than a normal function.

Here is the above simple server implemented using OOP:

<?php

include('IXR_Library.inc.php');

class SimpleServer extends IXR_Server {
    function SimpleServer() {
        $this->IXR_Server(array(
            'demo.sayHello' => 'this:sayHello',
            'demo.addTwoNumbers' => 'this:addTwoNumbers'
        ));
    }
    function sayHello($args) {
        return 'Hello!';
    }
    function addTwoNumbers($args) {
        $number1 = $args[0];
        $number2 = $args[1];
        return $number1 + $number2;
    }
}

$server = new SimpleServer();

?>