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]
+ link:$$https://sourceforge.net/projects/phpxmlrpc/$$[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
Daniel Krippner
-{empty}S. Kuip
+S. Kuip
-{empty}A. Lambert
+A. Lambert
Frederic Lecointre
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
+doc/*:: the documentation, including this manual, and the list of API changes between versions 3 and 4
-extras/test.pl, extras/test.py:: Perl and Python programs to exercise server.php to test that some of the methods work.
+extras/*:: php utility scripts, such as a benchmark suite and an evironment compatibility checker
lib/*:: a compatibility layer for applications which still rely on version 3 of the API
[[bugs]]
-
== Known Bugs
Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]
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
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].
+ link:$$https://lists.usefulinc.com/cgi-bin/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.]
+Complete details of the book are link:$$https://www.oreilly.com/library/view/programming-web-services/0596001193/$$[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
+ the (now discontinued) O'Reilly's Meerkat service in order to allow commenting on news stories
from around the Web.
If you've benefited from the effort that has been put into writing this software, then please consider buying the book!
[[apidocs]]
-
== Class documentation
-
==== Notes on types
===== int
them, and uses the same encoding convention (see ...).
[[xmlrpcval-creation]]
-
==== Xmlrpcval creation
The constructor is the normal way to create an
[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
[source, php]
----
-
$myArray = new xmlrpcval(
array(
new xmlrpcval("Tom"),
"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:
[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
[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).
+ HTTPS.
The transport parameter is optional, and
if omitted will default to 'http'. Allowed values are either
[source, php]
----
-
function foo ($xmlrpcmsg) {
...
return new xmlrpcresp($some_xmlrpc_val);
"examples.myFunc1" => array("function" => "foo"),
"examples.myFunc2" => array("function" => "bar::foobar"),
));
-
----
This performs everything you need to do with a server. The single
[source, php]
----
-
function foo ($xmlrpcmsg) {
global $xmlrpcerruser; // import user errcode base value
return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
}
}
-
----
See __server.php__ in this distribution for
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
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
"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.
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';
"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,
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
[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
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
words:
[source, php]
----
-
function foo($usr_id, $out_lang='en') {
global $xmlrpcerruser;
), false);
$s->functions_parameters_type = 'phpvals';
$s->service();
-
----
There are a few things to keep in mind when using this
[[globalvars]]
-
== Global variables
Many global variables are defined in the xmlrpc.inc file. Some of
been encoded as global variables:
[source, php]
----
-
$xmlrpcI4="i4";
$xmlrpcI8="i8";
$xmlrpcInt="int";
$xmlrpcStruct="struct";
$xmlrpcValue="undefined";
$xmlrpcNull="null";
-
----
==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities
=== Variables whose value can be modified
[[xmlrpc-defencoding]]
-
==== xmlrpc_defencoding
$xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
[source, php]
----
-
<?php
include('xmlrpc.inc');
$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
$v = new xmlrpcval('κόÏ\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
-
----
==== xmlrpcName
[[helpers]]
-
== Helper functions
XML-RPC for PHP contains some helper functions which you can use to
representations: CCYYMMDDTHH:MM:SS.
[[iso8601encode]]
-
==== iso8601_encode
stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
includes a demonstration of this function.
[[iso8601decode]]
-
==== iso8601_decode
intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
local timestamp.
[[arrayuse]]
-
=== Easy use with nested PHP values
Dan Libby was kind enough to contribute two helper functions that
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
Example:
[source, php]
----
-
// wrapper to expose an existing php function as xmlrpc method handler
function foo_wrapper($m)
{
"function" => "foo_wrapper",
"signatures" => ...
)));
-
----
[[phpxmlrpcencode]]
-
==== php_xmlrpc_encode
xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
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,
'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
'fourth: a datetime' => '20060107T01:53:00'
), array('auto_dates'));
-
----
==== php_xmlrpc_decode_xml
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)
[source, php]
----
-
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
$function = wrap_xmlrpc_method($client, 'examples.getStateName');
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'
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
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
[[reserved]]
-
== Reserved methods
In order to extend the functionality offered by XML-RPC servers
a method implemented by the server.
[[sysmethodsig]]
-
=== system.methodSignature
This method takes one parameter, the name of a method implemented
[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
[[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
[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);
print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
"Reason: '" . htmlentities($r->faultString()) . "'<BR>";
}
-
----
=== Executing a multicall call
[[faq]]
-[qanda]
+[[qanda]]
== Frequently Asked Questions
==== How to send custom XML as payload of a method call::
[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
[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
[source, php]
----
-
$resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
if (!$resp->faultCode())
{
$val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
}
}
-
----
Server-side sessions are handled normally like in any other
[[integration]]
-
[appendix]
== Integration with the PHP xmlrpc extension
[source, php]
----
-
/*** client side ***/
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
else
echo'Got response: '.htmlentities($v);
}
-
----
-
[[substitution]]
-
[appendix]
== Substitution of the PHP xmlrpc extension
[[enough]]
-
[appendix]
== 'Enough of xmlrpcvals!': new style library usage
[[debugger]]
-
[appendix]
== Usage of the debugger
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__,
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
git://git.onelab.eu / plcapi.git / commitdiff