* PHP 5.3.0 or later
-* the php "curl" extension is needed if you wish to use SSL or HTTP 1.1 to communicate with remote servers
+* the php "curl" extension is needed if you wish to use HTTPS, HTTP2, HTTP 1.1 or NTLM Auth to communicate with remote
+ servers
-The php "xmlrpc" native extension is not required, but if it is installed, there will be no interference with the
-operation of this library.
+* the php "mbstring" extension is not required, but when installed it allows reception of requests/responses in character
+ sets other than ASCII,LATIN-1,UTF-8.
+* the php "zlib" extension is not required, but when installed it allows sending compressed requests and receiving
+ compressed responses even without the "curl" extension
+
+* the php "xmlrpc" native extension is not required, but if it is installed, there will be no interference with the
+ operation of this library.
Installation instructions
-------------------------
Installation of the library is quite easy:
-1. Via Composer (highly recommended):
+1. Via Composer (highly recommended)
1. Install composer if you don't have it already present on your system.
Depending on how you install, you may end up with a composer.phar file in your directory.
4. Write your code.
Once Composer has downloaded the component(s), all you need to do is include the vendor/autoload.php file that
- was generated by Composer. This file takes care of autoloading all of the libraries so that you can use them
+ was generated by Composer. This file takes care of autoloading all the libraries so that you can use them
immediately, including phpxmlrpc:
// File example: src/script.php
as leaving it open to access means that any visitor can trigger execution of php code such as
the built-in debugger.
+ Tip: to reduce the size of the download, the demo files are not part of the default package installed with Composer.
+ You can either check them out online at https://github.com/gggeek/phpxmlrpc/tree/master/demo, or make sure they are
+ available locally, by installing the library using Composer option `--prefer-install=source`.
+
2. Via manual download and autoload configuration
- 1. copy the contents of the src/ folder to any location required by your
+ 1. download the zip or tarball version of the phpxmlrpc library from GitHub and unzip it in a temporary folder
+
+ 2. copy the contents of the extracted src/ folder to any location required by your
application (it can be inside the web server root or not).
- 2. configure your app autoloading mechanism so that all classes in the PhpXmlRpc namespace are loaded
+ 3. configure your app's autoloading mechanism so that all classes in the PhpXmlRpc namespace are loaded
from that location: any PSR-4 compliant autoloader can do that, if you don't have any there is one
available in src/Autoloader.php
- 3. Write your code.
+ 4. Write your code.
// File example: script.php
$client = new Client('http://some/server');
$response = $client->send(new Request('method', array(new Value('parameter'))));
- 4. IMPORTANT! Make sure that the phpxmlrpc directory is not directly accessible from the internet,
+ 5. IMPORTANT! Make sure that the phpxmlrpc root directory is not directly accessible from the internet,
as leaving it open to access means that any visitor can trigger execution of php code such as
the built-in debugger.
-
-Tips
-----
-
-* Please note that usage of the 'pake' command is not required for installation of the library.
- At this moment it is only useful to build the html and pdf versions of the documentation.
==== Sending multiple requests
-@TODO...
+Both the Client and Server classes provided by the library support the multicall xmlrpc extension, which allows to execute
+multiple xml-rpc requests with a single http call, by wrapping them up in a call to the `system.multiCall` method.
+
+The expected advantage is a nice improvements in performances, especially when there are many small requests at play, but,
+as always, the devil is in the details: the multicall specification does not mandate for the server to execute the
+single requests within the multicall method in a specific order, nor how to handle execution errors happening halfway
+through the list.
+
+The phpxmlrpc server will execute all the requests sequentially, in the same order in which they appear in the xml payload,
+and will try its best to execute them all, even if one of them fails, but there is no guarantee on the latter point.
+
+In order to take advantage of multicall, either use the Client's `multicall` method, or just pass an array of Request to
+the `send` method:
+
+----
+$m1 = new PhpXmlRpc\Request('system.methodHelp');
+$m2 = new PhpXmlRpc\Request('system.methodSignature');
+$val = new PhpXmlRpc\Value('an-xmlrpc-method', "string");
+$m1->addParam($val);
+$m2->addParam($val);
+$ms = array($m1, $m2);
+$rs = $client->multicall($ms);
+foreach($rs as $resp) {
+ var_dump($rs->faultCode());
+ var_dump($rs->value());
+}
+----
+
+Please note that, in case of faults during execution of a multicall call, the Client will automatically fail back to
+sending every request separately, one at a time. If you are sure that the server supports the multicall protocol, you
+might want to optimize and avoid this second attempt by passing `false` as 4th argument to `multicall()`.
+
+If, on the other hand, after writing code which uses the `multicall` method, you are forced to migrate to a server which
+does not support the `system.multiCall` method, you can simply set `$client->no_multicall = true`
=== Server [[server]]
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'.
+* `parameters_type` - this entry can be used when the server is working in 'xmlrpcvals' mode (see <<method_handlers>>)
+ 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'.
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).
+by the server, and should not be reimplemented (see <<reserved>> below).
==== Method signatures [[signatures]]
));
----
-==== Method handler functions
+==== Method handler functions [[method_handlers]]
The same php function can be registered as handler of multiple xml-rpc methods.
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 settings have been
set in `php.ini`, namely `display_errors`. Another way to prevent echoing of errors inside the response and
-facilitate debugging is to use the server's `SetDebug` method with debug level 3 (see ...).
+facilitate debugging is to use the server's `SetDebug` method with debug level 3 (see <<setdebug>>).
Exceptions thrown during execution of handler functions are caught by default and an XML-RPC error response is generated
-instead. This behaviour can be fine-tuned by usage of the `$exception_handling` server property (see ...).
+instead. This behaviour can be fine-tuned by usage of the `$exception_handling` server property (see <<exception_handling>>).
===== Manual type conversion
A couple of methods / class properties 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()
+===== setDebug() [[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,
Note that the ZLIB php extension must be installed for this to work. If it is, `$compress_response` will default to TRUE.
-===== $exception_handling
+===== $exception_handling [[exception_handling]]
This property 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 returns an 'internal error'
$srv = new Server($methods);
----
-== Performances
+== Performances [[performances]]
Although the library is not designed to be the most memory-efficient nor the most fast possible implementation of the
xml-rpc protocol, care is taken not to introduce unnecessary bloat.
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 Value objects, at least in the decoding phase, and have the server (or client) object
return to the calling function directly php values (see `Client::return_type` and `Server::functions_parameters_types`
-for more details, and the tips in the "performance" section TODO add link...).
+for more details, and the tips in the <<performances>> section.
=== My server (client) returns an error whenever the client (server) returns accented characters
=== 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:
git://git.onelab.eu / plcapi.git / commitdiff