"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
PHP-XMLRPC User manual
-$Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $
-->
<book lang="en">
<title>XML-RPC for PHP</title>
- <subtitle>version 2.2.2</subtitle>
+ <subtitle>version 3.0.0</subtitle>
<bookinfo>
- <date>XXX YY, 2008</date>
+ <date>June 15, 2014</date>
<authorgroup>
<author>
<para>The original author is Edd Dumbill of <ulink
url="http://usefulinc.com/">Useful Information Company</ulink>. As of the
- 1.0 stable release, the project has been opened to wider involvement and
- moved to <ulink
- url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>.</para>
+ 1.0 stable release, the project was opened to wider involvement and moved
+ to <ulink
+ url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>; later, to <ulink
+ url="https://github.com/">Github</ulink></para>
<para>A list of XML-RPC implementations for other languages such as Perl
and Python can be found on the <ulink
<para>A. Lambert</para>
+ <para>Frederic Lecointre</para>
+
<para>Dan Libby</para>
<para>Arnaud Limbourg</para>
<para>Peter Russel</para>
+ <para>Jean-Jacques Sarton</para>
+
<para>Viliam Simko</para>
+ <para>Idan Sofer</para>
+
<para>Douglas Squirrel</para>
- <para>Idan Sofer</para>
+ <para>Heiko Stübner</para>
<para>Anatoly Techtonik</para>
+ <para>Tommaso Trani</para>
+
<para>Eric van der Vlist</para>
<para>Christian Wenz</para>
<para>Jim Winstead</para>
<para>Przemyslaw Wroblewski</para>
+
+ <para>Bruno Zanetti Melotti</para>
</sect1>
</chapter>
functions and methods please take a look at the source code of the
library, which is quite thoroughly commented in javadoc-like form.</para>
+ <sect1>
+ <title>3.0.0</title>
+
+ <para><emphasis>Note:</emphasis> 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.</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)</para>
+ </listitem>
+
+ <listitem>
+ <para>omit port on http 'Host' header if it is 80</para>
+ </listitem>
+
+ <listitem>
+ <para>test suite allows interrogating https servers ignoring their certs</para>
+ </listitem>
+
+ <listitem>
+ <para>method setAcceptedCompression was failing to disable reception of compressed responses if the
+ client supported them</para>
+ </listitem>
+
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>3.0.0 beta</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>improved: removed all usage of php functions deprecated in
+ php 5.3, usage of assign-by-ref when creating new objects
+ etc...</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: add support for the <ex:nil/> tag used by
+ the apache library, both in input and output</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: add support for <classname>dateTime</classname>
+ objects in both in <function>php_xmlrpc_encode</function> and as
+ parameter for constructor of
+ <classname>xmlrpcval</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>improved: add support for timestamps as parameter for
+ constructor of <classname>xmlrpcval</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>improved: add option 'dates_as_objects' to
+ <function>php_xmlrpc_decode</function> to return
+ <classname>dateTime</classname> objects for xmlrpc
+ datetimes</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: add new method
+ <methodname>SetCurlOptions</methodname> to
+ <classname>xmrlpc_client</classname> to allow extra flexibility in
+ tweaking http config, such as explicitly binding to an ip
+ address</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: add new method
+ <methodname>SetUserAgent</methodname> to
+ <classname>xmrlpc_client</classname> to to allow having different
+ user-agent http headers</para>
+ </listitem>
+
+ <listitem>
+ <para>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</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: allow servers in 'xmlrpcvals' mode to also
+ register plain php functions by defining them in the dispatch map
+ with an added option</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: catch exceptions thrown during execution of php
+ functions exposed as methods by the server</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: bad encoding if same object is encoded twice using
+ php_xmlrpc_encode</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
<sect1>
<title>2.2.2</title>
<para>The <function>wrap_php_function</function> and
<function>wrap_xmlrpc_method</function> functions have been moved
out of the base library file <filename>xmlrpc.inc</filename> into
- a file of their own: <filename>xmlrpc_wrappers.inc</filename>. You
+ a file of their own: <filename>xmlrpc_wrappers.php</filename>. You
will have to include() / require() it in your scripts if you have
been using those functions. For increased security, the automatic
rebuilding of php object instances out of received xmlrpc structs
<code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,
and has many caveats, with php being a typeless language and
all...</para>
-
- <para>With PHP versions lesser than 5.0.3 wrapping of php functions
- into xmlrpc methods is not supported yet.</para>
</listitem>
<listitem>
configuration.</para>
<para>The <emphasis>minimum supported</emphasis> PHP version is
- 4.2.</para>
-
- <para>A compatibility layer is provided that allows the code to run on PHP
- 4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest
- you upgrade as soon as possible.</para>
-
- <para>Automatic generation of xml-rpc methods from php functions is only
- supported with PHP version 5.0.3 and later (note that the lib will
- generate some warnings with PHP 5 in strict error reporting mode).</para>
+ 5.3.</para>
<para>If you wish to use SSL or HTTP 1.1 to communicate with remote
servers, you need the "curl" extension compiled into your PHP
- installation. This is available in PHP 4.0.2 and greater, although 4.0.6
- has a bug preventing SSL working, and versions prior to 4.3.8 do not
- support streamlining multiple requests using HTTP Keep-Alive.</para>
+ installation.</para>
<para>The "xmlrpc" native extension is not required to be compiled into
your PHP installation, but if it is, there will be no interference with
</glossentry>
<glossentry>
- <glossterm>lib/xmlrpc_wrappers.inc</glossterm>
+ <glossterm>lib/xmlrpc_wrappers.php</glossterm>
<glossdef>
<para>helper functions to "automagically" convert plain php
</glossdef>
</glossentry>
- <glossentry>
- <glossterm>lib/compat/array_key_exists.php, lib/compat/is_a.php,
- lib/compat/is_scalar.php, lib/compat/var_export.php,
- lib/compat/vesrions_compare.php</glossterm>
-
- <glossdef>
- <para>compatibility functions: these files implement the
- compatibility layer needed to run the library with PHP versions 4.0
- and 4.1</para>
- </glossdef>
- </glossentry>
-
<glossentry>
<glossterm>demo/server/proxy.php</glossterm>
</glossentry>
<glossentry>
- <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>
+ <glossterm>demo/demo1.xml, demo/demo2.xml, demo/demo3.xml</glossterm>
<glossdef>
<para>XML-RPC responses captured in a file for testing purposes (you
content will be parsed as if it had been encoded using the charset defined
by <xref linkend="xmlrpc-defencoding" /></para>
- <para>Very large floating point numbers are serialized using exponential
- notation, even though the spec explicitly forbids this behaviour. This
- will not be a problem if this library is used on both ends of the
- communication, but might cause problems with other implementations.</para>
-
<para>Support for receiving from servers version 1 cookies (i.e.
conforming to RFC 2965) is quite incomplete, and might cause unforeseen
errors.</para>
-
- <para>A PHP warning will be generated in many places when using
- <filename>xmlrpc.inc</filename> and <filename>xmlrpcs.inc</filename> with
- PHP 5 in strict error reporting mode. The simplest workaround to this
- problem is to lower the <parameter>error_reporting</parameter> level in
- php.ini.</para>
</chapter>
<chapter id="support">
<listitem>
<para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
on <ulink
- url="http://phpxmlrpc.sourceforge.net">phpxmlrpc.sourceforge.net</ulink>.
+ url="https://github.com/gggeek/phpxmlrpc">github.com/gggeek/phpxmlrpc</ulink>.
Bugs, feature requests and patches can be posted to the <ulink
- url="http://sourceforge.net/projects/phpxmlrpc">project's
+ url="https://github.com/gggeek/phpxmlrpc/issues">project's
website</ulink>.</para>
</listitem>
<para>The <classname>xmlrpcval</classname> class can store arbitrarily
complicated values using the following types: <literal>i4 int boolean
- string double dateTime.iso8601 base64 array struct</literal>. You should
- refer to the <ulink url="http://www.xmlrpc.com/spec">spec</ulink> for
- more information on what each of these types mean.</para>
+ string double dateTime.iso8601 base64 array struct</literal>
+ <literal>null</literal>. You should refer to the <ulink
+ url="http://www.xmlrpc.com/spec">spec</ulink> for more information on
+ what each of these types mean.</para>
<sect2>
<title>Notes on types</title>
representation has the advantage of producing XML that is valid
independently of the charset encoding assumed.</para>
</sect3>
+
+ <sect3>
+ <title>null</title>
+
+ <para>There is no support for encoding <literal>null</literal>
+ values in the XML-RPC spec, but at least a couple of extensions (and
+ many toolkits) do support it. Before using <literal>null</literal>
+ values in your messages, make sure that the responding party accepts
+ them, and uses the same encoding convention (see ...).</para>
+ </sect3>
</sect2>
<sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
second parameter must be a name of an XML-RPC type. Valid types are:
"<literal>int</literal>", "<literal>boolean</literal>",
"<literal>string</literal>", "<literal>double</literal>",
- "<literal>dateTime.iso8601</literal>",
- "<literal>base64</literal>".</para>
+ "<literal>dateTime.iso8601</literal>", "<literal>base64</literal>" or
+ "null".</para>
<para>Examples:</para>
<programlisting language="php">
-$myInt = new xmlrpcvalue(1267, "int");
-$myString = new xmlrpcvalue("Hello, World!", "string");
-$myBool = new xmlrpcvalue(1, "boolean");
-$myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
+$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
</programlisting>
<para>The fourth constructor form can be used to compose complex
array(
"street" => new xmlrpcval("Fifht Ave", "string"),
"city" => new xmlrpcval("NY", "string")
- ),
+ ),
"struct")
- ),
+ ),
"struct");
</programlisting>
<function>parseResponse.</function></para>
<para>This method is useful to construct responses from pre-prepared
- files (see files <literal>demo1.txt, demo2.txt, demo3.txt</literal>
+ files (see files <literal>demo1.xml, demo2.xml, demo3.xml</literal>
in this distribution). It processes any HTTP headers it finds, and
does not close the file handle.</para>
</sect3>
parameter.</para>
</sect3>
+ <sect3>
+ <title>setCurlOptions</title>
+
+ <para><funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setCurlOptions</function></funcdef>
+
+ <paramdef><type>array</type><parameter>$options</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>This method allows to directly set any desired
+ option to manipulate the usage of the cURL client (when in cURL
+ mode). It can be used eg. to explicitly bind to an outgoing ip
+ address when the server is multihomed</para>
+ </sect3>
+
<sect3>
<title>setDebug</title>
SSL certificates to validate the server with, use the
<methodname>setCaCertificate</methodname> method.</para>
</sect3>
+
+ <sect3>
+ <title>setUserAgent</title>
+
+ <para><funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>Useragent</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$useragent</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>This method sets a custom user-agent that will be
+ used by the client in the http headers sent with the request. The
+ default value is built using the library name and version
+ constants.</para>
+ </sect3>
</sect2>
<sect2>
<para>Example usage:</para>
<programlisting language="php">
-$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server");
+$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
$client->return_type = 'phpvals';
$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
$resp = $client->send($message);
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
- below).</para>
+ ...). 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
+ <varname>exception_handling</varname> member variable (see
+ ...).</para>
<para>Note that if you implement a method with a name prefixed by
<code>system.</code> the handler function will be invoked by the
"system.methodHelp" protocol does not support documenting method
parameters individually.</para>
</listitem>
+
+ <listitem>
+ <para><literal>parameters_type</literal> - 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 <literal>phpvals</literal>.</para>
+ </listitem>
</itemizedlist>
<para>Look at the <filename>server.php</filename> example in the
<para>Note that the <methodname>service</methodname> 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.</para>
+ permits further manipulation of the response, possibly in combination
+ with output buffering.</para>
<para>To prevent the server from sending HTTP headers back to the
client, you can pass a second parameter with a value of
TRUE.</para>
</sect3>
+ <sect3>
+ <title>exception_handling</title>
+
+ <para>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</para>
+ </sect3>
+
<sect3>
<title>response_charset_encoding</title>
simplified syntax:</para>
<para>to return an xmlrpc error, the method handler function must
- return an instance of xmlrpcresp. There is no other way for the server
- to know when an error response should be served to the client;</para>
+ return an instance of <classname>xmlrpcresp</classname>. 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
+ <varname>exception_handling</varname> memeber var to 1;</para>
<para>to return a base64 value, the method handler function must
encode it on its own, creating an instance of an xmlrpcval
<title>xmlrpc_null_extension</title>
<para>When set to <constant>TRUE</constant>, the lib will enable
- support for the <NIL/> xmlrpc value, as per the extension to the
- standard proposed here. This means that <NIL/> tags will be
- parsed as valid xmlrpc, and the corresponding xmlrpcvals will return
- "null" for <methodname>scalarTyp()</methodname>.</para>
+ 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
+ <methodname>scalarTyp()</methodname>.</para>
+ </sect2>
+
+ <sect2>
+ <title>xmlrpc_null_apache_encoding</title>
+
+ <para>When set to <literal>TRUE</literal>, php NULL values encoded
+ into <classname>xmlrpcval</classname> objects get serialized using the
+ <literal><EX:NIL/></literal> tag instead of
+ <literal><NIL/></literal>. Please note that both forms are
+ always accepted as input regardless of the value of this
+ variable.</para>
</sect2>
</sect1>
</chapter>
<para>The <parameter>options</parameter> 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 is
- <symbol>decode_php_objs</symbol>. When it is set, php objects that
- have been converted to xml-rpc structs using the
+ decoding process. At the moment the only valid option are
+ <symbol>decode_php_objs</symbol> and
+ <literal>dates_as_objects</literal>. When the first is set, php
+ objects that have been converted to xml-rpc structs using the
<function>php_xmlrpc_encode</function> 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).</para>
+ reconstruction time). When the second is set, XML-RPC datetime values
+ will be converted into native <classname>dateTime</classname> objects
+ instead of strings.</para>
<para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
extreme care before enabling the <symbol>decode_php_objs</symbol>
<para>The <parameter>options</parameter> 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
- <symbol>encode_php_objs</symbol> and
- <symbol>auto_dates</symbol>.</para>
+ <symbol>encode_php_objs</symbol>, <literal>null_extension</literal>
+ and <symbol>auto_dates</symbol>.</para>
<para>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)</para>
+ same class definition exists on both sides of the communication). The
+ second allows to encode php <literal>NULL</literal> values to the
+ <literal><NIL/></literal> (or
+ <literal><EX:NIL/></literal>, see ...) tag. The last encodes any
+ string that matches the ISO8601 format into an XML-RPC
+ datetime.</para>
<para>Example:<programlisting language="php">
// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
transparently carried out by the lib, while datetime vals are passed
around as strings).</para>
- <para>Known limitations: requires PHP 5.0.3 +; only works for
+ <para>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
<para>To be documented...</para>
</sect1>
- <sect1>
- <title>My php error log is getting full of "deprecated" errors on
- different lines of xmlrpc.inc and xmlrpcs.inc</title>
-
- <para>This happens when the PHP in usage is version 5, and the error
- reporting level is set to include <constant>E_STRICT</constant> errors.
- Since the main development platform of the library remains (for the time
- being) PHP 4, there are no plans to fix this asap. The best workaround
- is to set the error reporting level to <constant>E_ALL ^
- E_STRICT</constant>.</para>
- </sect1>
-
<sect1>
<title>How to enable long-lasting method calls</title>
<para>PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
The net result of this situation is that those extra characters will not
be properly encoded, and will be received at the other end of the
- XML-RPC tranmission as "garbled data". Unfortunately the library cannot
+ 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
<filename>xmlrpc.inc</filename> (you can search for the string "1252"),
then set <code>$GLOBALS['xmlrpc_internalencoding']='CP1252';</code>
Please note that all incoming data will then be fed to your application
- as UTF-8 to avoid any potentail data loss.</para>
+ as UTF-8 to avoid any potential data loss.</para>
</sect1>
<sect1>
git://git.onelab.eu / plcapi.git / blobdiff