the path and name of the RPC server script
you want the request to go to

string$server

the URL of the remote server to connect to.
If this parameter doesn't specify a
protocol and $port is 443, ssl:// is assumed.

integer$port

a port for connecting to the remote server.
Defaults to 80 for http:// connections and
443 for https:// and ssl:// connections.

string$proxy

the URL of the proxy server to use, if any.
If this parameter doesn't specify a
protocol and $port is 443, ssl:// is assumed.

integer$proxy_port

a port for connecting to the remote server.
Defaults to 8080 for http:// connections and
443 for https:// and ssl:// connections.

string$proxy_user

a user name for accessing the proxy server

string$proxy_pass

a password for accessing the proxy server

In order to use SSL connections, your PHP installation must
have the openssl extension enabled.

Here's an example client set up to query Userland's XML-RPC server
at betty.userland.com:

<?php$client = new XML_RPC_Client('/RPC2', 'betty.userland.com');?>

Methods

This class supports the following methods.

send()

This method takes the form:

$response = $client->send (
$xmlrpc_message
, $timeout
)

Where $xmlrpc_message is an instance of
XML_RPC_Message and
$response is an instance of
XML_RPC_Response (see API).

The $timeout is optional, and will be set to
0 (wait forever) if omitted. This timeout value
is passed to fsockopen().

If the value of $response is
0 rather than an
XML_RPC_Response object, then this signifies
an I/O error has occured. You can find out what the I/O error was
from the values $client->errno and
$client->errstring.

In addition to low-level errors, the XML-RPC server you were
querying may return an error in the
XML_RPC_Response object. See API for details
of how to handle these errors.

setCredentials()

$client->setCredentials (
$username
, $password
)

This method sets the username and password for authorizing the
client to a server. With the default (HTTP) transport, this
information is used for HTTP Basic authorization.

setDebug()

$client->setDebug (
$debugOn
)

$debugOn is either 0 or
1 depending on whether you require the client to
print debugging information to the browser. The default is not to
output this information.

The debugging information includes the raw data returned from the
XML-RPC server it was querying, and the PHP value the client
attempts to create to represent the value returned by the server.
This option can be very useful when debugging servers as it allows
you to see exactly what the server returns.

XML_RPC_Message

This class provides a representation for a request to an XML-RPC
server. A client sends an XML_RPC_Message to a
server, and receives back an XML_RPC_Response.

Creation

The constructor takes the following form:

$msg = new XML_RPC_Message (
$methodName
, $parameterArray
)

Where $methodName is a string indicating the
name of the method you wish to invoke, and
$parameterArray is a simple
Array of XML_RPC_Value
objects. Here's an example message to the US state
name server:

This example requests the name of state number 23. For more
information on XML_RPC_Value objects, see
API.

Methods

serialize()

$outString = $msg->serialize (
)

Returns the an XML string representing the XML-RPC message.

addParam()

$msg->addParam (
$xmlrpcVal
)

Adds the XML_RPC_Value$xmlrpcVal to the parameter list for this
method call.

Returns an XML_RPC_Value object.
If the parameter doesn't exist, an XML_RPC_Response
object is returned.

getParam()

$xmlrpcVal = $msg->getParam (
$n
)

Gets the $nth parameter in the message. Use
this method in server implementations. Returns the
undef value if no such parameter exists.

getNumParams()

$n = $msg->getNumParams (
)

Returns the number of parameters attached to this message.

method()

$methName=$msg->method (
)

$msg->method (
$methName
)

Gets or sets the method contained in the XML-RPC message.

parseResponse()

$response = $msg->parseResponse (
$xmlString
)

Given an incoming XML-RPC server response contained in the string
$xmlString, this method constructs an
XML_RPC_Response response object and returns
it, setting error codes as appropriate.

This method processes any HTTP/MIME headers it finds.

parseResponseFile()

$response = $msg->parseResponseFile (
$fileHandle
)

Given an incoming XML-RPC server response on the file handle
$fileHandle, this method reads the data and
passes it to parseResponse().

This method is useful to construct responses from pre-prepared
files. It processes any HTTP headers it finds.

XML_RPC_Response

This class is used to contain responses to XML-RPC requests. A server
method handler will construct an
XML_RPC_Response and pass it as a return
value. This same value will be returned by the result of an
invocation of the send() method of the
XML_RPC_Client class.

Creation

$resp = new XML_RPC_Response (
$xmlrpcval
)

$resp = new XML_RPC_Response (
0
, $errcode
, $errstring
)

The first instance is used when execution has happened without
difficulty: $xmlrpcval is an
XML_RPC_Value value with the result of the
method execution contained in it.

The second type of constructor is used in case of
failure. $errcode and
$errstring are used to provide indication of
what has gone wrong. See API for more
information on passing error codes.

Methods

faultCode()

$fn = $resp->faultCode (
)

Returns the integer fault code return from the XML-RPC response
$resp. A zero value indicates success, any
other value indicates a failure response.

faultString()

$fs = $resp->faultString (
)

Returns the human readable explanation of the fault indicated by
$resp->faultCode.

value()

$xmlrpcVal = $resp->value (
)

Returns an XML_RPC_Value object containing
the return value sent by the server. If the response's
faultCode is non-zero then the value returned
by this method should not be used (it may not even be an object).

serialize()

$outString = $resp->serialize (
)

Returns an XML string representation of the response.

XML_RPC_Value

This is where a lot of the hard work gets done. This class enables
the creation and encapsulation of values for XML-RPC.

The XML_RPC_Value class can store arbitrarily
complicated values using the following types:
i4,
int,
boolean,
string,
double,
dateTime.iso8601,
base64,
array or
struct.
You
should refer to the spec for
more information on what each of these types mean.

Notes on types

int

The type i4 is accepted as a synonym for
int. The value parsing code will always
convert i4 to int:
int is regarded by this implementation as
the canonical name for this type.

base64

Base 64 encoding is performed transparently to the caller when
using this type. Therefore you ought to consider it as a binary
data type, for use when you want to pass none 7-bit clean data.
Decoding is also transparent.

boolean

The values true and 1 map to
true. All other values (including the empty
string) are converted to false.

string

The characters
<,
>,
" and
&
are converted to their entity equivalents
&lt;,
&gt;,
&quot; and
&amp;
for transport through XML-RPC. The
current XML-RPC spec recommends only encoding
< and &
but this implementation goes further, for reasons
explained by the XML 1.0
recommendation.

Currently, passing a string "-1" to XML_RPC_Value's
constructor creates an empty result since it serves as a special/magic
value.

TODO: &apos; entity is not yet supported

Creation

The constructor is the normal way to create an
XML_RPC_Value. The constructor can take these
forms:

The fourth constructor form can be used to compose complex XML-RPC
values. The first argument is either a simple array in the case of
an XML-RPC array or an associative array in
the case of a struct. The elements of the
array must be XML_RPC_Value objects
themselves. Examples:

$myArray = new XML_RPC_Value(array( new XML_RPC_Value("Tom"), new XML_RPC_Value("Dick"), new XML_RPC_Value("Harry")), "array");

Methods

addScalar()

If $val is an empty
XML_RPC_Value this method makes it a scalar
value, and sets that value. If $val is
already a scalar value, then no more scalars can be added and
0 is returned. If all went OK,
1 is returned.

There is a special case if $val is an
array: the scalar value passedis appended to
the array.

addArray()

$ok = $val->addArray (
$arrayVal
)

Turns an empty XML_RPC_Value into an
array with contents as specified by
$arrayVal. See the fourth constructor form
for more information.

addStruct()

$ok = $val->addStruct (
$assocArrayVal
)

Turns an empty XML_RPC_Value into a
struct with contents as specified by
$assocArrayVal. See the fourth constructor
form for more information.

kindOf()

$kind = $val->kindOf (
)

Returns a string containing struct, array or scalar
describing the base type of the value. If it returns undef it
means that the value hasn't been initialised.

This performs everything you need to do with a server. The single
argument is an associative array from method names to function
names. The request is parsed and despatched to the relevant function,
which is reponsible for returning a
XML_RPC_Response object, which gets serialized
back to the caller.

Here is a more detailed look at what the handler function
foo() may do:

// $params is the received XML_RPC_Message object.if ($err) {// this is an error conditionreturn new XML_RPC_Response(0, $XML_RPC_erruser+1, // user error 1"There's a problem, Captain"); } else {// this is a successful value being returnedreturn new XML_RPC_Response(new XML_RPC_Value("All's fine!", "string")); }}?>

The dispatch map

The first argument to the XML_RPC_Server()
constructor is an array, called the dispatch
map. In this array is the information the server needs
to service the XML-RPC methods you define.

The dispatch map takes the form of an associative array of
associative arrays: the outer array has one entry for each method,
the key being the method name. The corresponding value is another
associative array, which can have the following members:

function - this entry is mandatory. It must
be a name of a function in the global scope which services the
XML-RPC method.

It is possible to use regular functions, class names with method
names and objects with method names. The Examples page of this
manual demonstrates the appropriate syntax for all of these approaches.

signature - this entry is an array containg
the possible signatures (see API)
for the method. If this entry is present then the server will
check that the correct number and type of parameters have been
sent for this method before dispatching it.

docstring - this entry is a string containing
documentation for the method. The documentation may contain HTML
markup.

Method signatures

A signature is a description of a method's return type and its
parameter types. A method may have more than one signature.

Within a server's dispatch map, each method has an array of possible
signatures. Each signature is an array of types. The first entry is
the return type.

Let's run through an example. Imagine you wanted to write a
regular PHP function like this:

Delaying the server response

You may want to construct the server, but for some reason not
fulfill the request immediately (security verification, for
instance). If you pass the constructor a second argument of
0 this will have the desired effect. You can then
use the service() method of the server class to
service the request. For example:

<?php$s = new XML_RPC_Server($myDispMap, 0);

// ... some code that does other stuff here

$s->service();?>

Fault reporting

Fault codes for your servers should start at the value indicated by
the global $xmlrpcerruser + 1.

Standard errors returned by the server include:

1Unknown method

Returned if the server was asked to dispatch a method it didn't
know about

2Invalid return payload

This error is actually generated by the client, not server, code,
but signifies that a server returned something it couldn't
understand.

3Incorrect parameters

This error is generated when the server has signature(s) defined
for a method, and the parameters passed by the client do not
match any of signatures.

4Can't introspect: method
unknown

This error is generated by the builtin
system.*() methods when any kind of
introspection is attempted on a method undefined by the server.

5Didn't receive 200 OK from remote
server

This error is generated by the client when a remote server
doesn't return HTTP/1.1 200 OK in response to a request. A more
detailed error report is added onto the end of the phrase above.

100-XML parse errors

Returns 100 plus the XML parser error code for the fault that
occurred. The faultString returned explains
where the parse error was in the incoming XML stream.

XML_RPC_Dump

This class generates string representations of
the data in XML_RPC_Value objects.