xmlrpc.php

XML-RPC for PHP

version 3.0.0 beta

Sep 5, 2009

Edd

Dumbill

Gaetano

Giunta

Miles

Lott

Justin R.

Miller

Andres

Salomon

1999,2000,2001

Edd Dumbill, Useful Information Company

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

Redistributions of source code must retain the above
copyright notice, this list of conditions and the following
disclaimer.

Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.

Neither the name of the “XML-RPC for PHP” nor the names of
its contributors may be used to endorse or promote products
derived from this software without specific prior written
permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Introduction

XML-RPC is a format devised by Userland Software for achieving
remote procedure call via XML using HTTP as the transport. XML-RPC has its
own web site, http://www.xmlrpc.com

This collection of PHP classes provides a framework for writing
XML-RPC clients and servers in PHP.

Main goals of the project are ease of use, flexibility and
completeness.

The original author is Edd Dumbill of Useful Information Company. As of the
1.0 stable release, the project was opened to wider involvement and moved
to SourceForge.

A list of XML-RPC implementations for other languages such as Perl
and Python can be found on the http://www.xmlrpc.com site.

Acknowledgements

Daniel E. Baumann

James Bercegay

Leon Blackwell

Stephane Bortzmeyer

Daniel Convissor

Geoffrey T. Dairiki

Stefan Esser

James Flemer

Ernst de Haan

Tom Knight

Axel Kollmorgen

Peter Kocks

Daniel Krippner

S. Kuip

A. Lambert

Frederic Lecointre

Dan Libby

Arnaud Limbourg

Ernest MacDougal Campbell III

Lukasz Mach

Kjartan Mannes

Ben Margolin

Nicolay Mausz

Justin Miller

Jan Pfeifer

Giancarlo Pinerolo

Peter Russel

Jean-Jacques Sarton

Viliam Simko

Idan Sofer

Douglas Squirrel

Heiko Stübner

Anatoly Techtonik

Tommaso Trani

Eric van der Vlist

Christian Wenz

Jim Winstead

Przemyslaw Wroblewski

Bruno Zanetti Melotti

What’s new

Note: not all items the following list have
(yet) been fully documented, and some might not be present in any other
chapter in the manual. To find a more detailed description of new
functions and methods please take a look at the source code of the
library, which is quite thoroughly commented in javadoc-like form.

3.0.0 beta

This is the first release of the library to only support PHP 5.
Some legacy code has been removed, and support for features such as
exceptions and dateTime objects introduced.

The “beta” tag is meant to indicate the fact that the refactoring
has been more widespread than in precedent releases and that more
changes are likely to be introduced with time – the library is still
considered to be production quality.

improved: removed all usage of php functions deprecated in
php 5.3, usage of assign-by-ref when creating new objects
etc…

improved: add support for the <ex:nil/> tag used by
the apache library, both in input and output

improved: add support for dateTime
objects in both in php_xmlrpc_encode and as
parameter for constructor of
xmlrpcval

improved: add support for timestamps as parameter for
constructor of xmlrpcval

improved: add option ‘dates_as_objects’ to
php_xmlrpc_decode to return
dateTime objects for xmlrpc
datetimes

improved: add new method
SetCurlOptions to
xmrlpc_client to allow extra flexibility in
tweaking http config, such as explicitly binding to an ip
address

improved: add new method
SetUserAgent to
xmrlpc_client to to allow having different
user-agent http headers

improved: add a new member variable in server class to allow
fine-tuning of the encoding of returned values when the server is
in ‘phpvals’ mode

improved: allow servers in ‘xmlrpcvals’ mode to also
register plain php functions by defining them in the dispatch map
with an added option

improved: catch exceptions thrown during execution of php
functions exposed as methods by the server

fixed: bad encoding if same object is encoded twice using
php_xmlrpc_encode

2.2.2

Note: this might the last release of the
library that will support PHP 4. Future releases (if any) should target
php 5.0 as minimum supported version.

fixed: encoding of utf-8 characters outside of the BMP
plane

fixed: character set declarations surrounded by double
quotes were not recognized in http headers

fixed: be more tolerant in detection of charset in http
headers

fixed: fix detection of zlib.output_compression

fixed: use feof() to test if socket connections are to be
closed instead of the number of bytes read (rare bug when
communicating with some servers)

fixed: format floating point values using the correct
decimal separator even when php locale is set to one that uses
comma

fixed: improve robustness of the debugger when parsing weird
results from non-compliant servers

php warning when receiving ‘false’ in a bool value

improved: allow the add_to_map server method to add docs for
single params too

improved: added the possibility to wrap for exposure as
xmlrpc methods plain php class methods, object methods and even
whole classes

2.2.1

fixed: work aroung bug in php 5.2.2 which broke support of
HTTP_RAW_POST_DATA

fixed: is_dir parameter of setCaCertificate() method is
reversed

fixed: a php warning in xmlrpc_client creator method

fixed: parsing of ‘1e+1’ as valid float

fixed: allow errorlevel 3 to work when prev. error handler was
a static method

fixed: usage of client::setcookie() for multiple cookies in
non-ssl mode

improved: support for CP1252 charset is not part or the
library but almost possible

improved: more info when curl is enabled and debug mode is
on

2.2

fixed: debugger errors on php installs with magic_quotes_gpc
on

fixed: support for https connections via proxy

fixed: wrap_xmlrpc_method() generated code failed to properly
encode php objects

improved: slightly faster encoding of data which is internally
UTF-8

improved: debugger always generates a ‘null’ id for jsonrpc if
user omits it

new: debugger can take advantage of a graphical value builder
(it has to be downloaded separately, as part of jsxmlrpc package.
See Appendix D for more details)

new: support for the <NIL/> xmlrpc extension. see below
for more details

new: server support for the system.getCapabilities xmlrpc
extension

new: wrap_xmlrpc_method()
accepts two new options: debug and return_on_fault

2.1

The wrap_php_function and
wrap_xmlrpc_method functions have been moved
out of the base library file xmlrpc.inc into
a file of their own: xmlrpc_wrappers.inc. You
will have to include() / require() it in your scripts if you have
been using those functions. For increased security, the automatic
rebuilding of php object instances out of received xmlrpc structs
in wrap_xmlrpc_method() has been disabled
(but it can be optionally re-enabled). Both
wrap_php_function() and
wrap_xmlrpc_method() functions accept many
more options to fine tune their behaviour, including one to return
the php code to be saved and later used as standalone php
script

The constructor of xmlrpcval() values has seen some internal
changes, and it will not throw a php warning anymore when invoked
using an unknown xmlrpc type: the error will only be written to
php error log. Also new xmlrpcval('true', 'boolean')
is not supported anymore

The new function
php_xmlrpc_decode_xml() will take the xml
representation of either an xmlrpc request, response or single
value and return the corresponding php-xmlrpc object
instance

A new function wrap_xmlrpc_server()has
been added, to wrap all (or some) of the methods exposed by a
remote xmlrpc server into a php class

A new file has been added:
verify_compat.php, to help users diagnose the
level of compliance of their php installation with the
library

Restored compatibility with php 4.0.5 (for those poor souls
still stuck on it)

Method xmlrpc_server->service()
now returns a value: either the response payload or xmlrpcresp
object instance

Method
xmlrpc_server->add_to_map() now
accepts xmlrpc methods with no param definitions

Documentation for single parameters of exposed methods can
be added to the dispatch map (and turned into html docs in
conjunction with a future release of the ‘extras’ package)

Full response payload is saved into xmlrpcresp object for
further debugging

The debugger can now generate code that wraps a remote
method into a php function (works for jsonrpc, too); it also has
better support for being activated via a single GET call (e.g. for
integration into other tools)

Stricter parsing of incoming xmlrpc messages: two more
invalid cases are now detected (double data
element inside array and
struct/array after scalar
inside value element)

More logging of errors in a lot of situations

Javadoc documentation of lib files (almost) complete

Many performance tweaks and code cleanups, plus the usual
crop of bugs fixed (see NEWS file for complete list of
bugs)

Lib internals have been modified to provide better support
for grafting extra functionality on top of it. Stay tuned for
future releases of the EXTRAS package (or go read Appendix
B)…

2.0 final

Added to the client class the possibility to use Digest and
NTLM authentication methods (when using the CURL library) for
connecting to servers and NTLM for connecting to proxies

Added to the client class the possibility to specify
alternate certificate files/directories for authenticating the
peer with when using HTTPS communication

Reviewed all examples and added a new demo file, containing
a proxy to forward xmlrpc requests to other servers (useful e.g.
for ajax coding)

The debugger has been upgraded to reflect the new client
capabilities

All known bugs have been squashed, and the lib is more
tolerant than ever of commonly-found mistakes

2.0 Release candidate 3

Added to server class the property
functions_parameters_type, that allows the
server to register plain php functions as xmlrpc methods (i.e.
functions that do not take an xmlrpcmsg object as unique
param)

let server and client objects serialize calls using a
specified character set encoding for the produced xml instead of
US-ASCII (ISO-8859-1 and UTF-8 supported)

let php_xmlrpc_decode accept xmlrpcmsg objects as valid
input

‘class::method’ syntax is now accepted in the server
dispatch map

xmlrpc_clent::SetDebug() accepts
integer values instead of a boolean value, with debugging level 2
adding to the information printed to screen the complete client
request

2.0 Release candidate 2

Added a new property of the client object:
xmlrpc_client->return_type, indicating whether
calls to the send() method will return xmlrpcresp objects whose
value() is an xmlrpcval object, a php value (automatically
decoded) or the raw xml received from the server.

Added in the extras dir. two new library file:
jsonrpc.inc and
jsonrpcs.inc containing new classes that
implement support for the json-rpc protocol (alpha quality
code)

Added a new client method: setKey($key,
$keypass)
to be used in HTTPS connections

Added a new file containing some benchmarks in the testsuite
directory

2.0 Release candidate 1

Support for HTTP proxies (new method:
xmlrpc_client::setProxy())

Support HTTP compression of both requests and responses.
Clients can specify what kind of compression they accept for
responses between deflate/gzip/any, and whether to compress the
requests. Servers by default compress responses to clients that
explicitly declare support for compression (new methods:
xmlrpc_client::setAcceptedCompression(),
xmlrpc_client::setRequestCompression()). Note that the
ZLIB php extension needs to be enabled in PHP to support
compression.

Implement HTTP 1.1 connections, but only if CURL is enabled
(added an extra parameter to
xmlrpc_client::xmlrpc_client to set the desired HTTP
protocol at creation time and a new supported value for the last
parameter of xmlrpc_client::send, which now can be
safely omitted if it has been specified at creation time)

With PHP versions greater than 4.3.8 keep-alives are enabled
by default for HTTP 1.1 connections. This should yield faster
execution times when making multiple calls in sequence to the same
xml-rpc server from a single client.

Introduce support for cookies. Cookies to be sent to the
server with a request can be set using
xmlrpc_client::setCookie(), while cookies received from
the server are found in xmlrpcresp::cookies(). It is
left to the user to check for validity of received cookies and
decide whether they apply to successive calls or not.

Better support for detecting different character set encodings
of xml-rpc requests and responses: both client and server objects
will correctly detect the charset encoding of received xml, and use
an appropriate xml parser.

Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.

Added one new xmlrpcmsg constructor syntax, allowing usage of
a single string with the complete URL of the target server

Convert xml-rpc boolean values into native php values instead
of 0 and 1

Force the php_xmlrpc_encode function to properly
encode numerically indexed php arrays into xml-rpc arrays
(numerically indexed php arrays always start with a key of 0 and
increment keys by values of 1)

Prevent the php_xmlrpc_encode function from
further re-encoding any objects of class xmlrpcval that
are passed to it. This allows to call the function with arguments
consisting of mixed php values / xmlrpcval objects.

Allow a server to NOT respond to system.* method calls
(setting the $server->allow_system_funcs
property).

Implement a new xmlrpcval method to determine if a value of
type struct has a member of a given name without having to loop
trough all members: xmlrpcval::structMemExists()

Expand methods xmlrpcval::addArray,
addScalar and addStruct allowing extra php
values to be added to xmlrpcval objects already formed.

Let the xmlrpc_client::send method accept an XML
string for sending instead of an xmlrpcmsg object, to facilitate
debugging and integration with the php native xmlrpc
extension

Extend the php_xmlrpc_encode and
php_xmlrpc_decode functions to allow serialization and
rebuilding of PHP objects. To successfully rebuild a serialized
object, the object class must be defined in the deserializing end of
the transfer. Note that object members of type resource will be
deserialized as NULL values.

Note that his has been implemented adding a “php_class”
attribute to xml representation of xmlrpcval of STRUCT type, which,
strictly speaking, breaks the xml-rpc spec. Other xmlrpc
implementations are supposed to ignore such an attribute (unless
they implement a brain-dead custom xml parser…), so it should be
safe enabling it in heterogeneous environments. The activation of
this feature is done by usage of an option passed as second
parameter to both php_xmlrpc_encode and
php_xmlrpc_decode.

Extend the php_xmlrpc_encode function to allow
automatic serialization of iso8601-conforming php strings as
datetime.iso8601 xmlrpcvals, by usage of an optional
parameter

Added an automatic stub code generator for converting xmlrpc
methods to php functions and vice-versa.

This is done via two new functions:
wrap_php_function and wrap_xmlrpc_method,
and has many caveats, with php being a typeless language and
all…

With PHP versions lesser than 5.0.3 wrapping of php functions
into xmlrpc methods is not supported yet.

Allow object methods to be used in server dispatch map

Added a complete debugger solution, in the
debugger folder

Added configurable server-side debug messages, controlled by
the new method xmlrpc_server::SetDebug(). At level 0,
no debug messages are sent to the client; level 1 is the same as the
old behaviour; at level 2 a lot more info is echoed back to the
client, regarding the received call; at level 3 all warnings raised
during server processing are trapped (this prevents breaking the xml
to be echoed back to the client) and added to the debug info sent
back to the client

New XML parsing code, yields smaller memory footprint and
faster execution times, not to mention complete elimination of the
dreaded eval() construct, so prone to code
injection exploits

Rewritten most of the error messages, making text more
explicative

System Requirements

The library has been designed with goals of scalability and backward
compatibility. As such, it supports a wide range of PHP installs. Note
that not all features of the lib are available in every
configuration.

The minimum supported PHP version is
5.0.

Automatic generation of xml-rpc methods from php functions is only
supported with PHP version 5.0.3 and later (note that the lib will
generate some warnings with PHP 5 in strict error reporting mode).

If you wish to use SSL or HTTP 1.1 to communicate with remote
servers, you need the “curl” extension compiled into your PHP
installation.

The “xmlrpc” native extension is not required to be compiled into
your PHP installation, but if it is, there will be no interference with
the operation of this library.

Files in the distribution

lib/xmlrpc.inc

the XML-RPC classes. include() this in
your PHP files to use the classes.

lib/xmlrpcs.inc

the XML-RPC server class. include() this
in addition to xmlrpc.inc to get server functionality

lib/xmlrpc_wrappers.inc

helper functions to “automagically” convert plain php
functions to xmlrpc services and vice versa

demo/server/proxy.php

a sample server implementing xmlrpc proxy
functionality.

demo/server/server.php

a sample server hosting various demo functions, as well as a
full suite of functions used for interoperability testing. It is
used by testsuite.php (see below) for unit testing the library, and
is not to be copied literally into your production servers

demo/client/client.php, demo/client/agesort.php,
demo/client/which.php

client code to exercise some of the functions in server.php,
including the interopEchoTests.whichToolkit
method.

demo/client/wrap.php

client code to illustrate ‘wrapping’ of remote methods into
php functions.

demo/client/introspect.php

client code to illustrate usage of introspection capabilities
offered by server.php.

demo/client/mail.php

client code to illustrate usage of an xmlrpc-to-email gateway
using Dave Winer’s XML-RPC server at userland.com.

demo/client/zopetest.php

example client code that queries an xmlrpc server built in
Zope.

demo/vardemo.php

examples of how to construct xmlrpcval types

demo/demo1.txt, demo/demo2.txt, demo/demo3.txt

XML-RPC responses captured in a file for testing purposes (you
can use these to test the
xmlrpcmsg->parseResponse() method).

demo/server/discuss.php,
demo/client/comment.php

Software used in the PHP chapter of to provide a comment server and allow the
attachment of comments to stories from Meerkat’s data store.

test/testsuite.php, test/parse_args.php

A unit test suite for this software package. If you do
development on this software, please consider submitting tests for
this suite.

test/benchmark.php

A (very limited) benchmarking suite for this software package.
If you do development on this software, please consider submitting
benchmarks for this suite.

test/phpunit.php, test/PHPUnit/*.php

An (incomplete) version PEAR’s unit test framework for PHP.
The complete package can be found at http://pear.php.net/package/PHPUnit

test/verify_compat.php

Script designed to help the user to verify the level of
compatibility of the library with the current php install

extras/test.pl, extras/test.py

Perl and Python programs to exercise server.php to test that
some of the methods work.

extras/workspace.testPhpServer.fttb

Frontier scripts to exercise the demo server. Thanks to Dave
Winer for permission to include these. See Dave’s
announcement of these.

extras/rsakey.pem

A test certificate key for the SSL support, which can be used
to generate dummy certificates. It has the passphrase “test.”

Known bugs and limitations

This started out as a bare framework. Many “nice” bits haven’t been
put in yet. Specifically, very little type validation or coercion has been
put in. PHP being a loosely-typed language, this is going to have to be
done explicitly (in other words: you can call a lot of library functions
passing them arguments of the wrong type and receive an error message only
much further down the code, where it will be difficult to
understand).

dateTime.iso8601 is supported opaquely. It can’t be done natively as
the XML-RPC specification explicitly forbids passing of timezone
specifiers in ISO8601 format dates. You can, however, use the and functions
to do the encoding and decoding for you.

Very little HTTP response checking is performed (e.g. HTTP redirects
are not followed and the Content-Length HTTP header, mandated by the
xml-rpc spec, is not validated); cookie support still involves quite a bit
of coding on the part of the user.

If a specific character set encoding other than US-ASCII, ISO-8859-1
or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
or response messages then it will be ignored for the moment, and the
content will be parsed as if it had been encoded using the charset defined
by

Support for receiving from servers version 1 cookies (i.e.
conforming to RFC 2965) is quite incomplete, and might cause unforeseen
errors.

Support

Online Support

XML-RPC for PHP is offered “as-is” without any warranty or
commitment to support. However, informal advice and help is available
via the XML-RPC for PHP website and mailing list and from
XML-RPC.com.

The XML-RPC for PHP development is hosted
on phpxmlrpc.sourceforge.net.
Bugs, feature requests and patches can be posted to the project’s
website.

The PHP XML-RPC interest mailing list is
run by the author. More details can be
found here.

For more general XML-RPC questions, there is a Yahoo! Groups
XML-RPC mailing
list.

The XML-RPC.com discussion
group is a useful place to get help with using XML-RPC. This group
is also gatewayed into the Yahoo! Groups mailing list.

The Jellyfish Book

Together with Simon St.Laurent and Joe
Johnston, Edd Dumbill wrote a book on XML-RPC for O’Reilly and
Associates on XML-RPC. It features a rather fetching jellyfish on the
cover.

Complete details of the book are available from
O’Reilly’s web site.

Edd is responsible for the chapter on PHP, which includes a worked
example of creating a forum server, and hooking it up the O’Reilly’s
Meerkat service in
order to allow commenting on news stories from around the Web.

If you’ve benefited from the effort that has been put into writing
this software, then please consider buying the book!

Class documentation

xmlrpcval

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

Ensure you’ve read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7
before reading on as it will make things clearer.

The xmlrpcval class can store arbitrarily
complicated values using the following types: i4 int boolean
string double dateTime.iso8601 base64 array struct
null. 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 when creating xmlrpcval objects. The
xml 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. Decoding is also transparent. Therefore you ought
to consider it as a “binary” data type, for use when you want to
pass data that is not 7-bit clean.

boolean

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

string

Characters <, >, ‘, “, &, are encoded using their
entity reference as &lt; &gt; &apos; &quot; and
&amp; All other characters outside of the ASCII range are
encoded using their character reference representation (e.g.
&#200 for é). The XML-RPC spec recommends only encoding
< & but this implementation goes further,
for reasons explained by the XML 1.0
recommendation. In particular, using character reference
representation has the advantage of producing XML that is valid
independently of the charset encoding assumed.

null

There is no support for encoding null
values in the XML-RPC spec, but at least a couple of extensions (and
many toolkits) do support it. Before using null
values in your messages, make sure that the responding party accepts
them, and uses the same encoding convention (see …).

Creation

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

xmlrpcvalnew
xmlrpcval

xmlrpcvalnew
xmlrpcval

string$stringVal

xmlrpcvalnew
xmlrpcval

mixed$scalarVal

string$scalartyp

xmlrpcvalnew
xmlrpcval

array$arrayVal

string$arraytyp

The first constructor creates an empty value, which must be
altered using the methods addScalar,
addArray or addStruct before
it can be used.

The second constructor creates a simple string value.

The third constructor is used to create a scalar value. The
second parameter must be a name of an XML-RPC type. Valid types are:
“int”, “boolean”,
“string”, “double”,
“dateTime.iso8601”, “base64” or
“null”.

Examples:

$myInt = new xmlrpcvalue(1267, “int”);
$myString = new xmlrpcvalue(“Hello, World!”, “string”);
$myBool = new xmlrpcvalue(1, “boolean”);
$myString2 = new xmlrpcvalue(1.24, “string”); // note: this will serialize a php float value as xmlrpc string

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 xmlrpcval objects
themselves.

The second parameter must be either “array”
or “struct”.

Examples:

$myArray = new xmlrpcval(
array(
new xmlrpcval(“Tom”),
new xmlrpcval(“Dick”),
new xmlrpcval(“Harry”)
),
“array”);

// recursive struct
$myStruct = new xmlrpcval(
array(
“name” => new xmlrpcval(“Tom”, “string”),
“age” => new xmlrpcval(34, “int”),
“address” => new xmlrpcval(
array(
“street” => new xmlrpcval(“Fifht Ave”, “string”),
“city” => new xmlrpcval(“NY”, “string”)
),
“struct”)
),
“struct”);

See the file vardemo.php in this distribution
for more examples.

Methods

addScalar

intaddScalar

string$stringVal

intaddScalar

mixed$scalarVal

string$scalartyp

If $val is an empty
xmlrpcval 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 $val is an xmlrpcval of type array,
the php value $scalarval is added as its last
element.

If all went OK, 1 is returned, otherwise
0.

addArray

intaddArray

array$arrayVal

The argument is a simple (numerically indexed) array. The
elements of the array must be
xmlrpcval objects
themselves.

Turns an empty xmlrpcval into an
array with contents as specified by
$arrayVal.

If $val is an xmlrpcval of type array,
the elements of $arrayVal are appended to the
existing ones.

See the fourth constructor form for more information.

If all went OK, 1 is returned, otherwise
0.

addStruct

intaddStruct

array$assocArrayVal

The argument is an associative array. The elements of the
array must be xmlrpcval objects
themselves.

Turns an empty xmlrpcval into a
struct with contents as specified by
$assocArrayVal.

If $val is an xmlrpcval of type struct,
the elements of $arrayVal are merged with the
existing ones.

See the fourth constructor form for more information.

If all went OK, 1 is returned, otherwise
0.

kindOf

stringkindOf

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.

serialize

stringserialize

Returns a string containing the XML-RPC representation of this
value.

scalarVal

mixedscalarVal

If $val->kindOf() == “scalar”, this
method returns the actual PHP-language value of the scalar (base 64
decoding is automatically handled here).

scalarTyp

stringscalarTyp

If $val->kindOf() == “scalar”, this
method returns a string denoting the type of the scalar. As
mentioned before, i4 is always coerced to
int.

arrayMem

xmlrpcvalarrayMem

int$n

If $val->kindOf() == “array”, returns
the $nth element in the array represented by
the value $val. The value returned is an
xmlrpcval object.

// iterating over values of an array object
for ($i = 0; $i < $val->arraySize(); $i++)
{
$v = $val->arrayMem($i);
echo “Element $i of the array is of type “.$v->kindOf();
}

arraySize

intarraySize

If $val is an
array, returns the number of elements in that
array.

structMem

xmlrpcvalstructMem

string$memberName

If $val->kindOf() == “struct”, returns
the element called $memberName from the
struct represented by the value $val. The
value returned is an xmlrpcval object.

structEach

arraystructEach

Returns the next (key, value) pair from the struct, when
$val is a struct.
$value is an xmlrpcval itself. See also .

// iterating over all values of a struct object
$val->structreset();
while (list($key, $v) = $val->structEach())
{
echo “Element $key of the struct is of type “.$v->kindOf();
}

structReset

voidstructReset

Resets the internal pointer for
structEach() to the beginning of the struct,
where $val is a struct.

structMemExists

boolstructMemExsists

string$memberName

Returns TRUE or
FALSE depending on whether a member of the
given name exists in the struct.

xmlrpcmsg

This class provides a representation for a request to an XML-RPC
server. A client sends an xmlrpcmsg to a server,
and receives back an xmlrpcresp (see ).

Creation

The constructor takes the following forms:

xmlrpcmsgnew
xmlrpcmsg

string$methodName

array$parameterArraynull

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

$msg = new xmlrpcmsg(“examples.getStateName”, array(new xmlrpcval(23, “int”)));

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

Note that the parameterArray parameter is
optional and can be omitted for methods that take no input parameters
or if you plan to add parameters one by one.

Methods

addParam

booladdParam

xmlrpcval$xmlrpcVal

Adds the xmlrpcval
xmlrpcVal to the parameter list for this
method call. Returns TRUE or FALSE on error.

getNumParams

intgetNumParams

Returns the number of parameters attached to this
message.

getParam

xmlrpcvalgetParam

int$n

Gets the nth parameter in the message
(with the index zero-based). Use this method in server
implementations to retrieve the values sent by the client.

method

stringmethod

stringmethod

string$methName

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

parseResponse

xmlrpcrespparseResponse

string$xmlString

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

This method processes any HTTP/MIME headers it finds.

parseResponseFile

xmlrpcrespparseResponseFile

file handle
resource$fileHandle

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

This method is useful to construct responses from pre-prepared
files (see files demo1.txt, demo2.txt, demo3.txt
in this distribution). It processes any HTTP headers it finds, and
does not close the file handle.

serialize

string
serialize

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

xmlrpc_client

This is the basic class used to represent a client of an XML-RPC
server.

Creation

The constructor accepts one of two possible syntaxes:

xmlrpc_clientnew
xmlrpc_client

string$server_url

xmlrpc_clientnew
xmlrpc_client

string$server_path

string$server_hostname

int$server_port80

string$transport’http’

Here are a couple of usage examples of the first form:

$client = new xmlrpc_client(“http://phpxmlrpc.sourceforge.net/server.php&#8221;);
$another_client = new xmlrpc_client(“https://james:bond@secret.service.com:443/xmlrpcserver?agent=007&#8221;);

The second syntax does not allow to express a username and
password to be used for basic HTTP authorization as in the second
example above, but instead it allows to choose whether xmlrpc calls
will be made using the HTTP 1.0 or 1.1 protocol.

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

$client = new xmlrpc_client(“/RPC2”, “betty.userland.com”, 80);

The server_port parameter is optional,
and if omitted will default to 80 when using HTTP and 443 when using
HTTPS (see the method
below).

The transport parameter is optional, and
if omitted will default to ‘http’. Allowed values are either
‘http’, ‘https’ or
‘http11’. Its value can be overridden with every call
to the send method. See the
send method below for more details about the
meaning of the different values.

Methods

This class supports the following methods.

send

This method takes the forms:

xmlrpcrespsend

xmlrpcmsg$xmlrpc_message

int$timeout

string$transport

arraysend

array$xmlrpc_messages

int$timeout

string$transport

xmlrpcrespsend

string$xml_payload

int$timeout

string$transport

Where xmlrpc_message is an instance of
xmlrpcmsg (see ),
and response is an instance of
xmlrpcresp (see ).

If xmlrpc_messages is an array of
message instances, responses will be an array of
response instances. The client will try to make use of a single
system.multicall xml-rpc method call to forward to the
server all the messages in a single HTTP round trip, unless
$client->no_multicall has been previously set to
TRUE (see the multicall method below), in which case
many consecutive xmlrpc requests will be sent.

The third syntax allows to build by hand (or any other means)
a complete xmlrpc request message, and send it to the server.
xml_payload should be a string containing the
complete xml representation of the request. It is e.g. useful when,
for maximal speed of execution, the request is serialized into a
string using the native php xmlrpc functions (see the php manual on
xmlrpc).

The timeout is optional, and will be
set to 0 (wait for platform-specific predefined
timeout) if omitted. This timeout value is passed to
fsockopen(). It is also used for detecting
server timeouts during communication (i.e. if the server does not
send anything to the client for timeout
seconds, the connection will be closed).

The transport parameter is optional,
and if omitted will default to the transport set using instance
creator or ‘http’ if omitted. The only other valid values are
‘https’, which will use an SSL HTTP connection to connect to the
remote server, and ‘http11’. Note that your PHP must have the “curl”
extension compiled in order to use both these features. Note that
when using SSL you should normally set your port number to 443,
unless the SSL server you are contacting runs at any other
port.

PHP 4.0.6 has a bug which prevents SSL working.

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

multiCall

This method takes the form:

arraymultiCall

array$messages

int$timeout

string$transport

bool$fallback

This method is used to boxcar many method calls in a single
xml-rpc request. It will try first to make use of the
system.multicall xml-rpc method call, and fall back to
executing many separate requests if the server returns any
error.

msgs is an array of
xmlrpcmsg objects (see ), and response is an
array of xmlrpcresp objects (see ).

The timeout and
transport parameters are optional, and behave
as in the send method above.

The fallback parameter is optional, and
defaults to TRUE. When set to
FALSE it will prevent the client to try using
many single method calls in case of failure of the first multicall
request. It should be set only when the server is known to support
the multicall extension.

setAcceptedCompression

voidsetAcceptedCompression

string$compressionmethod

This method defines whether the client will accept compressed
xml payload forming the bodies of the xmlrpc responses received from
servers. Note that enabling reception of compressed responses merely
adds some standard http headers to xmlrpc requests. It is up to the
xmlrpc server to return compressed responses when receiving such
requests. Allowed values for
compressionmethod are: ‘gzip’, ‘deflate’,
‘any’ or null (with any meaning either gzip or deflate).

This requires the “zlib” extension to be enabled in your php
install. If it is, by default xmlrpc_client
instances will enable reception of compressed content.

setCaCertificate

voidsetCaCertificate

string$certificate

bool$is_dir

This method sets an optional certificate to be used in
SSL-enabled communication to validate a remote server with (when the
server_method is set to ‘https’ in the
client’s construction or in the send method and
SetSSLVerifypeer has been set to
TRUE).

The certificate parameter must be the
filename of a PEM formatted certificate, or a directory containing
multiple certificate files. The is_dir
parameter defaults to FALSE, set it to
TRUE to specify that
certificate indicates a directory instead of
a single file.

This requires the “curl” extension to be compiled into your
installation of PHP. For more details see the man page for the
curl_setopt function.

setCertificate

voidsetCertificate

string$certificate

string$passphrase

This method sets the optional certificate and passphrase used
in SSL-enabled communication with a remote server (when the
server_method is set to ‘https’ in the
client’s construction or in the send method).

The certificate parameter must be the
filename of a PEM formatted certificate. The
passphrase parameter must contain the
password required to use the certificate.

This requires the “curl” extension to be compiled into your
installation of PHP. For more details see the man page for the
curl_setopt function.

Note: to retrieve information about the client certificate on
the server side, you will need to look into the environment
variables which are set up by the webserver. Different webservers
will typically set up different variables.

setCookie

voidsetCookie

string$name

string$value

string$path

string$domain

int$port

This method sets a cookie that will be sent to the xmlrpc
server along with every further request (useful e.g. for keeping
session info outside of the xml-rpc payload).

$value is optional, and defaults to
null.

$path, $domain and $port are optional,
and will be omitted from the cookie header if unspecified. Note that
setting any of these values will turn the cookie into a ‘version 1’
cookie, that might not be fully supported by the server (see RFC2965
for more details).

setCredentials

voidsetCredentials

string$username

string$password

int$authtype

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. Note that username
and password can also be set using the class constructor. With HTTP
1.1 and HTTPS transport, NTLM and Digest authentication protocols
are also supported. To enable them use the constants
CURLAUTH_DIGEST and
CURLAUTH_NTLM as values for the authtype
parameter.

setCurlOptions

voidsetCurlOptions

array$options

This method allows to directly set any desired
option to manipulate the usage of the cURL client (when in cURL
mode). It can be used eg. to explicitly bind to an outgoing ip
address when the server is multihomed

setDebug

voidsetDebug

int$debugLvl

debugLvl is either 0,
1 or 2 depending on whether you require the client to
print debugging information to the browser. The default is not to
output this information (0).

The debugging information at level 1includes the raw data
returned from the XML-RPC server it was querying (including bot HTTP
headers and the full XML payload), and the PHP value the client
attempts to create to represent the value returned by the server. At
level2, the complete payload of the xmlrpc request is also printed,
before being sent t the server.

This option can be very useful when debugging servers as it
allows you to see exactly what the client sends and the server
returns.

setKey

voidsetKey

int$key

int$keypass

This method sets the optional certificate key and passphrase
used in SSL-enabled communication with a remote server (when the
transport is set to ‘https’ in the client’s
construction or in the send method).

This requires the “curl” extension to be compiled into your
installation of PHP. For more details see the man page for the
curl_setopt function.

setProxy

voidsetProxy

string$proxyhost

int$proxyport

string$proxyusername

string$proxypassword

int$authtype

This method enables calling servers via an HTTP proxy. The
proxyusername,
proxypassword and authtype
parameters are optional. Authtype defaults to
CURLAUTH_BASIC (Basic authentication protocol);
the only other valid value is the constant
CURLAUTH_NTLM, and has effect only when the
client uses the HTTP 1.1 protocol.

NB: CURL versions before 7.11.10 cannot use a proxy to
communicate with https servers.

setRequestCompression

voidsetRequestCompression

string$compressionmethod

This method defines whether the xml payload forming the
request body will be sent to the server in compressed format, as per
the HTTP specification. This is particularly useful for large
request parameters and over slow network connections. Allowed values
for compressionmethod are: ‘gzip’, ‘deflate’,
‘any’ or null (with any meaning either gzip or deflate). Note that
there is no automatic fallback mechanism in place for errors due to
servers not supporting receiving compressed request bodies, so make
sure that the particular server you are querying does accept
compressed requests before turning it on.

This requires the “zlib” extension to be enabled in your php
install.

setSSLVerifyHost

voidsetSSLVerifyHost

int$i

This method defines whether connections made to XML-RPC
backends via HTTPS should verify the remote host’s SSL certificate’s
common name (CN). By default, only the existence of a CN is checked.
$i should be an
integer value; 0 to not check the CN at all, 1 to merely check for
its existence, and 2 to check that the CN on the certificate matches
the hostname that is being connected to.

setSSLVerifyPeer

voidsetSSLVerifyPeer

bool$i

This method defines whether connections made to XML-RPC
backends via HTTPS should verify the remote host’s SSL certificate,
and cause the connection to fail if the cert verification fails.
$i should be a boolean
value. Default value: TRUE. To specify custom
SSL certificates to validate the server with, use the
setCaCertificate method.

setUserAgent

voidUseragent

string$useragent

This method sets a custom user-agent that will be
used by the client in the http headers sent with the request. The
default value is built using the library name and version
constants.

Variables

NB: direct manipulation of these variables is only recommended
for advanced users.

no_multicall

This member variable determines whether the multicall() method
will try to take advantage of the system.multicall xmlrpc method to
dispatch to the server an array of requests in a single http
roundtrip or simply execute many consecutive http calls. Defaults to
FALSE, but it will be enabled automatically on the first failure of
execution of system.multicall.

request_charset_encoding

This is the charset encoding that will be used for serializing
request sent by the client.

If defaults to NULL, which means using US-ASCII and encoding
all characters outside of the ASCII range using their xml character
entity representation (this has the benefit that line end characters
will not be mangled in the transfer, a CR-LF will be preserved as
well as a singe LF).

Valid values are ‘US-ASCII’, ‘UTF-8’ and ‘ISO-8859-1’

return_type

This member variable determines whether the value returned
inside an xmlrpcresp object as results of calls to the send() and
multicall() methods will be an xmlrpcval object, a plain php value
or a raw xml string. Allowed values are ‘xmlrpcvals’ (the default),
‘phpvals’ and ‘xml’. To allow the user to differentiate between a
correct and a faulty response, fault responses will be returned as
xmlrpcresp objects in any case. Note that the ‘phpvals’ setting will
yield faster execution times, but some of the information from the
original response will be lost. It will be e.g. impossible to tell
whether a particular php string value was sent by the server as an
xmlrpc string or base64 value.

Example usage:

$client = new xmlrpc_client(“phpxmlrpc.sourceforge.net/server”);
$client->return_type = ‘phpvals’;
$message = new xmlrpcmsg(“examples.getStateName”, array(new xmlrpcval(23, “int”)));
$resp = $client->send($message);
if ($resp->faultCode()) echo ‘KO. Error: ‘.$resp->faultString(); else echo ‘OK: got ‘.$resp->value();

For more details about usage of the ‘xml’ value, see Appendix
A.

xmlrpcresp

This class is used to contain responses to XML-RPC requests. A
server method handler will construct an
xmlrpcresp 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
xmlrpc_client class.

Creation

xmlrpcrespnew
xmlrpcresp

xmlrpcval$xmlrpcval

xmlrpcrespnew
xmlrpcresp

0

int$errcode

string$err_string

The first syntax is used when execution has happened without
difficulty: $xmlrpcval is an
xmlrpcval value with the result of the method
execution contained in it. Alternatively it can be a string containing
the xml serialization of the single xml-rpc value result of method
execution.

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

Methods

faultCode

intfaultCode

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

faultString

stringfaultString

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

value

xmlrpcvalvalue

Returns an xmlrpcval 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).

Note: if the xmlrpcresp instance in question has been created
by an xmlrpc_client object whose
return_type was set to ‘phpvals’, then a plain
php value will be returned instead of an
xmlrpcval object. If the
return_type was set to ‘xml’, an xml string will
be returned (see the return_type member var above for more
details).

serialize

stringserialize

Returns an XML string representation of the response (xml
prologue not included).

xmlrpc_server

The implementation of this class has been kept as simple to use as
possible. The constructor for the server basically does all the work.
Here’s a minimal example:

function foo ($xmlrpcmsg) {

return new xmlrpcresp($some_xmlrpc_val);
}

class bar {
function foobar($xmlrpcmsg) {

return new xmlrpcresp($some_xmlrpc_val);
}
}

$s = new xmlrpc_server(
array(
“examples.myFunc1” => array(“function” => “foo”),
“examples.myFunc2” => array(“function” => “bar::foobar”),
));

This performs everything you need to do with a server. The single
constructor argument is an associative array from xmlrpc method names to
php function names. The incoming request is parsed and dispatched to the
relevant php function, which is responsible for returning a
xmlrpcresp object, that will be serialized back
to the caller.

Method handler functions

Both php functions and class methods can be registered as xmlrpc
method handlers.

The synopsis of a method handler function is:

xmlrpcresp $resp = function (xmlrpcmsg $msg)

No text should be echoed ‘to screen’ by the handler function, or
it will break the xml response sent back to the client. This applies
also to error and warning messages that PHP prints to screen unless
the appropriate parameters have been set in the php.in file. Another
way to prevent echoing of errors inside the response and facilitate
debugging is to use the server SetDebug method with debug level 3 (see
…). Exceptions thrown duting execution of handler functions are
caught by default and a XML-RPC error reponse is generated instead.
This behaviour can be finetuned by usage of the
exception_handling member variable (see
…).

Note that if you implement a method with a name prefixed by
system. the handler function will be invoked by the
server with two parameters, the first being the server itself and the
second being the xmlrpcmsg object.

The same php function can be registered as handler of multiple
xmlrpc methods.

Here is a more detailed example of what the handler function
foo may do:

function foo ($xmlrpcmsg) {
global $xmlrpcerruser; // import user errcode base value

$meth = $xmlrpcmsg->method(); // retrieve method name
$par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter – assumes at least one param received
$val = $par->scalarval(); // decode value of first parameter – assumes it is a scalar value

if ($err) {
// this is an error condition
return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
“There’s a problem, Captain”);
} else {
// this is a successful value being returned
return new xmlrpcresp(new xmlrpcval(“All’s fine!”, “string”));
}
}

See server.php in this distribution for
more examples of how to do this.

Since release 2.0RC3 there is a new, even simpler way of
registering php functions with the server. See section 5.7
below

The dispatch map

The first argument to the xmlrpc_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 either a name of a function in the
global scope which services the XML-RPC method, or an array
containing an instance of an object and a static method name (for
static class methods the ‘class::method’ syntax is also
supported).

signature – this
entry is an array containing the possible signatures (see ) 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.

signature_docs – this entry can be used
to provide documentation for the single parameters. It must match
in structure the ‘signature’ member. By default, only the
documenting_xmlrpc_server class in the
extras package will take advantage of this, since the
“system.methodHelp” protocol does not support documenting method
parameters individually.

parameters_type – this entry can be used
when the server is working in ‘xmlrpcvals’ mode (see …) to
define one or more entries in the dispatch map as being functions
that follow the ‘phpvals’ calling convention. The only useful
value is currently the string phpvals.

Look at the server.php example in the
distribution to see what a dispatch map looks like.

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. For instance, the method string examples.getStateName(int)
has the signature array($xmlrpcString, $xmlrpcInt)
and, assuming that it is the only possible signature for the
method, it might be used like this in server creation:
$findstate_sig = array(array($xmlrpcString, $xmlrpcInt));

$findstate_doc = ‘When passed an integer between 1 and 51 returns the
name of a US state, where the integer is the index of that state name
in an alphabetic order.’;

$s = new xmlrpc_server( array(
“examples.getStateName” => array(
“function” => “findstate”,
“signature” => $findstate_sig,
“docstring” => $findstate_doc
)));

Note that method signatures do not allow to check nested
parameters, e.g. the number, names and types of the members of a
struct param cannot be validated.

If a method that you want to expose has a definite number of
parameters, but each of those parameters could reasonably be of
multiple types, the array of acceptable signatures will easily grow
into a combinatorial explosion. To avoid such a situation, the lib
defines the global var $xmlrpcValue, which can be
used in method signatures as a placeholder for ‘any xmlrpc
type’:

$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));

$findstate_doc = ‘Echoes back to the client the received value, regardless of its type’;

$s = new xmlrpc_server( array(
“echoBack” => array(
“function” => “echoback”,
“signature” => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
“docstring” => $echoback_doc
)));

Methods system.listMethods,
system.methodHelp,
system.methodSignature and
system.multicall are already defined by the
server, and should not be reimplemented (see Reserved Methods
below).

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 omit to pass to the constructor the dispatch map or pass it 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:

$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request

// … some code that does other stuff here

$s->service();

Note that the service method will print
the complete result payload to screen and send appropriate HTTP
headers back to the client, but also return the response object. This
permits further manipulation of the response, possibly in combination
with output buffering.

To prevent the server from sending HTTP headers back to the
client, you can pass a second parameter with a value of
TRUE to the service
method. In this case, the response payload will be returned instead of
the response object.

Xmlrpc requests retrieved by other means than HTTP POST bodies
can also be processed. For example:

$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request

// … some code that does other stuff here, including setting dispatch map into server object

$resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload

// … some code that does other stuff with xml response $resp here

Modifying the server behaviour

A couple of methods / class variables are available to modify
the behaviour of the server. The only way to take advantage of their
existence is by usage of a delayed server response (see above)

setDebug()

This function controls weather the server is going to echo
debugging messages back to the client as comments in response body.
Valid values: 0,1,2,3, with 1 being the default. At level 0, no
debug info is returned to the client. At level 2, the complete
client request is added to the response, as part of the xml
comments. At level 3, a new PHP error handler is set when executing
user functions exposed as server methods, and all non-fatal errors
are trapped and added as comments into the response.

allow_system_funcs

Default_value: TRUE. When set to FALSE, disables support for
System.xxx functions in the server. It
might be useful e.g. if you do not wish the server to respond to
requests to System.ListMethods.

compress_response

When set to TRUE, enables the server to take advantage of HTTP
compression, otherwise disables it. Responses will be transparently
compressed, but only when an xmlrpc-client declares its support for
compression in the HTTP headers of the request.

Note that the ZLIB php extension must be installed for this to
work. If it is, compress_response will default to
TRUE.

exception_handling

This variable controls the behaviour of the server when an
exception is thrown by a method handler php function. Valid values:
0,1,2, with 0 being the default. At level 0, the server catches the
exception and return an ‘internal error’ xmlrpc response; at 1 it
catches the exceptions and return an xmlrpc response with the error
code and error message corresponding to the exception that was
thron; at 2 = the exception is floated to the upper layers in the
code

response_charset_encoding

Charset encoding to be used for response (only affects string
values).

If it can, the server will convert the generated response from
internal_encoding to the intended one.

Valid values are: a supported xml encoding (only UTF-8 and
ISO-8859-1 at present, unless mbstring is enabled), null (leave
charset unspecified in response and convert output stream to
US_ASCII), ‘default’ (use xmlrpc library default as specified in
xmlrpc.inc, convert output stream if needed), or ‘auto’ (use
client-specified charset encoding or same as request if request
headers do not specify it (unless request is US-ASCII: then use
library default anyway).

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:

1 Unknown method

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

2 Invalid return
payload

This error is actually generated by the client, not
server, code, but signifies that a server returned something it
couldn’t understand. A more detailed error report is sometimes
added onto the end of the phrase above.

3 Incorrect
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.

4 Can’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.

5 Didn’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.

6 No data received from
server

This error is generated by the client when a remote server
returns HTTP/1.1 200 OK in response to a request, but no
response body follows the HTTP headers.

7 No SSL support compiled
in

This error is generated by the client when trying to send
a request with HTTPS and the CURL extension is not available to
PHP.

8 CURL error

This error is generated by the client when trying to send
a request with HTTPS and the HTTPS communication fails.

9-14 multicall
errors

These errors are generated by the server when something
fails inside a system.multicall request.

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.

‘New style’ servers

In the same spirit of simplification that inspired the
xmlrpc_client::return_type class variable, a new
class variable has been added to the server class:
functions_parameters_type. When set to ‘phpvals’,
the functions registered in the server dispatch map will be called
with plain php values as parameters, instead of a single xmlrpcmsg
instance parameter. The return value of those functions is expected to
be a plain php value, too. An example is worth a thousand
words:
function foo($usr_id, $out_lang=’en’) {
global $xmlrpcerruser;

if ($someErrorCondition)
return new xmlrpcresp(0, $xmlrpcerruser+1, ‘DOH!’);
else
return array(
‘name’ => ‘Joe’,
‘age’ => 27,
‘picture’ => new xmlrpcval(file_get_contents($picOfTheGuy), ‘base64’)
);
}

$s = new xmlrpc_server(
array(
“examples.myFunc” => array(
“function” => “bar::foobar”,
“signature” => array(
array($xmlrpcString, $xmlrpcInt),
array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
)
)
), false);
$s->functions_parameters_type = ‘phpvals’;
$s->service();
There are a few things to keep in mind when using this
simplified syntax:

to return an xmlrpc error, the method handler function must
return an instance of xmlrpcresp. The only
other way for the server to know when an error response should be
served to the client is to throw an exception and set the server’s
exception_handling memeber var to 1;

to return a base64 value, the method handler function must
encode it on its own, creating an instance of an xmlrpcval
object;

the method handler function cannot determine the name of the
xmlrpc method it is serving, unlike standard handler functions that
can retrieve it from the message object;

when receiving nested parameters, the method handler function
has no way to distinguish a php string that was sent as base64 value
from one that was sent as a string value;

this has a direct consequence on the support of
system.multicall: a method whose signature contains datetime or base64
values will not be available to multicall calls;

last but not least, the direct parsing of xml to php values is
much faster than using xmlrpcvals, and allows the library to handle
much bigger messages without allocating all available server memory or
smashing PHP recursive call stack.

Global variables

Many global variables are defined in the xmlrpc.inc file. Some of
those are meant to be used as constants (and modifying their value might
cause unpredictable behaviour), while some others can be modified in your
php scripts to alter the behaviour of the xml-rpc client and
server.

“Constant” variables

$xmlrpcerruser

$xmlrpcerruser

800
The minimum value for errors reported by user
implemented XML-RPC servers. Error numbers lower than that are
reserved for library usage.

$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
$xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,
$xmlrpcStruct, $xmlrpcValue, $xmlrpcNull

For convenience the strings representing the XML-RPC types have
been encoded as global variables:
$xmlrpcI4=”i4″;
$xmlrpcInt=”int”;
$xmlrpcBoolean=”boolean”;
$xmlrpcDouble=”double”;
$xmlrpcString=”string”;
$xmlrpcDateTime=”dateTime.iso8601″;
$xmlrpcBase64=”base64″;
$xmlrpcArray=”array”;
$xmlrpcStruct=”struct”;
$xmlrpcValue=”undefined”;
$xmlrpcNull=”null”;

$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
$xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
$xmlEntities, $xmlrpcs_capabilities

Reserved for internal usage.

Variables whose value can be modified

xmlrpc_defencoding

$xmlrpc_defencoding

“UTF8”

This variable defines the character set encoding that will be
used by the xml-rpc client and server to decode the received messages,
when a specific charset declaration is not found (in the messages sent
non-ascii chars are always encoded using character references, so that
the produced xml is valid regardless of the charset encoding
assumed).

Allowed values: “UTF8”,
“ISO-8859-1”, “ASCII”.

Note that the appropriate RFC actually mandates that XML
received over HTTP without indication of charset encoding be treated
as US-ASCII, but many servers and clients ‘in the wild’ violate the
standard, and assume the default encoding is UTF-8.

xmlrpc_internalencoding

$xmlrpc_internalencoding

“ISO-8859-1”
This variable defines the character set encoding
that the library uses to transparently encode into valid XML the
xml-rpc values created by the user and to re-encode the received
xml-rpc values when it passes them to the PHP application. It only
affects xml-rpc values of string type. It is a separate value from
xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
character set used internally by PHP (unless you are running an
MBString-enabled installation), so you should change it only in
special situations, if e.g. the string values exchanged in the xml-rpc
messages are directly inserted into / fetched from a database
configured to return UTF8 encoded strings to PHP. Example
usage:

<?php

include(‘xmlrpc.inc’);
$xmlrpc_internalencoding = ‘UTF-8’; // this has to be set after the inclusion above
$v = new xmlrpcval(‘κόσμε’); // This xmlrpc value will be correctly serialized as the greek word ‘kosme’

xmlrpcName

$xmlrpcName

“XML-RPC for PHP”
The string representation of the name of the XML-RPC
for PHP library. It is used by the client for building the User-Agent
HTTP header that is sent with every request to the server. You can
change its value if you need to customize the User-Agent
string.

xmlrpcVersion

$xmlrpcVersion

“2.2”
The string representation of the version number of
the XML-RPC for PHP library in use. It is used by the client for
building the User-Agent HTTP header that is sent with every request to
the server. You can change its value if you need to customize the
User-Agent string.

xmlrpc_null_extension

When set to TRUE, the lib will enable
support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
per the extension to the standard proposed here. This means that
<NIL/> and <EX:NIL/> tags received will be parsed as valid
xmlrpc, and the corresponding xmlrpcvals will return “null” for
scalarTyp().

xmlrpc_null_apache_encoding

When set to TRUE, php NULL values encoded
into xmlrpcval objects get serialized using the
<EX:NIL/> tag instead of
<NIL/>. Please note that both forms are
always accepted as input regardless of the value of this
variable.

Helper functions

XML-RPC for PHP contains some helper functions which you can use to
make processing of XML-RPC requests easier.

Date functions

The XML-RPC specification has this to say on dates:

Don’t assume a timezone. It should be
specified by the server in its documentation what assumptions it makes
about timezones.

Unfortunately, this means that date processing isn’t
straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn’t
use the timezone specifier.

We strongly recommend that in every case where you pass dates in
XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
languages include routines for handling GMT times natively, and you
won’t have to translate between timezones.

For more information about dates, see ISO 8601: The Right
Format for Dates, which has a handy link to a PDF of the ISO
8601 specification. Note that XML-RPC uses exactly one of the available
representations: CCYYMMDDTHH:MM:SS.

iso8601_encode

stringiso8601_encode

string$time_t

int$utc0

Returns an ISO 8601 formatted date generated from the UNIX
timestamp $time_t, as returned by the PHP
function time().

The argument $utc can be omitted, in
which case it defaults to 0. If it is set to
1, then the function corrects the time passed in
for UTC. Example: if you’re in the GMT-6:00 timezone and set
$utc, you will receive a date representation
six hours ahead of your local time.

The included demo program vardemo.php
includes a demonstration of this function.

iso8601_decode

intiso8601_decode

string$isoString

int$utc0

Returns a UNIX timestamp from an ISO 8601 encoded time and date
string passed in. If $utc is
1 then $isoString is assumed
to be in the UTC timezone, and thus the result is also UTC: otherwise,
the timezone is assumed to be your local timezone and you receive a
local timestamp.

Easy use with nested PHP values

Dan Libby was kind enough to contribute two helper functions that
make it easier to translate to and from PHP values. This makes it easier
to deal with complex structures. At the moment support is limited to
int, double, string,
array, datetime and struct
datatypes; note also that all PHP arrays are encoded as structs, except
arrays whose keys are integer numbers starting with 0 and incremented by
1.

These functions reside in xmlrpc.inc.

php_xmlrpc_decode

mixedphp_xmlrpc_decode

xmlrpcval$xmlrpc_val

array$options

arrayphp_xmlrpc_decode

xmlrpcmsg$xmlrpcmsg_val

string$options

Returns a native PHP value corresponding to the values found in
the xmlrpcval $xmlrpc_val,
translated into PHP types. Base-64 and datetime values are
automatically decoded to strings.

In the second form, returns an array containing the parameters
of the given
xmlrpcmsg_val, decoded
to php types.

The options parameter is optional. If
specified, it must consist of an array of options to be enabled in the
decoding process. At the moment the only valid option are
decode_php_objs and
dates_as_objects. When the first is set, php
objects that have been converted to xml-rpc structs using the
php_xmlrpc_encode function and a corresponding
encoding option will be converted back into object values instead of
arrays (provided that the class definition is available at
reconstruction time). When the second is set, XML-RPC datetime values
will be converted into native dateTime objects
instead of strings.

WARNING: please take
extreme care before enabling the decode_php_objs
option: when php objects are rebuilt from the received xml, their
constructor function will be silently invoked. This means that you are
allowing the remote end to trigger execution of uncontrolled PHP code
on your server, opening the door to code injection exploits. Only
enable this option when you have complete trust of the remote
server/client.

Example:
// wrapper to expose an existing php function as xmlrpc method handler
function foo_wrapper($m)
{
$params = php_xmlrpc_decode($m);
$retval = call_user_func_array(‘foo’, $params);
return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
}

$s = new xmlrpc_server(array(
“examples.myFunc1” => array(
“function” => “foo_wrapper”,
“signatures” => …
)));

php_xmlrpc_encode

xmlrpcvalphp_xmlrpc_encode

mixed$phpval

array$options

Returns an xmlrpcval object populated with the PHP
values in $phpval. Works recursively on arrays
and objects, encoding numerically indexed php arrays into array-type
xmlrpcval objects and non numerically indexed php arrays into
struct-type xmlrpcval objects. Php objects are encoded into
struct-type xmlrpcvals, excepted for php values that are already
instances of the xmlrpcval class or descendants thereof, which will
not be further encoded. Note that there’s no support for encoding php
values into base-64 values. Encoding of date-times is optionally
carried on on php strings with the correct format.

The options parameter is optional. If
specified, it must consist of an array of options to be enabled in the
encoding process. At the moment the only valid options are
encode_php_objs, null_extension
and auto_dates.

The first will enable the creation of ‘particular’ xmlrpcval
objects out of php objects, that add a “php_class” xml attribute to
their serialized representation. This attribute allows the function
php_xmlrpc_decode to rebuild the native php objects (provided that the
same class definition exists on both sides of the communication). The
second allows to encode php NULL values to the
<NIL/> (or
<EX:NIL/>, see …) tag. The last encodes any
string that matches the ISO8601 format into an XML-RPC
datetime.

Example:
// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
$val = php_xmlrpc_encode(array(
‘first struct_element: an int’ => 666,
‘second: an array’ => array (‘apple’, ‘orange’, ‘banana’),
‘third: a base64 element’ => new xmlrpcval(‘hello world’, ‘base64’),
‘fourth: a datetime’ => ‘20060107T01:53:00’
), array(‘auto_dates’));

php_xmlrpc_decode_xml

xmlrpcval | xmlrpcresp |
xmlrpcmsgphp_xmlrpc_decode_xml

string$xml

array$options

Decodes the xml representation of either an xmlrpc request,
response or single value, returning the corresponding php-xmlrpc
object, or FALSE in case of an error.

The options parameter is optional. If
specified, it must consist of an array of options to be enabled in the
decoding process. At the moment, no option is supported.

Example:
$text = ‘<value><array><data><value>Hello world</value></data></array></value>’;
$val = php_xmlrpc_decode_xml($text);
if ($val) echo ‘Found a value of type ‘.$val->kindOf(); else echo ‘Found invalid xml’;

Automatic conversion of php functions into xmlrpc methods (and
vice versa)

For the extremely lazy coder, helper functions have been added
that allow to convert a php function into an xmlrpc method, and a
remotely exposed xmlrpc method into a local php function – or a set of
methods into a php class. Note that these comes with many caveat.

wrap_xmlrpc_method

stringwrap_xmlrpc_method

$client

$methodname

$extra_options

stringwrap_xmlrpc_method

$client

$methodname

$signum

$timeout

$protocol

$funcname

Given an xmlrpc server and a method name, creates a php wrapper
function that will call the remote method and return results using
native php types for both params and results. The generated php
function will return an xmlrpcresp object for failed xmlrpc
calls.

The second syntax is deprecated, and is listed here only for
backward compatibility.

The server must support the
system.methodSignature xmlrpc method call for
this function to work.

The client param must be a valid
xmlrpc_client object, previously created with the address of the
target xmlrpc server, and to which the preferred communication options
have been set.

The optional parameters can be passed as array key,value pairs
in the extra_options param.

The signum optional param has the purpose
of indicating which method signature to use, if the given server
method has multiple signatures (defaults to 0).

The timeout and
protocol optional params are the same as in the
xmlrpc_client::send() method.

If set, the optional new_function_name
parameter indicates which name should be used for the generated
function. In case it is not set the function name will be
auto-generated.

If the return_source optional parameter is
set, the function will return the php source code to build the wrapper
function, instead of evaluating it (useful to save the code and use it
later as stand-alone xmlrpc client).

If the encode_php_objs optional parameter is
set, instances of php objects later passed as parameters to the newly
created function will receive a ‘special’ treatment that allows the
server to rebuild them as php objects instead of simple arrays. Note
that this entails using a “slightly augmented” version of the xmlrpc
protocol (ie. using element attributes), which might not be understood
by xmlrpc servers implemented using other libraries.

If the decode_php_objs optional parameter is
set, instances of php objects that have been appropriately encoded by
the server using a coordinate option will be deserialized as php
objects instead of simple arrays (the same class definition should be
present server side and client side).

Note that this might pose a security risk,
since in order to rebuild the object instances their constructor
method has to be invoked, and this means that the remote server can
trigger execution of unforeseen php code on the client: not really a
code injection, but almost. Please enable this option only when you
trust the remote server.

In case of an error during generation of the wrapper function,
FALSE is returned, otherwise the name (or source code) of the new
function.

Known limitations: server must support
system.methodsignature for the wanted xmlrpc
method; for methods that expose multiple signatures, only one can be
picked; for remote calls with nested xmlrpc params, the caller of the
generated php function has to encode on its own the params passed to
the php function if these are structs or arrays whose (sub)members
include values of type base64.

Note: calling the generated php function ‘might’ be slow: a new
xmlrpc client is created on every invocation and an xmlrpc-connection
opened+closed. An extra ‘debug’ param is appended to the parameter
list of the generated php function, useful for debugging
purposes.

Example usage:

$c = new xmlrpc_client(‘http://phpxmlrpc.sourceforge.net/server.php&#8217;);

$function = wrap_xmlrpc_method($client, ‘examples.getStateName’);

if (!$function)
die(‘Cannot introspect remote method’);
else {
$stateno = 15;
$statename = $function($a);
if (is_a($statename, ‘xmlrpcresp’)) // call failed
{
echo ‘Call failed: ‘.$statename->faultCode().’. Calling again with debug on’;
$function($a, true);
}
else
echo “OK, state nr. $stateno is $statename”;
}

wrap_php_function

arraywrap_php_function

string$funcname

string$wrapper_function_name

array$extra_options

Given a user-defined PHP function, create a PHP ‘wrapper’
function that can be exposed as xmlrpc method from an xmlrpc_server
object and called from remote clients, and return the appropriate
definition to be added to a server’s dispatch map.

The optional $wrapper_function_name
specifies the name that will be used for the auto-generated
function.

Since php is a typeless language, to infer types of input and
output parameters, it relies on parsing the javadoc-style comment
block associated with the given function. Usage of xmlrpc native types
(such as datetime.dateTime.iso8601 and base64) in the docblock @param
tag is also allowed, if you need the php function to receive/send data
in that particular format (note that base64 encoding/decoding is
transparently carried out by the lib, while datetime vals are passed
around as strings).

Known limitations: requires PHP 5.0.3 +; only works for
user-defined functions, not for PHP internal functions (reflection
does not support retrieving number/type of params for those); the
wrapped php function will not be able to programmatically return an
xmlrpc error response.

If the return_source optional parameter is
set, the function will return the php source code to build the wrapper
function, instead of evaluating it (useful to save the code and use it
later in a stand-alone xmlrpc server). It will be in the stored in the
source member of the returned array.

If the suppress_warnings optional parameter
is set, any runtime warning generated while processing the
user-defined php function will be catched and not be printed in the
generated xml response.

If the extra_options array contains the
encode_php_objs value, wrapped functions returning
php objects will generate “special” xmlrpc responses: when the xmlrpc
decoding of those responses is carried out by this same lib, using the
appropriate param in php_xmlrpc_decode(), the objects will be
rebuilt.

In short: php objects can be serialized, too (except for their
resource members), using this function. Other libs might choke on the
very same xml that will be generated in this case (i.e. it has a
nonstandard attribute on struct element tags)

If the decode_php_objs optional parameter is
set, instances of php objects that have been appropriately encoded by
the client using a coordinate option will be deserialized and passed
to the user function as php objects instead of simple arrays (the same
class definition should be present server side and client
side).

Note that this might pose a security risk,
since in order to rebuild the object instances their constructor
method has to be invoked, and this means that the remote client can
trigger execution of unforeseen php code on the server: not really a
code injection, but almost. Please enable this option only when you
trust the remote clients.

Example usage:

/**
* State name from state number decoder. NB: do NOT remove this comment block.
* @param integer $stateno the state number
* @return string the name of the state (or error description)
*/
function findstate($stateno)
{
global $stateNames;
if (isset($stateNames[$stateno-1]))
{
return $stateNames[$stateno-1];
}
else
{
return “I don’t have a state for the index ‘” . $stateno . “‘”;
}
}

// wrap php function, build xmlrpc server
$methods = array();
$findstate_sig = wrap_php_function(‘findstate’);
if ($findstate_sig)
$methods[‘examples.getStateName’] = $findstate_sig;
$srv = new xmlrpc_server($methods);

Functions removed from the library

The following two functions have been deprecated in version 1.1 of
the library, and removed in version 2, in order to avoid conflicts with
the EPI xml-rpc library, which also defines two functions with the same
names.

To ease the transition to the new naming scheme and avoid breaking
existing implementations, the following scheme has been adopted:

If EPI-XMLRPC is not active in the current PHP installation,
the constant XMLRPC_EPI_ENABLED will be set to
‘0’

If EPI-XMLRPC is active in the current PHP installation, the
constant XMLRPC_EPI_ENABLED will be set to
‘1’

The following documentation is kept for historical
reference:

xmlrpc_decode

mixedxmlrpc_decode

xmlrpcval$xmlrpc_val

Alias for php_xmlrpc_decode.

xmlrpc_encode

xmlrpcvalxmlrpc_encode

mixed$phpval

Alias for php_xmlrpc_encode.

Debugging aids

xmlrpc_debugmsg

voidxmlrpc_debugmsg

string$debugstring

Sends the contents of $debugstring in XML
comments in the server return payload. If a PHP client has debugging
turned on, the user will be able to see server debug
information.

Use this function in your methods so you can pass back
diagnostic information. It is only available from
xmlrpcs.inc.

Reserved methods

In order to extend the functionality offered by XML-RPC servers
without impacting on the protocol, reserved methods are supported in this
release.

All methods starting with system. are
considered reserved by the server. PHP for XML-RPC itself provides four
special methods, detailed in this chapter.

Note that all server objects will automatically respond to clients
querying these methods, unless the property
allow_system_funcs has been set to
false before calling the
service() method. This might pose a security risk
if the server is exposed to public access, e.g. on the internet.

system.getCapabilities

system.listMethods

This method may be used to enumerate the methods implemented by
the XML-RPC server.

The system.listMethods method requires no
parameters. It returns an array of strings, each of which is the name of
a method implemented by the server.

system.methodSignature

This method takes one parameter, the name of a method implemented
by the XML-RPC server.

It returns an array of possible signatures for this method. A
signature is an array of types. The first of these types is the return
type of the method, the rest are parameters.

Multiple signatures (i.e. overloading) are permitted: this is the
reason that an array of signatures are returned by this method.

Signatures themselves are restricted to the top level parameters
expected by a method. For instance if a method expects one array of
structs as a parameter, and it returns a string, its signature is simply
“string, array”. If it expects three integers, its signature is “string,
int, int, int”.

For parameters that can be of more than one type, the “undefined”
string is supported.

If no signature is defined for the method, a not-array value is
returned. Therefore this is the way to test for a non-signature, if
$resp below is the response object from a method
call to system.methodSignature:

$v = $resp->value();
if ($v->kindOf() != “array”) {
// then the method did not have a signature defined
}

See the introspect.php demo included in this
distribution for an example of using this method.

system.methodHelp

This method takes one parameter, the name of a method implemented
by the XML-RPC server.

It returns a documentation string describing the use of that
method. If no such string is available, an empty string is
returned.

The documentation string may contain HTML markup.

system.multicall

This method takes one parameter, an array of ‘request’ struct
types. Each request struct must contain a
methodName member of type string and a
params member of type array, and corresponds to
the invocation of the corresponding method.

It returns a response of type array, with each value of the array
being either an error struct (containing the faultCode and faultString
members) or the successful response value of the corresponding single
method call.

Examples

The best examples are to be found in the sample files included with
the distribution. Some are included here.

XML-RPC client: state name query

Code to get the corresponding state name from a number (1-50) from
the demo server available on SourceForge

$m = new xmlrpcmsg(‘examples.getStateName’,
array(new xmlrpcval($HTTP_POST_VARS[“stateno”], “int”)));
$c = new xmlrpc_client(“/server.php”, “phpxmlrpc.sourceforge.net”, 80);
$r = $c->send($m);
if (!$r->faultCode()) {
$v = $r->value();
print “State number ” . htmlentities($HTTP_POST_VARS[“stateno”]) . ” is ” .
htmlentities($v->scalarval()) . “<BR>”;
print “<HR>I got this value back<BR><PRE>” .
htmlentities($r->serialize()) . “</PRE><HR>\n”;
} else {
print “Fault <BR>”;
print “Code: ” . htmlentities($r->faultCode()) . “<BR>” .
“Reason: ‘” . htmlentities($r->faultString()) . “‘<BR>”;
}

Executing a multicall call

To be documented…

Frequently Asked Questions

How to send custom XML as payload of a method call

Unfortunately, at the time the XML-RPC spec was designed, support
for namespaces in XML was not as ubiquitous as it is now. As a
consequence, no support was provided in the protocol for embedding XML
elements from other namespaces into an xmlrpc request.

To send an XML “chunk” as payload of a method call or response,
two options are available: either send the complete XML block as a
string xmlrpc value, or as a base64 value. Since the ‘<‘ character in
string values is encoded as ‘&lt;’ in the xml payload of the method
call, the XML string will not break the surrounding xmlrpc, unless
characters outside of the assumed character set are used. The second
method has the added benefits of working independently of the charset
encoding used for the xml to be transmitted, and preserving exactly
whitespace, whilst incurring in some extra message length and cpu load
(for carrying out the base64 encoding/decoding).

Is there any limitation on the size of the requests / responses
that can be successfully sent?

Yes. But I have no hard figure to give; it most likely will depend
on the version of PHP in usage and its configuration.

Keep in mind that this library is not optimized for speed nor for
memory usage. Better alternatives exist when there are strict
requirements on throughput or resource usage, such as the php native
xmlrpc extension (see the PHP manual for more information).

Keep in mind also that HTTP is probably not the best choice in
such a situation, and XML is a deadly enemy. CSV formatted data over
socket would be much more efficient.

If you really need to move a massive amount of data around, and
you are crazy enough to do it using phpxmlrpc, your best bet is to
bypass usage of the xmlrpcval objects, at least in the decoding phase,
and have the server (or client) object return to the calling function
directly php values (see xmlrpc_client::return_type
and xmlrpc_server::functions_parameters_type for more
details).

My server (client) returns an error whenever the client (server)
returns accented characters

To be documented…

How to enable long-lasting method calls

To be documented…

My client returns “XML-RPC Fault #2: Invalid return payload:
enable debugging to examine incoming payload”: what should I do?

The response you are seeing is a default error response that the
client object returns to the php application when the server did not
respond to the call with a valid xmlrpc response.

The most likely cause is that you are not using the correct URL
when creating the client object, or you do not have appropriate access
rights to the web page you are requesting, or some other common http
misconfiguration.

To find out what the server is really returning to your client,
you have to enable the debug mode of the client, using
$client->setdebug(1);

How can I save to a file the xml of the xmlrpc responses received
from servers?

If what you need is to save the responses received from the server
as xml, you have two options:

1- use the serialize() method on the response object.

$resp = $client->send($msg);
if (!$resp->faultCode())
$data_to_be_saved = $resp->serialize();

Note that this will not be 100% accurate, since the xml generated
by the response object can be different from the xml received,
especially if there is some character set conversion involved, or such
(eg. if you receive an empty string tag as <string/>, serialize()
will output <string></string>), or if the server sent back
as response something invalid (in which case the xml generated client
side using serialize() will correspond to the error response generated
internally by the lib).

2 – set the client object to return the raw xml received instead
of the decoded objects:

$client = new xmlrpc_client($url);
$client->return_type = ‘xml’;
$resp = $client->send($msg);
if (!$resp->faultCode())
$data_to_be_saved = $resp->value();

Note that using this method the xml response response will not be
parsed at all by the library, only the http communication protocol will
be checked. This means that xmlrpc responses sent by the server that
would have generated an error response on the client (eg. malformed xml,
responses that have faultcode set, etc…) now will not be flagged as
invalid, and you might end up saving not valid xml but random
junk…

Can I use the ms windows character set?

If the data your application is using comes from a Microsoft
application, there are some chances that the character set used to
encode it is CP1252 (the same might apply to data received from an
external xmlrpc server/client, but it is quite rare to find xmlrpc
toolkits that encode to CP1252 instead of UTF8). It is a character set
which is “almost” compatible with ISO 8859-1, but for a few extra
characters.

PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
The net result of this situation is that those extra characters will not
be properly encoded, and will be received at the other end of the
XML-RPC tranmission as “garbled data”. Unfortunately the library cannot
provide real support for CP1252 because of limitations in the PHP 4 xml
parser. Luckily, we tried our best to support this character set anyway,
and, since version 2.2.1, there is some form of support, left commented
in the code.

To properly encode outgoing data that is natively in CP1252, you
will have to uncomment all relative code in the file
xmlrpc.inc (you can search for the string “1252”),
then set $GLOBALS['xmlrpc_internalencoding']='CP1252';
Please note that all incoming data will then be fed to your application
as UTF-8 to avoid any potentail data loss.

Does the library support using cookies / http sessions?

In short: yes, but a little coding is needed to make it
happen.

The code below uses sessions to e.g. let the client store a value
on the server and retrieve it later.

$resp = $client->send(new xmlrpcmsg(‘registervalue’, array(new xmlrpcval(‘foo’), new xmlrpcval(‘bar’))));
if (!$resp->faultCode())
{
$cookies = $resp->cookies();
if (array_key_exists(‘PHPSESSID’, $cookies)) // nb: make sure to use the correct session cookie name
{
$session_id = $cookies[‘PHPSESSID’][‘value’];

// do some other stuff here…

$client->setcookie(‘PHPSESSID’, $session_id);
$val = $client->send(new xmlrpcmsg(‘getvalue’, array(new xmlrpcval(‘foo’)));
}
}
Server-side sessions are handled normally like in any other
php application. Please see the php manual for more information about
sessions.

NB: unlike web browsers, not all xmlrpc clients support usage of
http cookies. If you have troubles with sessions and control only the
server side of the communication, please check with the makers of the
xmlrpc client in use.

Integration with the PHP xmlrpc extension

To be documented more…

In short: for the fastest execution possible, you can enable the php
native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
following code snippet gives an example of such integration

/*** client side ***/
$c = new xmlrpc_client(‘http://phpxmlrpc.sourceforge.net/server.php&#8217;);

// tell the client to return raw xml as response value
$c->return_type = ‘xml’;

// let the native xmlrpc extension take care of encoding request parameters
$r = $c->send(xmlrpc_encode_request(‘examples.getStateName’, $_POST[‘stateno’]));

if ($r->faultCode())
// HTTP transport error
echo ‘Got error ‘.$r->faultCode();
else
{
// HTTP request OK, but XML returned from server not parsed yet
$v = xmlrpc_decode($r->value());
// check if we got a valid xmlrpc response from server
if ($v === NULL)
echo ‘Got invalid response’;
else
// check if server sent a fault response
if (xmlrpc_is_fault($v))
echo ‘Got xmlrpc fault ‘.$v[‘faultCode’];
else
echo’Got response: ‘.htmlentities($v);
}

Substitution of the PHP xmlrpc extension

Yet another interesting situation is when you are using a ready-made
php application, that provides support for the XMLRPC protocol via the
native php xmlrpc extension, but the extension is not available on your
php install (e.g. because of shared hosting constraints).

Since version 2.1, the PHP-XMLRPC library provides a compatibility
layer that aims to be 100% compliant with the xmlrpc extension API. This
means that any code written to run on the extension should obtain the
exact same results, albeit using more resources and a longer processing
time, using the PHP-XMLRPC library and the extension compatibility module.
The module is part of the EXTRAS package, available as a separate download
from the sourceforge.net website, since version 0.2

‘Enough of xmlrpcvals!’: new style library usage

To be documented…

In the meantime, see docs about xmlrpc_client::return_type and
xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
php_xmlrpc_decode and php_xmlrpc_decode_xml

Usage of the debugger

A webservice debugger is included in the library to help during
development and testing.

The interface should be self-explicative enough to need little
documentation.

The most useful feature of the debugger is without doubt the “Show
debug info” option. It allows to have a screen dump of the complete http
communication between client and server, including the http headers as
well as the request and response payloads, and is invaluable when
troubleshooting problems with charset encoding, authentication or http
compression.

The debugger can take advantage of the JSONRPC library extension, to
allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
visual editor to allow easy mouse-driven construction of the payload for
remote methods. Both components have to be downloaded separately from the
sourceforge.net web pages and copied to the debugger directory to enable
the extra functionality:

to enable jsonrpc functionality, download the PHP-XMLRPC
EXTRAS package, and copy the file jsonrpc.inc
either to the same directory as the debugger or somewhere in your
php include path

to enable the visual value editing dialog, download the
JS-XMLRPC library, and copy somewhere in the web root files
visualeditor.php,
visualeditor.css and the folders
yui and img. Then edit the
debugger file controller.php and set
appropriately the variable $editorpath.

Advertisements