2334 lines
86 KiB
Plaintext
2334 lines
86 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
|
|
|
|
WARNING: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4. *DO NOT USE* FOR NOW. You can find the API documentation at link:$$http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html$$[http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html]
|
|
|
|
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]
|
|
|
|
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]
|
|
|
|
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 flexibility 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, or to use NTLM authentication, you need the
|
|
*curl* extension compiled into your PHP installation.
|
|
|
|
If you wish to receive XML-RPC requests or responses in any other character set than US-ASCII, ISO-8859-1 or UTF-8, you
|
|
will need the *mbstring* 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
|
|
|
|
debugger/*:: a graphical debugger which can be used to test calls to xmlrpc servers
|
|
|
|
demo/*:: example code for implementing both xmlrpc client and server functionality
|
|
|
|
doc/*:: the documentation/ this manual, and the list of API changes between versions 3 and 4
|
|
|
|
extras/rsakey.pem:: A test certificate key for the SSL support, which can be used to generate dummy certificates. It has
|
|
the passphrase "test."
|
|
|
|
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.]
|
|
|
|
lib/*:: a compatibility layer for applications which still rely on version 3 of the API
|
|
|
|
src/*:: the XML-RPC library classes. You can autoload these via Composer, or via a dedicated Autoloader class
|
|
|
|
tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it on Travis
|
|
|
|
|
|
[[bugs]]
|
|
|
|
== Known Bugs
|
|
|
|
Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]
|
|
|
|
== Known limitations
|
|
|
|
This started out as a bare framework. Many "nice" bits have been put in over time, but backwards compatibility has
|
|
always taken precedence over API cleanups. As such, you might find some API choices questionable.
|
|
|
|
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 PhpXmlRpc\Helper\Date class 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.
|
|
|
|
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.
|
|
|
|
* 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 original author. More details
|
|
link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].
|
|
|
|
|
|
[[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
|
|
|
|
|
|
==== 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.
|
|
|
|
The type i8 on the other hand is considered as a separate type.
|
|
Note that the library will never output integers as 'i8' on its own,
|
|
even when php is compiled in 64-bit mode.
|
|
|
|
===== 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 < > ' " and
|
|
& All other characters outside of the ASCII range are
|
|
encoded using their character reference representation (e.g.
|
|
È 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]]
|
|
|
|
==== Xmlrpcval 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.
|
|
|
|
[[xmlrpc-client]]
|
|
|
|
==== Xmlrpc-client 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.
|
|
|
|
|
|
[[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, $xmlrpcI8 $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";
|
|
$xmlrpcI8="i8";
|
|
$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
|
|
|
|
==== 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 '<' 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
|
|
|
|
CAUTION: 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
|
|
|
|
* new: introduction of namespaces and full OOP.
|
|
+
|
|
All php classes have been renamed and moved to separate files.
|
|
+
|
|
Class autoloading can now be done in accord with the PSR-4 standard.
|
|
+
|
|
All global variables and global functions have been removed.
|
|
+
|
|
Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
|
|
+
|
|
Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
|
|
For more details, head on to doc/api_changes_v4.md
|
|
|
|
* changed: the default character encoding delivered from the library to your code is now utf8.
|
|
It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
|
|
|
|
* improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
|
|
This only works when the mbstring php extension is enabled.
|
|
|
|
* improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
|
|
with recent curl builds
|
|
|
|
* improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`
|
|
|
|
* improved: a specific option allows users to decide the version of SSL to use for https calls.
|
|
This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
|
|
and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)
|
|
|
|
* improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)
|
|
|
|
* improved: all _wrap_something()_ functions now return a closure by default instead of a function name
|
|
|
|
* improved: debug messages are not html-escaped any more when executing from the command line
|
|
|
|
* improved: the library is now tested using Travis ( https://travis-ci.org/ ).
|
|
Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
|
|
is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services
|
|
|
|
* improved: phpunit is now installed via composer, not bundled anymore
|
|
|
|
* improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for
|
|
|
|
* improved: the test suite has basic checks for the debugger and demo files
|
|
|
|
* improved: more tests in the test suite
|
|
|
|
* fixed: the server would not reset the user-set debug messages between subsequent `service()` calls
|
|
|
|
* fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
|
|
exception_handling set to 2
|
|
|
|
* fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
|
|
prolog only
|
|
|
|
* fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
|
|
prolog only
|
|
|
|
* fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog
|
|
|
|
* fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name
|
|
|
|
* fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
|
|
It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name
|
|
|
|
* fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
|
|
or undefined parameters
|
|
|
|
* fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
|
|
signatures
|
|
|
|
* improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service
|
|
|
|
* improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
|
|
previously those messages would just disappear (this is visible e.g. in the debugger)
|
|
|
|
* changed: debug info handling
|
|
- at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
|
|
- at debug level 1, curl communication info are not dumped to screen
|
|
- at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads
|
|
|
|
* improved: makefiles have been replaced with a php_based pakefile
|
|
|
|
* improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
|
|
with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
|
|
to look at than previous versions
|
|
|
|
* improved: all php code is now formatted according to the PSR-2 standard
|
|
|
|
=== 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 ofreceived 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 files: _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:
|
|
-->
|
|
++++++++++++++++++++++++++++++++++++++
|