3123 lines
109 KiB
Plaintext
3123 lines
109 KiB
Plaintext
= XML-RPC for PHP
|
|
:revision: 4.0.0
|
|
:keywords: xmlrpc, ,xml, rpc, webservices, http
|
|
:toc: left
|
|
:imagesdir: images
|
|
:source-highlighter: highlightjs
|
|
|
|
|
|
[preface]
|
|
== Introduction
|
|
|
|
NB: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4.
|
|
DO NOT USE FOR NOW.
|
|
|
|
XML-RPC is a format devised by link:$$http://www.userland.com/$$[Userland Software] for achieving
|
|
remote procedure call via XML using HTTP as the transport. XML-RPC has its
|
|
own web site, link:$$http://www.xmlrpc.com/$$[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 link:$$http://usefulinc.com/$$[Useful Information Company]. As of the
|
|
1.0 stable release, the project was opened to wider involvement and moved
|
|
to link:$$http://phpxmlrpc.sourceforge.net/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github]
|
|
|
|
A list of XML-RPC implementations for other languages such as Perl
|
|
and Python can be found on the link:$$http://www.xmlrpc.com/$$[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
|
|
|
|
{empty}S. Kuip
|
|
|
|
{empty}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
|
|
|
|
|
|
[[requirements]]
|
|
== 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.3.
|
|
|
|
If you wish to use HTTPS 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.
|
|
|
|
|
|
[[manifest]]
|
|
== 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.php::
|
|
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.xml, demo/demo2.xml, demo/demo3.xml::
|
|
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 <<jellyfish>> 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 link:$$http://pear.php.net/package/PHPUnit$$[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 link:$$http://www.xmlrpc.com/discuss/msgReader$853$$[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."
|
|
|
|
|
|
[[bugs]]
|
|
|
|
== 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 <<iso8601encode>> and <<iso8601decode>> 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 <<xmlrpc-defencoding>>
|
|
|
|
Support for receiving from servers version 1 cookies (i.e.
|
|
conforming to RFC 2965) is quite incomplete, and might cause unforeseen
|
|
errors.
|
|
|
|
|
|
[[support]]
|
|
|
|
== 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 link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc].
|
|
Bugs, feature requests and patches can be posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].
|
|
|
|
* The __PHP XML-RPC interest mailing list__ is
|
|
run by the author. More details link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].
|
|
|
|
* For more general XML-RPC questions, there is a Yahoo! Groups
|
|
link:$$http://groups.yahoo.com/group/xml-rpc/$$[XML-RPC mailing list].
|
|
|
|
* The link:$$http://www.xmlrpc.com/discuss$$[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.
|
|
|
|
[[jellyfish]]
|
|
|
|
=== The Jellyfish Book
|
|
|
|
image::progxmlrpc.s.gif[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 link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[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
|
|
link:$$http://meerkat.oreillynet.com/$$[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!
|
|
|
|
|
|
[[apidocs]]
|
|
|
|
== Class documentation
|
|
|
|
[[xmlrpcval]]
|
|
|
|
=== 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 link:$$http://www.xmlrpc.com/stories/storyReader$7$$[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 link:$$http://www.xmlrpc.com/spec$$[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 link:$$http://www.w3.org/TR/REC-xml#syntax$$[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 ...).
|
|
|
|
[[xmlrpcval-creation]]
|
|
|
|
==== 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:
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$myInt = new xmlrpcval(1267, "int");
|
|
$myString = new xmlrpcval("Hello, World!", "string");
|
|
$myBool = new xmlrpcval(1, "boolean");
|
|
$myString2 = new xmlrpcval(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:
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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.
|
|
|
|
[[xmlrpcval-methods]]
|
|
|
|
==== Methods
|
|
|
|
===== addScalar
|
|
|
|
int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $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
|
|
|
|
intaddArrayarray$arrayValThe 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
|
|
|
|
int addStructarray$assocArrayValThe 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
|
|
|
|
string kindOf Returns a string containing "struct", "array" or "scalar"
|
|
describing the base type of the value. If it returns "undef" it
|
|
means that the value hasn't been initialised.
|
|
|
|
===== serialize
|
|
|
|
string serialize Returns a string containing the XML-RPC representation of this
|
|
value.
|
|
|
|
|
|
===== scalarVal
|
|
|
|
mixed scalarVal If $val->kindOf() == "scalar", this
|
|
method returns the actual PHP-language value of the scalar (base 64
|
|
decoding is automatically handled here).
|
|
|
|
===== scalarTyp
|
|
|
|
string scalarTyp 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
|
|
|
|
xmlrpcval arrayMem 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.
|
|
|
|
[source, php]
|
|
----
|
|
|
|
// 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
|
|
|
|
int arraySize If $val is an
|
|
array, returns the number of elements in that
|
|
array.
|
|
|
|
===== structMem
|
|
|
|
xmlrpcval structMem 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
|
|
|
|
array structEach Returns the next (key, value) pair from the struct, when
|
|
$val is a struct.
|
|
$value is an xmlrpcval itself. See also <<structreset>>.
|
|
|
|
[source, php]
|
|
----
|
|
|
|
// 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]]
|
|
|
|
===== structReset
|
|
|
|
void structReset Resets the internal pointer for
|
|
structEach() to the beginning of the struct,
|
|
where $val is a struct.
|
|
|
|
[[structmemexists]]
|
|
|
|
===== structMemExists
|
|
|
|
bool structMemExsists string $memberName Returns TRUE or
|
|
FALSE depending on whether a member of the
|
|
given name exists in the struct.
|
|
|
|
[[xmlrpcmsg]]
|
|
|
|
=== 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 <<xmlrpc-client-send>>).
|
|
|
|
==== Creation
|
|
|
|
The constructor takes the following forms:
|
|
|
|
xmlrpcmsgnew
|
|
xmlrpcmsgstring$methodNamearray$parameterArraynullWhere 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:
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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 <<xmlrpcval>>.
|
|
|
|
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
|
|
|
|
bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval
|
|
xmlrpcVal to the parameter list for this
|
|
method call. Returns TRUE or FALSE on error.
|
|
|
|
===== getNumParams
|
|
|
|
int getNumParams Returns the number of parameters attached to this
|
|
message.
|
|
|
|
===== getParam
|
|
|
|
xmlrpcval getParam 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
|
|
|
|
string method string method string $methNameGets or sets the method contained in the XML-RPC
|
|
message.
|
|
|
|
===== parseResponse
|
|
|
|
xmlrpcresp parseResponsestring $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 <<xmlrpc-client-send>>).
|
|
|
|
This method processes any HTTP/MIME headers it finds.
|
|
|
|
===== parseResponseFile
|
|
|
|
xmlrpcresp parseResponseFile file handle
|
|
resource$fileHandleGiven 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.xml, demo2.xml, demo3.xml++
|
|
in this distribution). It processes any HTTP headers it finds, and
|
|
does not close the file handle.
|
|
|
|
===== serialize
|
|
|
|
string
|
|
serializeReturns the an XML string representing the XML-RPC
|
|
message.
|
|
|
|
[[xmlrpc-client]]
|
|
|
|
=== 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_clientstring$server_urlxmlrpc_clientnew
|
|
xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
|
|
$another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
|
|
|
|
----
|
|
|
|
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__:
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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 <<xmlrpc-client-send>> 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.
|
|
|
|
[[xmlrpc-client-send]]
|
|
|
|
===== send
|
|
|
|
This method takes the forms:
|
|
|
|
xmlrpcresp send xmlrpcmsg $xmlrpc_message int $timeout string $transport array sendarray $xmlrpc_messages int $timeout string $transportxmlrpcrespsendstring$xml_payloadint$timeoutstring$transportWhere xmlrpc_message is an instance of
|
|
xmlrpcmsg (see <<xmlrpcmsg>>),
|
|
and response is an instance of
|
|
xmlrpcresp (see <<xmlrpcresp>>).
|
|
|
|
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 link:$$http://www.php.net/xmlrpc$$[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.
|
|
|
|
In addition to low-level errors, the XML-RPC server you were
|
|
querying may return an error in the
|
|
xmlrpcresp object. See <<xmlrpcresp>> for details of how to handle these
|
|
errors.
|
|
|
|
[[multicall]]
|
|
|
|
===== multiCall
|
|
|
|
This method takes the form:
|
|
|
|
array multiCall 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 <<xmlrpcmsg>>), and response is an
|
|
array of xmlrpcresp objects (see <<xmlrpcresp>>).
|
|
|
|
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
|
|
|
|
void setAcceptedCompression 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
|
|
|
|
voidsetCaCertificatestring$certificatebool$is_dirThis 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
|
|
|
|
voidsetCertificatestring$certificatestring$passphraseThis 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
|
|
|
|
void setCookiestring $name string $value string $path string $domain int $portThis 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
|
|
|
|
voidsetCredentialsstring$usernamestring$passwordint$authtypeThis 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
|
|
|
|
voidsetCurlOptionsarray$optionsThis 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
|
|
|
|
void setDebugint$debugLvldebugLvl 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
|
|
|
|
voidsetKeyint$keyint$keypassThis 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
|
|
|
|
voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis 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
|
|
|
|
voidsetRequestCompressionstring$compressionmethodThis 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
|
|
|
|
voidsetSSLVerifyHostint$iThis 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
|
|
|
|
voidsetSSLVerifyPeerbool$iThis 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
|
|
|
|
voidUseragentstring$useragentThis 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]]
|
|
|
|
===== 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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
|
|
$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]]
|
|
|
|
=== 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
|
|
xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew
|
|
xmlrpcresp0int$errcodestring$err_stringThe 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 <<xmlrpc-server>> for more information on passing error
|
|
codes.
|
|
|
|
|
|
==== Methods
|
|
|
|
|
|
===== faultCode
|
|
|
|
intfaultCodeReturns the integer fault code return from the XML-RPC
|
|
response. A zero value indicates success, any other value indicates
|
|
a failure response.
|
|
|
|
|
|
===== faultString
|
|
|
|
stringfaultStringReturns the human readable explanation of the fault indicated
|
|
by $resp->faultCode().
|
|
|
|
|
|
===== value
|
|
|
|
xmlrpcvalvalueReturns 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
|
|
|
|
stringserializeReturns an XML string representation of the response (xml
|
|
prologue not included).
|
|
|
|
[[xmlrpc-server]]
|
|
|
|
=== 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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
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 <<signatures>>) 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.
|
|
|
|
[[signatures]]
|
|
|
|
==== 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
|
|
[source, php]
|
|
----
|
|
string examples.getStateName(int)
|
|
|
|
----
|
|
|
|
has the signature
|
|
[source, php]
|
|
----
|
|
array($xmlrpcString, $xmlrpcInt)
|
|
|
|
----
|
|
|
|
and, assuming that it is the only possible signature for the
|
|
method, it might be used like this in server creation:
|
|
[source, php]
|
|
----
|
|
|
|
$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':
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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:
|
|
[source, php]
|
|
----
|
|
|
|
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.
|
|
|
|
|
|
[[globalvars]]
|
|
|
|
== 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
|
|
|
|
$xmlrpcerruser800The 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:
|
|
[source, php]
|
|
----
|
|
|
|
$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
|
|
|
|
$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:
|
|
|
|
[source, php]
|
|
----
|
|
|
|
<?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.
|
|
|
|
|
|
[[helpers]]
|
|
|
|
== 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:
|
|
|
|
[quote]
|
|
____
|
|
[[wrap_xmlrpc_method]]
|
|
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 link:$$http://www.uic.edu/year2000/datefmt.html$$[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.
|
|
|
|
[[iso8601encode]]
|
|
|
|
==== iso8601_encode
|
|
|
|
stringiso8601_encodestring$time_tint$utc0Returns 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.
|
|
|
|
[[iso8601decode]]
|
|
|
|
==== iso8601_decode
|
|
|
|
intiso8601_decodestring$isoStringint$utc0Returns 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.
|
|
|
|
[[arrayuse]]
|
|
|
|
=== 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__.
|
|
|
|
[[phpxmlrpcdecode]]
|
|
|
|
==== php_xmlrpc_decode
|
|
|
|
mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns 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:
|
|
[source, php]
|
|
----
|
|
|
|
// 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" => ...
|
|
)));
|
|
|
|
----
|
|
|
|
[[phpxmlrpcencode]]
|
|
|
|
==== php_xmlrpc_encode
|
|
|
|
xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns 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:
|
|
[source, php]
|
|
----
|
|
|
|
// 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_xmlstring$xmlarray$optionsDecodes 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:
|
|
[source, php]
|
|
----
|
|
|
|
$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_optionsstringwrap_xmlrpc_method$client$methodname$signum$timeout$protocol$funcnameGiven 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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
|
|
|
|
$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]]
|
|
|
|
==== wrap_php_function
|
|
|
|
arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven 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: 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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
/**
|
|
* 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);
|
|
|
|
----
|
|
|
|
[[deprecated]]
|
|
|
|
=== 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:
|
|
|
|
[[xmlrpcdecode]]
|
|
|
|
==== xmlrpc_decode
|
|
|
|
mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.
|
|
|
|
[[xmlrpcencode]]
|
|
|
|
==== xmlrpc_encode
|
|
|
|
xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.
|
|
|
|
[[debugging]]
|
|
|
|
=== Debugging aids
|
|
|
|
==== xmlrpc_debugmsg
|
|
|
|
void xmlrpc_debugmsgstring$debugstringSends 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]]
|
|
|
|
== 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.
|
|
|
|
[[sysmethodsig]]
|
|
|
|
=== 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:
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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.
|
|
|
|
[[sysmethhelp]]
|
|
|
|
=== 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]]
|
|
|
|
== Examples
|
|
|
|
The best examples are to be found in the sample files included with
|
|
the distribution. Some are included here.
|
|
|
|
[[statename]]
|
|
|
|
=== 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
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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...
|
|
|
|
|
|
[[faq]]
|
|
|
|
[qanda]
|
|
== Frequently Asked Questions
|
|
|
|
=== Hi
|
|
|
|
==== 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.
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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:
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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 transmission 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 potential 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.
|
|
|
|
[source, php]
|
|
----
|
|
|
|
$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]]
|
|
|
|
[appendix]
|
|
== 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
|
|
|
|
|
|
[source, php]
|
|
----
|
|
|
|
/*** client side ***/
|
|
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
|
|
|
|
// 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]]
|
|
|
|
[appendix]
|
|
== 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]]
|
|
|
|
[appendix]
|
|
== '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
|
|
|
|
|
|
[[debugger]]
|
|
|
|
[appendix]
|
|
== 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.
|
|
|
|
image::debugger.gif[,,,,align="center"]
|
|
|
|
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.
|
|
|
|
|
|
[[news]]
|
|
|
|
[appendix]
|
|
== Whats'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 phpdoc form.
|
|
|
|
=== 4.0.0
|
|
|
|
...to be documented...
|
|
|
|
=== 3.0.0
|
|
|
|
__Note:__ this is the last release of the library that will support PHP 5.1 and up.
|
|
Future releases will target php 5.3 as minimum supported version.
|
|
|
|
* when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)
|
|
|
|
* omit port on http 'Host' header if it is 80
|
|
|
|
* test suite allows interrogating https servers ignoring their certs
|
|
|
|
* method setAcceptedCompression was failing to disable reception of compressed responses if the
|
|
client supported them
|
|
|
|
=== 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 is 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,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.php$$__. 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...
|
|
|
|
* 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
|
|
|
|
++++++++++++++++++++++++++++++++++++++
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:2
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
sgml-namecase-general:t
|
|
sgml-general-insert-case:lower
|
|
End:
|
|
-->
|
|
++++++++++++++++++++++++++++++++++++++
|