#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass docbook-section
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title
\added_space_top vfill \added_space_bottom vfill 
XML_RPC2 Tutorial
\layout Abstract

This tutorial introduces basic usage of XML_RPC2 as a client/server library
 in XML_RPC operations.
 XML_RPC2 is a pear package providing XML_RPC client and server services.
 XML-RPC is a simple remote procedure call protocol built using HTTP as
 transport and XML as encoding.
\layout Abstract

As a client library, XML_RPC2 is capable of creating a proxy class which
 exposes the methods exported by the server.
 As a server library, XML_RPC2 is capable of exposing methods from a class
 or object instance, seamlessly exporting local methods as remotely callable
 procedures.
 
\layout Subsection

Client usage
\layout Subsubsection

Basic Usage
\layout Standard

The most simple way to use the XML_RPC client is by letting XML_RPC2 select
 the backend for you, and just give the client factory method the data referring
 to the server:
\layout Itemize

The server URI.
\layout Itemize

The HTTP proxy URI (null if no proxy).
\layout Itemize

The method prefix
\layout Code

require_once('XML/RPC2/Client.php');
\layout Code

$client = XML_RPC2_Client::create('http://rpc.example.com:80/', null, '');
\layout Standard

The factory will produce a client proxy.
 This class exports whichever methods the server exports.
 These methods are called just like regular local methods:
\layout Code

print($client->hello('World'));
\layout Standard

for a server that exports the method hello.
 If the server has methods prefixed by a classname (example.hello), there
 are two solutions.
 Either call the method using brackets enclosing the otherwise php-invalid
 method name:
\layout Code

print($client->{example.hello}('World'));
\layout Standard

Or specify a method prefix when creating the client instance:
\layout Code

$client = XML_RPC2_Client::create('http://rpc.example.com:80/', null, 'example.');
\layout Code

print($client->hello('World'));
\layout Subsubsection

Error handling
\layout Standard

XML_RPC2 uses exceptions to signal errors.
 The phpdoc reference contains a class hierarchy useful to get a grasp of
 possible errors.
 The most important characteristics of the XML_RPC2 exception tree are:
\layout Itemize

All XML_RPC2 exceptions are children of XML_RPC2_Exception.
 If you want to filter out exceptions from this package, catch XML_RPC2_Exceptio
n
\layout Itemize

Network failure is signaled by an XML_RPC2_TransportException
\layout Itemize

Regular XML-RPC fault responses are signaled by an XML_RPC2_FaultException
\layout Itemize

All other types of XML_RPC2_Exception signal package misuse or bug-induced
 misbehaviour
\layout Standard

Standard usage:
\layout Code

require_once('XMLrequire_once('XML/RPC2/Client.php');
\layout Code

try {
\layout Code

    $client = XML_RPC2_Client::create('http://rpc.example.com:80/', null,
 '');
\layout Code

    print($client->hello('World'));
\layout Code

} catch (XML_RPC2_TransportException transportException) {
\layout Code

    // Handle network-induced exception
\layout Code

} catch (XML_RPC2_FaultException fault) {
\layout Code

    // Handle fault returned by remote server
\layout Code

} catch (XML_RPC2_Exception xmlRpcException) {
\layout Code

    // Handle abnormal XML_RPC2 package exception
\layout Code

} catch (Exception e) {
\layout Code

    // Handle someone else's fault exception
\layout Code

}
\layout Standard

It is good practice to at least expect XML_RPC2_TransportException as network
 failure can't ever be ruled out.
 
\layout Subsection

Server usage
\layout Subsubsection

Basic Usage
\layout Standard

To export an XML-RPC server using XML_RPC2, the first step is writing the
 methods to export.
 XML_RPC2 can export class methods (static methods) for a class, or all
 methods for an object instance.
 For this example, we'll export a class' static methods:
\layout Code

class EchoServer {     
\layout Code

    /**
\layout Code

     * echoecho echoes the message received      
\layout Code

     *      
\layout Code

     * @param string  Message
\layout Code

     * @return string The echo
\layout Code

     */
\layout Code

\layout Code

    public static function echoecho($string) 
\layout Code

    {
\layout Code

        return $string;
\layout Code

    }
\layout Code

    
\layout Code

    /**
\layout Code

     * Dummy method which won't be exported
\layout Code

     * 
\layout Code

     * @xmlrpc.hidden
\layout Code

     */
\layout Code

    public static function dummy()
\layout Code

    {
\layout Code

        return false;
\layout Code

    }
\layout Code

\layout Code

    /**
\layout Code

     * hello says hello
\layout Code

     * 
\layout Code

     * @param string Name
\layout Code

     * @return string Hello 'name'
\layout Code

     */
\layout Code

    public function hello($name) 
\layout Code

    {
\layout Code

        return "Hello $name";
\layout Code

    }
\layout Code

\layout Code

} 
\layout Standard

Note that the method is documented using phpDoc docblocks.
 The docblock is used to deduce the signature and method documentation,
 required by the XML-RPC spec.
 Non-documented methods are not exported.
 Methods tagged with the tag @xmlrpc.hidden are not exported either (the
 dummy method above won't be exported).
\layout Standard

After creating the class, we need to get an XML_RPC2 server to export its
 methods remotely:
\layout Code

require_once 'XML/RPC2/Server.php';
\layout Code

$server = XML_RPC2_Server::create('EchoServer');
\layout Code

$server->handleCall();
\layout Standard

The XML_RPC2_Server automatically exports all of the EchoServer class public
 static methods (echoecho in this case).
 You may also export all of an instance's public methods (static or otherwise):
\layout Code

require_once 'XML/RPC2/Server.php';
\layout Code

$server = XML_RPC2_Server::create(new EchoServer());
\layout Code

$server->handleCall();
\the_end