theUpstairsRoom

In part one of this series, we looked at getting some simple information out of Horde using the api. In this installment, we'll look at getting the same information, but this time we will be using Horde's RPC server so we can get the information from a remote Horde server.

For these examples, we'll be making use of another one of Horde's libraries, Horde_RPC. This library encapsulates all the nastiness and complexities of dealing with remote server communications.  To use it, you must have the Horde_RPC package installed on your local system. (This package is available from CVS, or from the upcoming Horde 3.2 release).  Although any RPC client library would do.

The first example in the first article was to retrieve a list of applications that are installed and registered with Horde.  Following an example given in the Horde_RPC package, the first example would look like this:

// Load the RPC library
require_once 'Horde/RPC.php';

// XML-RPC endpoint
// This is the URL to your remote Horde server's RPC interface
$rpc_endpoint = 'http://example.com/horde/rpc.php';

// XML-RPC method to call
$rpc_method = 'horde.listApps';

// Process the request
$result = Horde_RPC::request(
    'jsonrpc',
    $rpc_endpoint,
    $rpc_method);

// Dump the results
var_dump($result);

Pretty simple, and not all that different than using the api directly.  The second example in the previous article demonstrated calling contacts/sources to get a list of available address books. The main difference between the first and second examples is the need to pass authentication parameters to Horde.  This, too, is simple:

require_once 'Horde/RPC.php';
$rpc_endpoint = 'http://example.com/horde/rpc.php';

// Specify the method to call
$rpc_method = 'contacts.sources';

// Username and password get set here
$rpc_options = array(
    'user' => 'myusername',
    'pass' => '****',
);

// Process the request, sending user/pass in the 'options' parameter.
$result = Horde_RPC::request(
    'jsonrpc',
    $rpc_endpoint,
    $rpc_method,
    array(),
    $rpc_options);

// Dump the results
var_dump($result);

It's worth noting that when using the jsonrpc server, the results are returned as a stdClass object, not as an array, and as you can see in the next example, you can iterate over the results if needed.

Finally, the last example shows how to pass parameters to the api methods using RPC. Just like in the last article, we get a list of address books that are available, and then search those address books for a certain user.

<?php
require_once 'Horde/RPC.php';
$rpc_endpoint = 'http://example.com/horde/rpc.php';
$rpc_method = 'contacts.sources';
$rpc_options = array(
    'user' => 'myusername',
    'pass' => '****',
);

// Process the first request
$results = Horde_RPC::request(
    'jsonrpc',
    $rpc_endpoint,
    $rpc_method,
    array(),
    $rpc_options);
$results = $results->result;

// jsonrpc returns data as a stdClass, so iterate over the results
// to get the source keys
foreach ($results as $key => $name) {
    $sources[] = $key;
}
$rpc_method = 'contacts.search';

// These are the parameters to the serach method
$rpc_parameters = array(array('michael'),
                        $sources,
                        array('name'));

$results = Horde_RPC::request(
    'jsonrpc',
    $rpc_endpoint,
    $rpc_method,
    $rpc_parameters,
    $rpc_options);

// Dump the results
var_dump($results->result);

You now have the tools and knowledge to retrieve any information that Horde exposes through it's api from both local and remote Horde servers.  The next installment will focus more deeply on various methods of building an 'external' website powered by Horde content.