Subversion-Projekte lars-tiefland.php_share

#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