-<?xml version="1.0" encoding="UTF-8"?>\r
-<?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>\r
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\r
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
-<!--\r
-PHP-XMLRPC User manual\r
-$Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $\r
--->\r
-<book lang="en">\r
- <title>XML-RPC for PHP</title>\r
-\r
- <subtitle>version 2.2.2</subtitle>\r
-\r
- <bookinfo>\r
- <date>XXX YY, 2008</date>\r
-\r
- <authorgroup>\r
- <author>\r
- <firstname>Edd</firstname>\r
-\r
- <surname>Dumbill</surname>\r
- </author>\r
-\r
- <author>\r
- <firstname>Gaetano</firstname>\r
-\r
- <surname>Giunta</surname>\r
- </author>\r
-\r
- <author>\r
- <firstname>Miles</firstname>\r
-\r
- <surname>Lott</surname>\r
- </author>\r
-\r
- <author>\r
- <firstname>Justin R.</firstname>\r
-\r
- <surname>Miller</surname>\r
- </author>\r
-\r
- <author>\r
- <firstname>Andres</firstname>\r
-\r
- <surname>Salomon</surname>\r
- </author>\r
- </authorgroup>\r
-\r
- <copyright>\r
- <year>1999,2000,2001</year>\r
-\r
- <holder>Edd Dumbill, Useful Information Company</holder>\r
- </copyright>\r
-\r
- <legalnotice>\r
- <para>All rights reserved.</para>\r
-\r
- <para>Redistribution and use in source and binary forms, with or without\r
- modification, are permitted provided that the following conditions are\r
- met:</para>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>Redistributions of source code must retain the above\r
- copyright notice, this list of conditions and the following\r
- disclaimer.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Redistributions in binary form must reproduce the above\r
- copyright notice, this list of conditions and the following\r
- disclaimer in the documentation and/or other materials provided\r
- with the distribution.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Neither the name of the "XML-RPC for PHP" nor the names of\r
- its contributors may be used to endorse or promote products\r
- derived from this software without specific prior written\r
- permission.</para>\r
- </listitem>\r
- </itemizedlist></para>\r
-\r
- <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND\r
- CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,\r
- BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND\r
- FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE\r
- REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\r
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED\r
- TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR\r
- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\r
- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\r
- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\r
- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>\r
- </legalnotice>\r
- </bookinfo>\r
-\r
- <chapter id="introduction">\r
- <title>Introduction</title>\r
-\r
- <para>XML-RPC is a format devised by <ulink\r
- url="http://www.userland.com/">Userland Software</ulink> for achieving\r
- remote procedure call via XML using HTTP as the transport. XML-RPC has its\r
- own web site, <ulink\r
- url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>\r
-\r
- <para>This collection of PHP classes provides a framework for writing\r
- XML-RPC clients and servers in PHP.</para>\r
-\r
- <para>Main goals of the project are ease of use, flexibility and\r
- completeness.</para>\r
-\r
- <para>The original author is Edd Dumbill of <ulink\r
- url="http://usefulinc.com/">Useful Information Company</ulink>. As of the\r
- 1.0 stable release, the project has been opened to wider involvement and\r
- moved to <ulink\r
- url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>.</para>\r
-\r
- <para>A list of XML-RPC implementations for other languages such as Perl\r
- and Python can be found on the <ulink\r
- url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>\r
-\r
- <sect1>\r
- <title>Acknowledgements</title>\r
-\r
- <para>Daniel E. Baumann</para>\r
-\r
- <para>James Bercegay</para>\r
-\r
- <para>Leon Blackwell</para>\r
-\r
- <para>Stephane Bortzmeyer</para>\r
-\r
- <para>Daniel Convissor</para>\r
-\r
- <para>Geoffrey T. Dairiki</para>\r
-\r
- <para>Stefan Esser</para>\r
-\r
- <para>James Flemer</para>\r
-\r
- <para>Ernst de Haan</para>\r
-\r
- <para>Tom Knight</para>\r
-\r
- <para>Axel Kollmorgen</para>\r
-\r
- <para>Peter Kocks</para>\r
-\r
- <para>Daniel Krippner</para>\r
-\r
- <para>S. Kuip</para>\r
-\r
- <para>A. Lambert</para>\r
-\r
- <para>Dan Libby</para>\r
-\r
- <para>Arnaud Limbourg</para>\r
-\r
- <para>Ernest MacDougal Campbell III</para>\r
-\r
- <para>Lukasz Mach</para>\r
-\r
- <para>Kjartan Mannes</para>\r
-\r
- <para>Ben Margolin</para>\r
-\r
- <para>Nicolay Mausz</para>\r
-\r
- <para>Justin Miller</para>\r
-\r
- <para>Jan Pfeifer</para>\r
-\r
- <para>Giancarlo Pinerolo</para>\r
-\r
- <para>Peter Russel</para>\r
-\r
- <para>Viliam Simko</para>\r
-\r
- <para>Douglas Squirrel</para>\r
-\r
- <para>Idan Sofer</para>\r
-\r
- <para>Anatoly Techtonik</para>\r
-\r
- <para>Eric van der Vlist</para>\r
-\r
- <para>Christian Wenz</para>\r
-\r
- <para>Jim Winstead</para>\r
-\r
- <para>Przemyslaw Wroblewski</para>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="news">\r
- <title>What's new</title>\r
-\r
- <para><emphasis>Note:</emphasis> not all items the following list have\r
- (yet) been fully documented, and some might not be present in any other\r
- chapter in the manual. To find a more detailed description of new\r
- functions and methods please take a look at the source code of the\r
- library, which is quite thoroughly commented in javadoc-like form.</para>\r
-\r
- <sect1>\r
- <title>2.2.2</title>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>fixed: encoding of utf-8 characters outside of the BMP\r
- plane</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: character set declarations surrounded by double\r
- quotes were not recognized in http headers</para>\r
- </listitem>\r
- </itemizedlist></para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.2.1</title>\r
-\r
- <para><emphasis>Note:</emphasis> this is the last release of the library\r
- that will support PHP 4. Future releases (if any) will target php 5.0 as\r
- minimum supported version.</para>\r
-\r
- <itemizedlist>\r
- <listitem>\r
- <para>fixed: work aroung bug in php 5.2.2 which broke support of\r
- HTTP_RAW_POST_DATA</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: is_dir parameter of setCaCertificate() method is\r
- reversed</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: a php warning in xmlrpc_client creator method</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: parsing of '1e+1' as valid float</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: allow errorlevel 3 to work when prev. error handler was\r
- a static method</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: usage of client::setcookie() for multiple cookies in\r
- non-ssl mode</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>improved: support for CP1252 charset is not part or the\r
- library but almost possible</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>improved: more info when curl is enabled and debug mode is\r
- on</para>\r
- </listitem>\r
- </itemizedlist>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.2</title>\r
-\r
- <itemizedlist>\r
- <listitem>\r
- <para>fixed: debugger errors on php installs with magic_quotes_gpc\r
- on</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: support for https connections via proxy</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>fixed: wrap_xmlrpc_method() generated code failed to properly\r
- encode php objects</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>improved: slightly faster encoding of data which is internally\r
- UTF-8</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>improved: debugger always generates a 'null' id for jsonrpc if\r
- user omits it</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>new: debugger can take advantage of a graphical value builder\r
- (it has to be downloaded separately, as part of jsxmlrpc package.\r
- See Appendix D for more details)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>new: support for the <NIL/> xmlrpc extension. see below\r
- for more details</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>new: server support for the system.getCapabilities xmlrpc\r
- extension</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>new: <function><link\r
- linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>\r
- accepts two new options: debug and return_on_fault</para>\r
- </listitem>\r
- </itemizedlist>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.1</title>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>The <function>wrap_php_function</function> and\r
- <function>wrap_xmlrpc_method</function> functions have been moved\r
- out of the base library file <filename>xmlrpc.inc</filename> into\r
- a file of their own: <filename>xmlrpc_wrappers.inc</filename>. You\r
- will have to include() / require() it in your scripts if you have\r
- been using those functions. For increased security, the automatic\r
- rebuilding of php object instances out of received xmlrpc structs\r
- in <function>wrap_xmlrpc_method()</function> has been disabled\r
- (but it can be optionally re-enabled). Both\r
- <function>wrap_php_function()</function> and\r
- <function>wrap_xmlrpc_method()</function> functions accept many\r
- more options to fine tune their behaviour, including one to return\r
- the php code to be saved and later used as standalone php\r
- script</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>The constructor of xmlrpcval() values has seen some internal\r
- changes, and it will not throw a php warning anymore when invoked\r
- using an unknown xmlrpc type: the error will only be written to\r
- php error log. Also <code>new xmlrpcval('true', 'boolean')</code>\r
- is not supported anymore</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>The new function\r
- <function>php_xmlrpc_decode_xml()</function> will take the xml\r
- representation of either an xmlrpc request, response or single\r
- value and return the corresponding php-xmlrpc object\r
- instance</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>A new function <function>wrap_xmlrpc_server()</function>has\r
- been added, to wrap all (or some) of the methods exposed by a\r
- remote xmlrpc server into a php class</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>A new file has been added:\r
- <filename>verify_compat.php</filename>, to help users diagnose the\r
- level of compliance of their php installation with the\r
- library</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Restored compatibility with php 4.0.5 (for those poor souls\r
- still stuck on it)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Method <methodname>xmlrpc_server->service()</methodname>\r
- now returns a value: either the response payload or xmlrpcresp\r
- object instance</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Method\r
- <methodname>xmlrpc_server->add_to_map()</methodname> now\r
- accepts xmlrpc methods with no param definitions</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Documentation for single parameters of exposed methods can\r
- be added to the dispatch map (and turned into html docs in\r
- conjunction with a future release of the 'extras' package)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Full response payload is saved into xmlrpcresp object for\r
- further debugging</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>The debugger can now generate code that wraps a remote\r
- method into a php function (works for jsonrpc, too); it also has\r
- better support for being activated via a single GET call (e.g. for\r
- integration into other tools)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Stricter parsing of incoming xmlrpc messages: two more\r
- invalid cases are now detected (double <literal>data</literal>\r
- element inside <literal>array</literal> and\r
- <literal>struct</literal>/<literal>array</literal> after scalar\r
- inside <literal>value</literal> element)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>More logging of errors in a lot of situations</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Javadoc documentation of lib files (almost) complete</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Many performance tweaks and code cleanups, plus the usual\r
- crop of bugs fixed (see NEWS file for complete list of\r
- bugs)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Lib internals have been modified to provide better support\r
- for grafting extra functionality on top of it. Stay tuned for\r
- future releases of the EXTRAS package (or go read Appendix\r
- B)...</para>\r
- </listitem>\r
- </itemizedlist></para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.0 final</title>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>Added to the client class the possibility to use Digest and\r
- NTLM authentication methods (when using the CURL library) for\r
- connecting to servers and NTLM for connecting to proxies</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added to the client class the possibility to specify\r
- alternate certificate files/directories for authenticating the\r
- peer with when using HTTPS communication</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Reviewed all examples and added a new demo file, containing\r
- a proxy to forward xmlrpc requests to other servers (useful e.g.\r
- for ajax coding)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>The debugger has been upgraded to reflect the new client\r
- capabilities</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>All known bugs have been squashed, and the lib is more\r
- tolerant than ever of commonly-found mistakes</para>\r
- </listitem>\r
- </itemizedlist></para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.0 Release candidate 3</title>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>Added to server class the property\r
- <property>functions_parameters_type</property>, that allows the\r
- server to register plain php functions as xmlrpc methods (i.e.\r
- functions that do not take an xmlrpcmsg object as unique\r
- param)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>let server and client objects serialize calls using a\r
- specified character set encoding for the produced xml instead of\r
- US-ASCII (ISO-8859-1 and UTF-8 supported)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid\r
- input</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>'class::method' syntax is now accepted in the server\r
- dispatch map</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para><function>xmlrpc_clent::SetDebug()</function> accepts\r
- integer values instead of a boolean value, with debugging level 2\r
- adding to the information printed to screen the complete client\r
- request</para>\r
- </listitem>\r
- </itemizedlist></para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.0 Release candidate 2</title>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>Added a new property of the client object:\r
- <code>xmlrpc_client->return_type</code>, indicating whether\r
- calls to the send() method will return xmlrpcresp objects whose\r
- value() is an xmlrpcval object, a php value (automatically\r
- decoded) or the raw xml received from the server.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added in the extras dir. two new library file:\r
- <filename>jsonrpc.inc</filename> and\r
- <filename>jsonrpcs.inc</filename> containing new classes that\r
- implement support for the json-rpc protocol (alpha quality\r
- code)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added a new client method: <code>setKey($key,\r
- $keypass)</code> to be used in HTTPS connections</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added a new file containing some benchmarks in the testsuite\r
- directory</para>\r
- </listitem>\r
- </itemizedlist></para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>2.0 Release candidate 1</title>\r
-\r
- <itemizedlist>\r
- <listitem>\r
- <para>Support for HTTP proxies (new method:\r
- <code>xmlrpc_client::setProxy()</code>)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Support HTTP compression of both requests and responses.\r
- Clients can specify what kind of compression they accept for\r
- responses between deflate/gzip/any, and whether to compress the\r
- requests. Servers by default compress responses to clients that\r
- explicitly declare support for compression (new methods:\r
- <code>xmlrpc_client::setAcceptedCompression()</code>,\r
- <code>xmlrpc_client::setRequestCompression()</code>). Note that the\r
- ZLIB php extension needs to be enabled in PHP to support\r
- compression.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Implement HTTP 1.1 connections, but only if CURL is enabled\r
- (added an extra parameter to\r
- <code>xmlrpc_client::xmlrpc_client</code> to set the desired HTTP\r
- protocol at creation time and a new supported value for the last\r
- parameter of <code>xmlrpc_client::send</code>, which now can be\r
- safely omitted if it has been specified at creation time)</para>\r
-\r
- <para>With PHP versions greater than 4.3.8 keep-alives are enabled\r
- by default for HTTP 1.1 connections. This should yield faster\r
- execution times when making multiple calls in sequence to the same\r
- xml-rpc server from a single client.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Introduce support for cookies. Cookies to be sent to the\r
- server with a request can be set using\r
- <code>xmlrpc_client::setCookie()</code>, while cookies received from\r
- the server are found in <code>xmlrpcresp::cookies()</code>. It is\r
- left to the user to check for validity of received cookies and\r
- decide whether they apply to successive calls or not.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Better support for detecting different character set encodings\r
- of xml-rpc requests and responses: both client and server objects\r
- will correctly detect the charset encoding of received xml, and use\r
- an appropriate xml parser.</para>\r
-\r
- <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added one new xmlrpcmsg constructor syntax, allowing usage of\r
- a single string with the complete URL of the target server</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Convert xml-rpc boolean values into native php values instead\r
- of 0 and 1</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Force the <code>php_xmlrpc_encode</code> function to properly\r
- encode numerically indexed php arrays into xml-rpc arrays\r
- (numerically indexed php arrays always start with a key of 0 and\r
- increment keys by values of 1)</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Prevent the <code>php_xmlrpc_encode</code> function from\r
- further re-encoding any objects of class <code>xmlrpcval</code> that\r
- are passed to it. This allows to call the function with arguments\r
- consisting of mixed php values / xmlrpcval objects.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Allow a server to NOT respond to system.* method calls\r
- (setting the <code>$server->allow_system_funcs</code>\r
- property).</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Implement a new xmlrpcval method to determine if a value of\r
- type struct has a member of a given name without having to loop\r
- trough all members: <code>xmlrpcval::structMemExists()</code></para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Expand methods <code>xmlrpcval::addArray</code>,\r
- <code>addScalar</code> and <code>addStruct</code> allowing extra php\r
- values to be added to xmlrpcval objects already formed.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Let the <code>xmlrpc_client::send</code> method accept an XML\r
- string for sending instead of an xmlrpcmsg object, to facilitate\r
- debugging and integration with the php native xmlrpc\r
- extension</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Extend the <code>php_xmlrpc_encode</code> and\r
- <code>php_xmlrpc_decode</code> functions to allow serialization and\r
- rebuilding of PHP objects. To successfully rebuild a serialized\r
- object, the object class must be defined in the deserializing end of\r
- the transfer. Note that object members of type resource will be\r
- deserialized as NULL values.</para>\r
-\r
- <para>Note that his has been implemented adding a "php_class"\r
- attribute to xml representation of xmlrpcval of STRUCT type, which,\r
- strictly speaking, breaks the xml-rpc spec. Other xmlrpc\r
- implementations are supposed to ignore such an attribute (unless\r
- they implement a brain-dead custom xml parser...), so it should be\r
- safe enabling it in heterogeneous environments. The activation of\r
- this feature is done by usage of an option passed as second\r
- parameter to both <code>php_xmlrpc_encode</code> and\r
- <code>php_xmlrpc_decode</code>.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Extend the <code>php_xmlrpc_encode</code> function to allow\r
- automatic serialization of iso8601-conforming php strings as\r
- datetime.iso8601 xmlrpcvals, by usage of an optional\r
- parameter</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added an automatic stub code generator for converting xmlrpc\r
- methods to php functions and vice-versa.</para>\r
-\r
- <para>This is done via two new functions:\r
- <code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,\r
- and has many caveats, with php being a typeless language and\r
- all...</para>\r
-\r
- <para>With PHP versions lesser than 5.0.3 wrapping of php functions\r
- into xmlrpc methods is not supported yet.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Allow object methods to be used in server dispatch map</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added a complete debugger solution, in the\r
- <filename>debugger</filename> folder</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Added configurable server-side debug messages, controlled by\r
- the new method <code>xmlrpc_server::SetDebug()</code>. At level 0,\r
- no debug messages are sent to the client; level 1 is the same as the\r
- old behaviour; at level 2 a lot more info is echoed back to the\r
- client, regarding the received call; at level 3 all warnings raised\r
- during server processing are trapped (this prevents breaking the xml\r
- to be echoed back to the client) and added to the debug info sent\r
- back to the client</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>New XML parsing code, yields smaller memory footprint and\r
- faster execution times, not to mention complete elimination of the\r
- dreaded <filename>eval()</filename> construct, so prone to code\r
- injection exploits</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>Rewritten most of the error messages, making text more\r
- explicative</para>\r
- </listitem>\r
- </itemizedlist>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="requirements">\r
- <title>System Requirements</title>\r
-\r
- <para>The library has been designed with goals of scalability and backward\r
- compatibility. As such, it supports a wide range of PHP installs. Note\r
- that not all features of the lib are available in every\r
- configuration.</para>\r
-\r
- <para>The <emphasis>minimum supported</emphasis> PHP version is\r
- 4.2.</para>\r
-\r
- <para>A compatibility layer is provided that allows the code to run on PHP\r
- 4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest\r
- you upgrade as soon as possible.</para>\r
-\r
- <para>Automatic generation of xml-rpc methods from php functions is only\r
- supported with PHP version 5.0.3 and later (note that the lib will\r
- generate some warnings with PHP 5 in strict error reporting mode).</para>\r
-\r
- <para>If you wish to use SSL or HTTP 1.1 to communicate with remote\r
- servers, you need the "curl" extension compiled into your PHP\r
- installation. This is available in PHP 4.0.2 and greater, although 4.0.6\r
- has a bug preventing SSL working, and versions prior to 4.3.8 do not\r
- support streamlining multiple requests using HTTP Keep-Alive.</para>\r
-\r
- <para>The "xmlrpc" native extension is not required to be compiled into\r
- your PHP installation, but if it is, there will be no interference with\r
- the operation of this library.</para>\r
- </chapter>\r
-\r
- <chapter id="manifest">\r
- <title>Files in the distribution</title>\r
-\r
- <glosslist>\r
- <glossentry>\r
- <glossterm>lib/xmlrpc.inc</glossterm>\r
-\r
- <glossdef>\r
- <para>the XML-RPC classes. <function>include()</function> this in\r
- your PHP files to use the classes.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>lib/xmlrpcs.inc</glossterm>\r
-\r
- <glossdef>\r
- <para>the XML-RPC server class. <function>include()</function> this\r
- in addition to xmlrpc.inc to get server functionality</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>lib/xmlrpc_wrappers.inc</glossterm>\r
-\r
- <glossdef>\r
- <para>helper functions to "automagically" convert plain php\r
- functions to xmlrpc services and vice versa</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>lib/compat/array_key_exists.php, lib/compat/is_a.php,\r
- lib/compat/is_scalar.php, lib/compat/var_export.php,\r
- lib/compat/vesrions_compare.php</glossterm>\r
-\r
- <glossdef>\r
- <para>compatibility functions: these files implement the\r
- compatibility layer needed to run the library with PHP versions 4.0\r
- and 4.1</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/server/proxy.php</glossterm>\r
-\r
- <glossdef>\r
- <para>a sample server implementing xmlrpc proxy\r
- functionality.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/server/server.php</glossterm>\r
-\r
- <glossdef>\r
- <para>a sample server hosting various demo functions, as well as a\r
- full suite of functions used for interoperability testing. It is\r
- used by testsuite.php (see below) for unit testing the library, and\r
- is not to be copied literally into your production servers</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/client/client.php, demo/client/agesort.php,\r
- demo/client/which.php</glossterm>\r
-\r
- <glossdef>\r
- <para>client code to exercise some of the functions in server.php,\r
- including the <function>interopEchoTests.whichToolkit</function>\r
- method.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/client/wrap.php</glossterm>\r
-\r
- <glossdef>\r
- <para>client code to illustrate 'wrapping' of remote methods into\r
- php functions.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/client/introspect.php</glossterm>\r
-\r
- <glossdef>\r
- <para>client code to illustrate usage of introspection capabilities\r
- offered by server.php.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/client/mail.php</glossterm>\r
-\r
- <glossdef>\r
- <para>client code to illustrate usage of an xmlrpc-to-email gateway\r
- using Dave Winer's XML-RPC server at userland.com.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/client/zopetest.php</glossterm>\r
-\r
- <glossdef>\r
- <para>example client code that queries an xmlrpc server built in\r
- Zope.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/vardemo.php</glossterm>\r
-\r
- <glossdef>\r
- <para>examples of how to construct xmlrpcval types</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>\r
-\r
- <glossdef>\r
- <para>XML-RPC responses captured in a file for testing purposes (you\r
- can use these to test the\r
- <function>xmlrpcmsg->parseResponse()</function> method).</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>demo/server/discuss.php,\r
- demo/client/comment.php</glossterm>\r
-\r
- <glossdef>\r
- <para>Software used in the PHP chapter of <xref\r
- linkend="jellyfish" /> to provide a comment server and allow the\r
- attachment of comments to stories from Meerkat's data store.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>test/testsuite.php, test/parse_args.php</glossterm>\r
-\r
- <glossdef>\r
- <para>A unit test suite for this software package. If you do\r
- development on this software, please consider submitting tests for\r
- this suite.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>test/benchmark.php</glossterm>\r
-\r
- <glossdef>\r
- <para>A (very limited) benchmarking suite for this software package.\r
- If you do development on this software, please consider submitting\r
- benchmarks for this suite.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>\r
-\r
- <glossdef>\r
- <para>An (incomplete) version PEAR's unit test framework for PHP.\r
- The complete package can be found at <ulink\r
- url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>test/verify_compat.php</glossterm>\r
-\r
- <glossdef>\r
- <para>Script designed to help the user to verify the level of\r
- compatibility of the library with the current php install</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>extras/test.pl, extras/test.py</glossterm>\r
-\r
- <glossdef>\r
- <para>Perl and Python programs to exercise server.php to test that\r
- some of the methods work.</para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>extras/workspace.testPhpServer.fttb</glossterm>\r
-\r
- <glossdef>\r
- <para>Frontier scripts to exercise the demo server. Thanks to Dave\r
- Winer for permission to include these. See <ulink\r
- url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's\r
- announcement of these.</ulink></para>\r
- </glossdef>\r
- </glossentry>\r
-\r
- <glossentry>\r
- <glossterm>extras/rsakey.pem</glossterm>\r
-\r
- <glossdef>\r
- <para>A test certificate key for the SSL support, which can be used\r
- to generate dummy certificates. It has the passphrase "test."</para>\r
- </glossdef>\r
- </glossentry>\r
- </glosslist>\r
- </chapter>\r
-\r
- <chapter id="bugs">\r
- <title>Known bugs and limitations</title>\r
-\r
- <para>This started out as a bare framework. Many "nice" bits haven't been\r
- put in yet. Specifically, very little type validation or coercion has been\r
- put in. PHP being a loosely-typed language, this is going to have to be\r
- done explicitly (in other words: you can call a lot of library functions\r
- passing them arguments of the wrong type and receive an error message only\r
- much further down the code, where it will be difficult to\r
- understand).</para>\r
-\r
- <para>dateTime.iso8601 is supported opaquely. It can't be done natively as\r
- the XML-RPC specification explicitly forbids passing of timezone\r
- specifiers in ISO8601 format dates. You can, however, use the <xref\r
- linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions\r
- to do the encoding and decoding for you.</para>\r
-\r
- <para>Very little HTTP response checking is performed (e.g. HTTP redirects\r
- are not followed and the Content-Length HTTP header, mandated by the\r
- xml-rpc spec, is not validated); cookie support still involves quite a bit\r
- of coding on the part of the user.</para>\r
-\r
- <para>If a specific character set encoding other than US-ASCII, ISO-8859-1\r
- or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request\r
- or response messages then it will be ignored for the moment, and the\r
- content will be parsed as if it had been encoded using the charset defined\r
- by <xref linkend="xmlrpc-defencoding" /></para>\r
-\r
- <para>Very large floating point numbers are serialized using exponential\r
- notation, even though the spec explicitly forbids this behaviour. This\r
- will not be a problem if this library is used on both ends of the\r
- communication, but might cause problems with other implementations.</para>\r
-\r
- <para>Support for receiving from servers version 1 cookies (i.e.\r
- conforming to RFC 2965) is quite incomplete, and might cause unforeseen\r
- errors.</para>\r
-\r
- <para>A PHP warning will be generated in many places when using\r
- <filename>xmlrpc.inc</filename> and <filename>xmlrpcs.inc</filename> with\r
- PHP 5 in strict error reporting mode. The simplest workaround to this\r
- problem is to lower the <parameter>error_reporting</parameter> level in\r
- php.ini.</para>\r
- </chapter>\r
-\r
- <chapter id="support">\r
- <title>Support</title>\r
-\r
- <sect1>\r
- <title>Online Support</title>\r
-\r
- <para>XML-RPC for PHP is offered "as-is" without any warranty or\r
- commitment to support. However, informal advice and help is available\r
- via the XML-RPC for PHP website and mailing list and from\r
- XML-RPC.com.</para>\r
-\r
- <itemizedlist>\r
- <listitem>\r
- <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted\r
- on <ulink\r
- url="http://phpxmlrpc.sourceforge.net">phpxmlrpc.sourceforge.net</ulink>.\r
- Bugs, feature requests and patches can be posted to the <ulink\r
- url="http://sourceforge.net/projects/phpxmlrpc">project's\r
- website</ulink>.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is\r
- run by the author. More details <ulink\r
- url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be\r
- found here</ulink>.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>For more general XML-RPC questions, there is a Yahoo! Groups\r
- <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing\r
- list</ulink>.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>The <ulink\r
- url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion\r
- group is a useful place to get help with using XML-RPC. This group\r
- is also gatewayed into the Yahoo! Groups mailing list.</para>\r
- </listitem>\r
- </itemizedlist>\r
- </sect1>\r
-\r
- <sect1 id="jellyfish" xreflabel="The Jellyfish Book">\r
- <title>The Jellyfish Book</title>\r
-\r
- <para><graphic align="right" depth="190" fileref="progxmlrpc.s.gif"\r
- format="GIF" width="145" />Together with Simon St.Laurent and Joe\r
- Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and\r
- Associates on XML-RPC. It features a rather fetching jellyfish on the\r
- cover.</para>\r
-\r
- <para>Complete details of the book are <ulink\r
- url="http://www.oreilly.com/catalog/progxmlrpc/">available from\r
- O'Reilly's web site.</ulink></para>\r
-\r
- <para>Edd is responsible for the chapter on PHP, which includes a worked\r
- example of creating a forum server, and hooking it up the O'Reilly's\r
- <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in\r
- order to allow commenting on news stories from around the Web.</para>\r
-\r
- <para>If you've benefited from the effort that has been put into writing\r
- this software, then please consider buying the book!</para>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="apidocs">\r
- <title>Class documentation</title>\r
-\r
- <sect1 id="xmlrpcval" xreflabel="xmlrpcval">\r
- <title>xmlrpcval</title>\r
-\r
- <para>This is where a lot of the hard work gets done. This class enables\r
- the creation and encapsulation of values for XML-RPC.</para>\r
-\r
- <para>Ensure you've read the XML-RPC spec at <ulink\r
- url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>\r
- before reading on as it will make things clearer.</para>\r
-\r
- <para>The <classname>xmlrpcval</classname> class can store arbitrarily\r
- complicated values using the following types: <literal>i4 int boolean\r
- string double dateTime.iso8601 base64 array struct</literal>. You should\r
- refer to the <ulink url="http://www.xmlrpc.com/spec">spec</ulink> for\r
- more information on what each of these types mean.</para>\r
-\r
- <sect2>\r
- <title>Notes on types</title>\r
-\r
- <sect3>\r
- <title>int</title>\r
-\r
- <para>The type <classname>i4</classname> is accepted as a synonym\r
- for <classname>int</classname> when creating xmlrpcval objects. The\r
- xml parsing code will always convert <classname>i4</classname> to\r
- <classname>int</classname>: <classname>int</classname> is regarded\r
- by this implementation as the canonical name for this type.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>base64</title>\r
-\r
- <para>Base 64 encoding is performed transparently to the caller when\r
- using this type. Decoding is also transparent. Therefore you ought\r
- to consider it as a "binary" data type, for use when you want to\r
- pass data that is not 7-bit clean.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>boolean</title>\r
-\r
- <para>The php values <literal>true</literal> and\r
- <literal>1</literal> map to <literal>true</literal>. All other\r
- values (including the empty string) are converted to\r
- <literal>false</literal>.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>string</title>\r
-\r
- <para>Characters <, >, ', ", &, are encoded using their\r
- entity reference as &lt; &gt; &apos; &quot; and\r
- &amp; All other characters outside of the ASCII range are\r
- encoded using their character reference representation (e.g.\r
- &#200 for é). The XML-RPC spec recommends only encoding\r
- <literal>< &</literal> but this implementation goes further,\r
- for reasons explained by <ulink\r
- url="http://www.w3.org/TR/REC-xml#syntax">the XML 1.0\r
- recommendation</ulink>. In particular, using character reference\r
- representation has the advantage of producing XML that is valid\r
- independently of the charset encoding assumed.</para>\r
- </sect3>\r
- </sect2>\r
-\r
- <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">\r
- <title>Creation</title>\r
-\r
- <para>The constructor is the normal way to create an\r
- <classname>xmlrpcval</classname>. The constructor can take these\r
- forms:</para>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type>new\r
- <function>xmlrpcval</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type>new\r
- <function>xmlrpcval</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type>new\r
- <function>xmlrpcval</function></funcdef>\r
-\r
- <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type>new\r
- <function>xmlrpcval</function></funcdef>\r
-\r
- <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>The first constructor creates an empty value, which must be\r
- altered using the methods <function>addScalar</function>,\r
- <function>addArray</function> or <function>addStruct</function> before\r
- it can be used.</para>\r
-\r
- <para>The second constructor creates a simple string value.</para>\r
-\r
- <para>The third constructor is used to create a scalar value. The\r
- second parameter must be a name of an XML-RPC type. Valid types are:\r
- "<literal>int</literal>", "<literal>boolean</literal>",\r
- "<literal>string</literal>", "<literal>double</literal>",\r
- "<literal>dateTime.iso8601</literal>",\r
- "<literal>base64</literal>".</para>\r
-\r
- <para>Examples:</para>\r
-\r
- <programlisting language="php">\r
-$myInt = new xmlrpcvalue(1267, "int");\r
-$myString = new xmlrpcvalue("Hello, World!", "string");\r
-$myBool = new xmlrpcvalue(1, "boolean");\r
-$myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string\r
-</programlisting>\r
-\r
- <para>The fourth constructor form can be used to compose complex\r
- XML-RPC values. The first argument is either a simple array in the\r
- case of an XML-RPC <classname>array</classname> or an associative\r
- array in the case of a <classname>struct</classname>. The elements of\r
- the array <emphasis>must be <classname>xmlrpcval</classname> objects\r
- themselves</emphasis>.</para>\r
-\r
- <para>The second parameter must be either "<literal>array</literal>"\r
- or "<literal>struct</literal>".</para>\r
-\r
- <para>Examples:</para>\r
-\r
- <programlisting language="php">\r
-$myArray = new xmlrpcval(\r
- array(\r
- new xmlrpcval("Tom"),\r
- new xmlrpcval("Dick"),\r
- new xmlrpcval("Harry")\r
- ),\r
- "array");\r
-\r
-// recursive struct\r
-$myStruct = new xmlrpcval(\r
- array(\r
- "name" => new xmlrpcval("Tom", "string"),\r
- "age" => new xmlrpcval(34, "int"),\r
- "address" => new xmlrpcval(\r
- array(\r
- "street" => new xmlrpcval("Fifht Ave", "string"),\r
- "city" => new xmlrpcval("NY", "string")\r
- ), \r
- "struct")\r
- ), \r
- "struct");\r
-</programlisting>\r
-\r
- <para>See the file <literal>vardemo.php</literal> in this distribution\r
- for more examples.</para>\r
- </sect2>\r
-\r
- <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">\r
- <title>Methods</title>\r
-\r
- <sect3>\r
- <title>addScalar</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>addScalar</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>int</type><function>addScalar</function></funcdef>\r
-\r
- <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>If <parameter>$val</parameter> is an empty\r
- <classname>xmlrpcval</classname> this method makes it a scalar\r
- value, and sets that value.</para>\r
-\r
- <para>If <parameter>$val</parameter> is already a scalar value, then\r
- no more scalars can be added and <literal>0</literal> is\r
- returned.</para>\r
-\r
- <para>If <parameter>$val</parameter> is an xmlrpcval of type array,\r
- the php value <parameter>$scalarval</parameter> is added as its last\r
- element.</para>\r
-\r
- <para>If all went OK, <literal>1</literal> is returned, otherwise\r
- <literal>0</literal>.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>addArray</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>addArray</function></funcdef>\r
-\r
- <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>The argument is a simple (numerically indexed) array. The\r
- elements of the array <emphasis>must be\r
- <classname>xmlrpcval</classname> objects\r
- themselves</emphasis>.</para>\r
-\r
- <para>Turns an empty <classname>xmlrpcval</classname> into an\r
- <classname>array</classname> with contents as specified by\r
- <parameter>$arrayVal</parameter>.</para>\r
-\r
- <para>If <parameter>$val</parameter> is an xmlrpcval of type array,\r
- the elements of <parameter>$arrayVal</parameter> are appended to the\r
- existing ones.</para>\r
-\r
- <para>See the fourth constructor form for more information.</para>\r
-\r
- <para>If all went OK, <literal>1</literal> is returned, otherwise\r
- <literal>0</literal>.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>addStruct</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>addStruct</function></funcdef>\r
-\r
- <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>The argument is an associative array. The elements of the\r
- array <emphasis>must be <classname>xmlrpcval</classname> objects\r
- themselves</emphasis>.</para>\r
-\r
- <para>Turns an empty <classname>xmlrpcval</classname> into a\r
- <classname>struct</classname> with contents as specified by\r
- <parameter>$assocArrayVal</parameter>.</para>\r
-\r
- <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,\r
- the elements of <parameter>$arrayVal</parameter> are merged with the\r
- existing ones.</para>\r
-\r
- <para>See the fourth constructor form for more information.</para>\r
-\r
- <para>If all went OK, <literal>1</literal> is returned, otherwise\r
- <literal>0</literal>.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>kindOf</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>kindOf</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns a string containing "struct", "array" or "scalar"\r
- describing the base type of the value. If it returns "undef" it\r
- means that the value hasn't been initialised.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>serialize</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>serialize</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns a string containing the XML-RPC representation of this\r
- value.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>scalarVal</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>mixed</type><function>scalarVal</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>If <function>$val->kindOf() == "scalar"</function>, this\r
- method returns the actual PHP-language value of the scalar (base 64\r
- decoding is automatically handled here).</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>scalarTyp</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>scalarTyp</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>If <function>$val->kindOf() == "scalar"</function>, this\r
- method returns a string denoting the type of the scalar. As\r
- mentioned before, <literal>i4</literal> is always coerced to\r
- <literal>int</literal>.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>arrayMem</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type><function>arrayMem</function></funcdef>\r
-\r
- <paramdef><type>int</type><parameter>$n</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>If <function>$val->kindOf() == "array"</function>, returns\r
- the <parameter>$n</parameter>th element in the array represented by\r
- the value <parameter>$val</parameter>. The value returned is an\r
- <classname>xmlrpcval</classname> object.</para>\r
-\r
- <para><programlisting language="php">\r
-// iterating over values of an array object\r
-for ($i = 0; $i < $val->arraySize(); $i++)\r
-{\r
- $v = $val->arrayMem($i);\r
- echo "Element $i of the array is of type ".$v->kindOf();\r
-}\r
-</programlisting></para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>arraySize</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>arraySize</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>If <parameter>$val</parameter> is an\r
- <classname>array</classname>, returns the number of elements in that\r
- array.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>structMem</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type><function>structMem</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>If <function>$val->kindOf() == "struct"</function>, returns\r
- the element called <parameter>$memberName</parameter> from the\r
- struct represented by the value <parameter>$val</parameter>. The\r
- value returned is an <classname>xmlrpcval</classname> object.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>structEach</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>array</type><function>structEach</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns the next (key, value) pair from the struct, when\r
- <parameter>$val</parameter> is a struct.\r
- <parameter>$value</parameter> is an xmlrpcval itself. See also <xref\r
- linkend="structreset" />.</para>\r
-\r
- <para><programlisting language="php">\r
-// iterating over all values of a struct object\r
-$val->structreset();\r
-while (list($key, $v) = $val->structEach())\r
-{\r
- echo "Element $key of the struct is of type ".$v->kindOf();\r
-}\r
-</programlisting></para>\r
- </sect3>\r
-\r
- <sect3 id="structreset" xreflabel="structreset()">\r
- <title>structReset</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>structReset</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Resets the internal pointer for\r
- <function>structEach()</function> to the beginning of the struct,\r
- where <parameter>$val</parameter> is a struct.</para>\r
- </sect3>\r
-\r
- <sect3 id="structmemexists" xreflabel="structmemexists()">\r
- <title>structMemExists</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>bool</type><function>structMemExsists</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns <constant>TRUE</constant> or\r
- <constant>FALSE</constant> depending on whether a member of the\r
- given name exists in the struct.</para>\r
- </sect3>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">\r
- <title>xmlrpcmsg</title>\r
-\r
- <para>This class provides a representation for a request to an XML-RPC\r
- server. A client sends an <classname>xmlrpcmsg</classname> to a server,\r
- and receives back an <classname>xmlrpcresp</classname> (see <xref\r
- linkend="xmlrpc-client-send" />).</para>\r
-\r
- <sect2>\r
- <title>Creation</title>\r
-\r
- <para>The constructor takes the following forms:</para>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcmsg</type>new\r
- <function>xmlrpcmsg</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>\r
-\r
- <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Where <parameter>methodName</parameter> is a string indicating\r
- the name of the method you wish to invoke, and\r
- <parameter>parameterArray</parameter> is a simple php\r
- <classname>Array</classname> of <classname>xmlrpcval</classname>\r
- objects. Here's an example message to the <emphasis>US state\r
- name</emphasis> server:</para>\r
-\r
- <programlisting language="php">\r
-$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));\r
-</programlisting>\r
-\r
- <para>This example requests the name of state number 23. For more\r
- information on <classname>xmlrpcval</classname> objects, see <xref\r
- linkend="xmlrpcval" />.</para>\r
-\r
- <para>Note that the <parameter>parameterArray</parameter> parameter is\r
- optional and can be omitted for methods that take no input parameters\r
- or if you plan to add parameters one by one.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Methods</title>\r
-\r
- <sect3>\r
- <title>addParam</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>bool</type><function>addParam</function></funcdef>\r
-\r
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Adds the <classname>xmlrpcval</classname>\r
- <parameter>xmlrpcVal</parameter> to the parameter list for this\r
- method call. Returns TRUE or FALSE on error.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>getNumParams</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>getNumParams</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns the number of parameters attached to this\r
- message.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>getParam</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type><function>getParam</function></funcdef>\r
-\r
- <paramdef><type>int</type><parameter>$n</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Gets the <parameter>n</parameter>th parameter in the message\r
- (with the index zero-based). Use this method in server\r
- implementations to retrieve the values sent by the client.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>method</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>method</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>string</type><function>method</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$methName</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Gets or sets the method contained in the XML-RPC\r
- message.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>parseResponse</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcresp</type><function>parseResponse</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Given an incoming XML-RPC server response contained in the\r
- string <parameter>$xmlString</parameter>, this method constructs an\r
- <classname>xmlrpcresp</classname> response object and returns it,\r
- setting error codes as appropriate (see <xref\r
- linkend="xmlrpc-client-send" />).</para>\r
-\r
- <para>This method processes any HTTP/MIME headers it finds.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>parseResponseFile</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcresp</type><function>parseResponseFile</function></funcdef>\r
-\r
- <paramdef><type>file handle\r
- resource</type><parameter>$fileHandle</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Given an incoming XML-RPC server response on the open file\r
- handle <parameter>fileHandle</parameter>, this method reads all the\r
- data it finds and passes it to\r
- <function>parseResponse.</function></para>\r
-\r
- <para>This method is useful to construct responses from pre-prepared\r
- files (see files <literal>demo1.txt, demo2.txt, demo3.txt</literal>\r
- in this distribution). It processes any HTTP headers it finds, and\r
- does not close the file handle.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>serialize</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string\r
- </type><function>serialize</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns the an XML string representing the XML-RPC\r
- message.</para>\r
- </sect3>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">\r
- <title>xmlrpc_client</title>\r
-\r
- <para>This is the basic class used to represent a client of an XML-RPC\r
- server.</para>\r
-\r
- <sect2>\r
- <title>Creation</title>\r
-\r
- <para>The constructor accepts one of two possible syntaxes:</para>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpc_client</type>new\r
- <function>xmlrpc_client</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>xmlrpc_client</type>new\r
- <function>xmlrpc_client</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Here are a couple of usage examples of the first form:</para>\r
-\r
- <programlisting language="php">\r
-$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");\r
-$another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/xmlrpcserver?agent=007");\r
-</programlisting>\r
-\r
- <para>The second syntax does not allow to express a username and\r
- password to be used for basic HTTP authorization as in the second\r
- example above, but instead it allows to choose whether xmlrpc calls\r
- will be made using the HTTP 1.0 or 1.1 protocol.</para>\r
-\r
- <para>Here's another example client set up to query Userland's XML-RPC\r
- server at <emphasis>betty.userland.com</emphasis>:</para>\r
-\r
- <programlisting language="php">\r
-$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);\r
-</programlisting>\r
-\r
- <para>The <parameter>server_port</parameter> parameter is optional,\r
- and if omitted will default to 80 when using HTTP and 443 when using\r
- HTTPS (see the <xref linkend="xmlrpc-client-send" /> method\r
- below).</para>\r
-\r
- <para>The <parameter>transport</parameter> parameter is optional, and\r
- if omitted will default to 'http'. Allowed values are either\r
- '<symbol>http'</symbol>, '<symbol>https</symbol>' or\r
- '<symbol>http11'</symbol>. Its value can be overridden with every call\r
- to the <methodname>send</methodname> method. See the\r
- <methodname>send</methodname> method below for more details about the\r
- meaning of the different values.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Methods</title>\r
-\r
- <para>This class supports the following methods.</para>\r
-\r
- <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client->send">\r
- <title>send</title>\r
-\r
- <para>This method takes the forms:</para>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>\r
-\r
- <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpc_message</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>array</type><function>send</function></funcdef>\r
-\r
- <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Where <parameter>xmlrpc_message</parameter> is an instance of\r
- <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),\r
- and <parameter>response</parameter> is an instance of\r
- <classname>xmlrpcresp</classname> (see <xref\r
- linkend="xmlrpcresp" />).</para>\r
-\r
- <para><parameter>If xmlrpc_messages</parameter> is an array of\r
- message instances, <code>responses</code> will be an array of\r
- response instances. The client will try to make use of a single\r
- <code>system.multicall</code> xml-rpc method call to forward to the\r
- server all the messages in a single HTTP round trip, unless\r
- <code>$client->no_multicall</code> has been previously set to\r
- <code>TRUE</code> (see the multicall method below), in which case\r
- many consecutive xmlrpc requests will be sent.</para>\r
-\r
- <para>The third syntax allows to build by hand (or any other means)\r
- a complete xmlrpc request message, and send it to the server.\r
- <parameter>xml_payload</parameter> should be a string containing the\r
- complete xml representation of the request. It is e.g. useful when,\r
- for maximal speed of execution, the request is serialized into a\r
- string using the native php xmlrpc functions (see <ulink\r
- url="http://www.php.net/xmlrpc">the php manual on\r
- xmlrpc</ulink>).</para>\r
-\r
- <para>The <parameter>timeout</parameter> is optional, and will be\r
- set to <literal>0</literal> (wait for platform-specific predefined\r
- timeout) if omitted. This timeout value is passed to\r
- <function>fsockopen()</function>. It is also used for detecting\r
- server timeouts during communication (i.e. if the server does not\r
- send anything to the client for <parameter>timeout</parameter>\r
- seconds, the connection will be closed).</para>\r
-\r
- <para>The <parameter>transport</parameter> parameter is optional,\r
- and if omitted will default to the transport set using instance\r
- creator or 'http' if omitted. The only other valid values are\r
- 'https', which will use an SSL HTTP connection to connect to the\r
- remote server, and 'http11'. Note that your PHP must have the "curl"\r
- extension compiled in order to use both these features. Note that\r
- when using SSL you should normally set your port number to 443,\r
- unless the SSL server you are contacting runs at any other\r
- port.</para>\r
-\r
- <warning>\r
- <para>PHP 4.0.6 has a bug which prevents SSL working.</para>\r
- </warning>\r
-\r
- <para>In addition to low-level errors, the XML-RPC server you were\r
- querying may return an error in the\r
- <classname>xmlrpcresp</classname> object. See <xref\r
- linkend="xmlrpcresp" /> for details of how to handle these\r
- errors.</para>\r
- </sect3>\r
-\r
- <sect3 id="multicall" xreflabel="xmlrpc_client->multicall">\r
- <title>multiCall</title>\r
-\r
- <para>This method takes the form:</para>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>array</type><function>multiCall</function></funcdef>\r
-\r
- <paramdef><type>array</type><parameter>$messages</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$transport</parameter></paramdef>\r
-\r
- <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method is used to boxcar many method calls in a single\r
- xml-rpc request. It will try first to make use of the\r
- <code>system.multicall</code> xml-rpc method call, and fall back to\r
- executing many separate requests if the server returns any\r
- error.</para>\r
-\r
- <para><parameter>msgs</parameter> is an array of\r
- <classname>xmlrpcmsg</classname> objects (see <xref\r
- linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an\r
- array of <classname>xmlrpcresp</classname> objects (see <xref\r
- linkend="xmlrpcresp" />).</para>\r
-\r
- <para>The <parameter>timeout</parameter> and\r
- <parameter>transport</parameter> parameters are optional, and behave\r
- as in the <methodname>send</methodname> method above.</para>\r
-\r
- <para>The <parameter>fallback</parameter> parameter is optional, and\r
- defaults to <constant>TRUE</constant>. When set to\r
- <constant>FALSE</constant> it will prevent the client to try using\r
- many single method calls in case of failure of the first multicall\r
- request. It should be set only when the server is known to support\r
- the multicall extension.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setAcceptedCompression</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setAcceptedCompression</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method defines whether the client will accept compressed\r
- xml payload forming the bodies of the xmlrpc responses received from\r
- servers. Note that enabling reception of compressed responses merely\r
- adds some standard http headers to xmlrpc requests. It is up to the\r
- xmlrpc server to return compressed responses when receiving such\r
- requests. Allowed values for\r
- <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',\r
- 'any' or null (with any meaning either gzip or deflate).</para>\r
-\r
- <para>This requires the "zlib" extension to be enabled in your php\r
- install. If it is, by default <classname>xmlrpc_client</classname>\r
- instances will enable reception of compressed content.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setCaCertificate</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setCaCertificate</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>\r
-\r
- <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method sets an optional certificate to be used in\r
- SSL-enabled communication to validate a remote server with (when the\r
- <parameter>server_method</parameter> is set to 'https' in the\r
- client's construction or in the send method and\r
- <methodname>SetSSLVerifypeer</methodname> has been set to\r
- <constant>TRUE</constant>).</para>\r
-\r
- <para>The <parameter>certificate</parameter> parameter must be the\r
- filename of a PEM formatted certificate, or a directory containing\r
- multiple certificate files. The <parameter>is_dir</parameter>\r
- parameter defaults to <constant>FALSE</constant>, set it to\r
- <constant>TRUE</constant> to specify that\r
- <parameter>certificate</parameter> indicates a directory instead of\r
- a single file.</para>\r
-\r
- <para>This requires the "curl" extension to be compiled into your\r
- installation of PHP. For more details see the man page for the\r
- <function>curl_setopt</function> function.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setCertificate</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setCertificate</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method sets the optional certificate and passphrase used\r
- in SSL-enabled communication with a remote server (when the\r
- <parameter>server_method</parameter> is set to 'https' in the\r
- client's construction or in the send method).</para>\r
-\r
- <para>The <parameter>certificate</parameter> parameter must be the\r
- filename of a PEM formatted certificate. The\r
- <parameter>passphrase</parameter> parameter must contain the\r
- password required to use the certificate.</para>\r
-\r
- <para>This requires the "curl" extension to be compiled into your\r
- installation of PHP. For more details see the man page for the\r
- <function>curl_setopt</function> function.</para>\r
-\r
- <para>Note: to retrieve information about the client certificate on\r
- the server side, you will need to look into the environment\r
- variables which are set up by the webserver. Different webservers\r
- will typically set up different variables.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setCookie</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setCookie</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$name</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$value</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$path</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$domain</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$port</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method sets a cookie that will be sent to the xmlrpc\r
- server along with every further request (useful e.g. for keeping\r
- session info outside of the xml-rpc payload).</para>\r
-\r
- <para><parameter>$value</parameter> is optional, and defaults to\r
- null.</para>\r
-\r
- <para><parameter>$path, $domain and $port</parameter> are optional,\r
- and will be omitted from the cookie header if unspecified. Note that\r
- setting any of these values will turn the cookie into a 'version 1'\r
- cookie, that might not be fully supported by the server (see RFC2965\r
- for more details).</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setCredentials</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setCredentials</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$username</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$password</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method sets the username and password for authorizing the\r
- client to a server. With the default (HTTP) transport, this\r
- information is used for HTTP Basic authorization. Note that username\r
- and password can also be set using the class constructor. With HTTP\r
- 1.1 and HTTPS transport, NTLM and Digest authentication protocols\r
- are also supported. To enable them use the constants\r
- <constant>CURLAUTH_DIGEST</constant> and\r
- <constant>CURLAUTH_NTLM</constant> as values for the authtype\r
- parameter.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setDebug</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setDebug</function></funcdef>\r
-\r
- <paramdef><type>int</type><parameter>$debugLvl</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para><parameter>debugLvl</parameter> is either <literal>0,\r
- 1</literal> or 2 depending on whether you require the client to\r
- print debugging information to the browser. The default is not to\r
- output this information (0).</para>\r
-\r
- <para>The debugging information at level 1includes the raw data\r
- returned from the XML-RPC server it was querying (including bot HTTP\r
- headers and the full XML payload), and the PHP value the client\r
- attempts to create to represent the value returned by the server. At\r
- level2, the complete payload of the xmlrpc request is also printed,\r
- before being sent t the server.</para>\r
-\r
- <para>This option can be very useful when debugging servers as it\r
- allows you to see exactly what the client sends and the server\r
- returns.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setKey</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setKey</function></funcdef>\r
-\r
- <paramdef><type>int</type><parameter>$key</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method sets the optional certificate key and passphrase\r
- used in SSL-enabled communication with a remote server (when the\r
- <parameter>transport</parameter> is set to 'https' in the client's\r
- construction or in the send method).</para>\r
-\r
- <para>This requires the "curl" extension to be compiled into your\r
- installation of PHP. For more details see the man page for the\r
- <function>curl_setopt</function> function.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setProxy</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setProxy</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method enables calling servers via an HTTP proxy. The\r
- <parameter>proxyusername</parameter>,<parameter>\r
- proxypassword</parameter> and <parameter>authtype</parameter>\r
- parameters are optional. <parameter>Authtype</parameter> defaults to\r
- <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);\r
- the only other valid value is the constant\r
- <constant>CURLAUTH_NTLM</constant>, and has effect only when the\r
- client uses the HTTP 1.1 protocol.</para>\r
-\r
- <para>NB: CURL versions before 7.11.10 cannot use a proxy to\r
- communicate with https servers.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setRequestCompression</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setRequestCompression</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method defines whether the xml payload forming the\r
- request body will be sent to the server in compressed format, as per\r
- the HTTP specification. This is particularly useful for large\r
- request parameters and over slow network connections. Allowed values\r
- for <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',\r
- 'any' or null (with any meaning either gzip or deflate). Note that\r
- there is no automatic fallback mechanism in place for errors due to\r
- servers not supporting receiving compressed request bodies, so make\r
- sure that the particular server you are querying does accept\r
- compressed requests before turning it on.</para>\r
-\r
- <para>This requires the "zlib" extension to be enabled in your php\r
- install.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setSSLVerifyHost</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setSSLVerifyHost</function></funcdef>\r
-\r
- <paramdef><type>int</type><parameter>$i</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method defines whether connections made to XML-RPC\r
- backends via HTTPS should verify the remote host's SSL certificate's\r
- common name (CN). By default, only the existence of a CN is checked.\r
- <parameter><parameter>$i</parameter></parameter> should be an\r
- integer value; 0 to not check the CN at all, 1 to merely check for\r
- its existence, and 2 to check that the CN on the certificate matches\r
- the hostname that is being connected to.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>setSSLVerifyPeer</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>setSSLVerifyPeer</function></funcdef>\r
-\r
- <paramdef><type>bool</type><parameter>$i</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>This method defines whether connections made to XML-RPC\r
- backends via HTTPS should verify the remote host's SSL certificate,\r
- and cause the connection to fail if the cert verification fails.\r
- <parameter><parameter>$i</parameter></parameter> should be a boolean\r
- value. Default value: <constant>TRUE</constant>. To specify custom\r
- SSL certificates to validate the server with, use the\r
- <methodname>setCaCertificate</methodname> method.</para>\r
- </sect3>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Variables</title>\r
-\r
- <para>NB: direct manipulation of these variables is only recommended\r
- for advanced users.</para>\r
-\r
- <sect3>\r
- <title>no_multicall</title>\r
-\r
- <para>This member variable determines whether the multicall() method\r
- will try to take advantage of the system.multicall xmlrpc method to\r
- dispatch to the server an array of requests in a single http\r
- roundtrip or simply execute many consecutive http calls. Defaults to\r
- FALSE, but it will be enabled automatically on the first failure of\r
- execution of system.multicall.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>request_charset_encoding</title>\r
-\r
- <para>This is the charset encoding that will be used for serializing\r
- request sent by the client.</para>\r
-\r
- <para>If defaults to NULL, which means using US-ASCII and encoding\r
- all characters outside of the ASCII range using their xml character\r
- entity representation (this has the benefit that line end characters\r
- will not be mangled in the transfer, a CR-LF will be preserved as\r
- well as a singe LF).</para>\r
-\r
- <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>\r
- </sect3>\r
-\r
- <sect3 id="return-type" xreflabel="return_type">\r
- <title>return_type</title>\r
-\r
- <para>This member variable determines whether the value returned\r
- inside an xmlrpcresp object as results of calls to the send() and\r
- multicall() methods will be an xmlrpcval object, a plain php value\r
- or a raw xml string. Allowed values are 'xmlrpcvals' (the default),\r
- 'phpvals' and 'xml'. To allow the user to differentiate between a\r
- correct and a faulty response, fault responses will be returned as\r
- xmlrpcresp objects in any case. Note that the 'phpvals' setting will\r
- yield faster execution times, but some of the information from the\r
- original response will be lost. It will be e.g. impossible to tell\r
- whether a particular php string value was sent by the server as an\r
- xmlrpc string or base64 value.</para>\r
-\r
- <para>Example usage:</para>\r
-\r
- <programlisting language="php">\r
-$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server");\r
-$client->return_type = 'phpvals';\r
-$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));\r
-$resp = $client->send($message);\r
-if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();\r
-</programlisting>\r
-\r
- <para>For more details about usage of the 'xml' value, see Appendix\r
- A.</para>\r
- </sect3>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">\r
- <title>xmlrpcresp</title>\r
-\r
- <para>This class is used to contain responses to XML-RPC requests. A\r
- server method handler will construct an\r
- <classname>xmlrpcresp</classname> and pass it as a return value. This\r
- same value will be returned by the result of an invocation of the\r
- <function>send</function> method of the\r
- <classname>xmlrpc_client</classname> class.</para>\r
-\r
- <sect2>\r
- <title>Creation</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcresp</type>new\r
- <function>xmlrpcresp</function></funcdef>\r
-\r
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>xmlrpcresp</type>new\r
- <function>xmlrpcresp</function></funcdef>\r
-\r
- <paramdef><parameter>0</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>The first syntax is used when execution has happened without\r
- difficulty: <parameter>$xmlrpcval</parameter> is an\r
- <classname>xmlrpcval</classname> value with the result of the method\r
- execution contained in it. Alternatively it can be a string containing\r
- the xml serialization of the single xml-rpc value result of method\r
- execution.</para>\r
-\r
- <para>The second type of constructor is used in case of failure.\r
- <parameter>errcode</parameter> and <parameter>err_string</parameter>\r
- are used to provide indication of what has gone wrong. See <xref\r
- linkend="xmlrpc-server" /> for more information on passing error\r
- codes.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Methods</title>\r
-\r
- <sect3>\r
- <title>faultCode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>faultCode</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns the integer fault code return from the XML-RPC\r
- response. A zero value indicates success, any other value indicates\r
- a failure response.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>faultString</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>faultString</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns the human readable explanation of the fault indicated\r
- by <function>$resp->faultCode</function>().</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>value</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type><function>value</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns an <classname>xmlrpcval</classname> object containing\r
- the return value sent by the server. If the response's\r
- <function>faultCode</function> is non-zero then the value returned\r
- by this method should not be used (it may not even be an\r
- object).</para>\r
-\r
- <para>Note: if the xmlrpcresp instance in question has been created\r
- by an <classname>xmlrpc_client</classname> object whose\r
- <varname>return_type</varname> was set to 'phpvals', then a plain\r
- php value will be returned instead of an\r
- <classname>xmlrpcval</classname> object. If the\r
- <varname>return_type</varname> was set to 'xml', an xml string will\r
- be returned (see the return_type member var above for more\r
- details).</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>serialize</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>serialize</function></funcdef>\r
-\r
- <void />\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns an XML string representation of the response (xml\r
- prologue not included).</para>\r
- </sect3>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">\r
- <title>xmlrpc_server</title>\r
-\r
- <para>The implementation of this class has been kept as simple to use as\r
- possible. The constructor for the server basically does all the work.\r
- Here's a minimal example:</para>\r
-\r
- <programlisting language="php">\r
- function foo ($xmlrpcmsg) {\r
- ...\r
- return new xmlrpcresp($some_xmlrpc_val);\r
- }\r
-\r
- class bar {\r
- function foobar($xmlrpcmsg) {\r
- ...\r
- return new xmlrpcresp($some_xmlrpc_val);\r
- }\r
- }\r
-\r
- $s = new xmlrpc_server(\r
- array(\r
- "examples.myFunc1" => array("function" => "foo"),\r
- "examples.myFunc2" => array("function" => "bar::foobar"),\r
- ));\r
-</programlisting>\r
-\r
- <para>This performs everything you need to do with a server. The single\r
- constructor argument is an associative array from xmlrpc method names to\r
- php function names. The incoming request is parsed and dispatched to the\r
- relevant php function, which is responsible for returning a\r
- <classname>xmlrpcresp</classname> object, that will be serialized back\r
- to the caller.</para>\r
-\r
- <sect2>\r
- <title>Method handler functions</title>\r
-\r
- <para>Both php functions and class methods can be registered as xmlrpc\r
- method handlers.</para>\r
-\r
- <para>The synopsis of a method handler function is:</para>\r
-\r
- <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>\r
-\r
- <para>No text should be echoed 'to screen' by the handler function, or\r
- it will break the xml response sent back to the client. This applies\r
- also to error and warning messages that PHP prints to screen unless\r
- the appropriate parameters have been set in the php.in file. Another\r
- way to prevent echoing of errors inside the response and facilitate\r
- debugging is to use the server SetDebug method with debug level 3 (see\r
- below).</para>\r
-\r
- <para>Note that if you implement a method with a name prefixed by\r
- <code>system.</code> the handler function will be invoked by the\r
- server with two parameters, the first being the server itself and the\r
- second being the <classname>xmlrpcmsg</classname> object.</para>\r
-\r
- <para>The same php function can be registered as handler of multiple\r
- xmlrpc methods.</para>\r
-\r
- <para>Here is a more detailed example of what the handler function\r
- <function>foo</function> may do:</para>\r
-\r
- <programlisting language="php">\r
- function foo ($xmlrpcmsg) {\r
- global $xmlrpcerruser; // import user errcode base value\r
-\r
- $meth = $xmlrpcmsg->method(); // retrieve method name\r
- $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received\r
- $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value\r
-\r
- ...\r
-\r
- if ($err) {\r
- // this is an error condition\r
- return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1\r
- "There's a problem, Captain");\r
- } else {\r
- // this is a successful value being returned\r
- return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));\r
- }\r
- }\r
-</programlisting>\r
-\r
- <para>See <filename>server.php</filename> in this distribution for\r
- more examples of how to do this.</para>\r
-\r
- <para>Since release 2.0RC3 there is a new, even simpler way of\r
- registering php functions with the server. See section 5.7\r
- below</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>The dispatch map</title>\r
-\r
- <para>The first argument to the <function>xmlrpc_server</function>\r
- constructor is an array, called the <emphasis>dispatch map</emphasis>.\r
- In this array is the information the server needs to service the\r
- XML-RPC methods you define.</para>\r
-\r
- <para>The dispatch map takes the form of an associative array of\r
- associative arrays: the outer array has one entry for each method, the\r
- key being the method name. The corresponding value is another\r
- associative array, which can have the following members:</para>\r
-\r
- <itemizedlist>\r
- <listitem>\r
- <para><function><literal>function</literal></function> - this\r
- entry is mandatory. It must be either a name of a function in the\r
- global scope which services the XML-RPC method, or an array\r
- containing an instance of an object and a static method name (for\r
- static class methods the 'class::method' syntax is also\r
- supported).</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para><function><literal>signature</literal></function> - this\r
- entry is an array containing the possible signatures (see <xref\r
- linkend="signatures" />) for the method. If this entry is present\r
- then the server will check that the correct number and type of\r
- parameters have been sent for this method before dispatching\r
- it.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para><function><literal>docstring</literal></function> - this\r
- entry is a string containing documentation for the method. The\r
- documentation may contain HTML markup.</para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para><literal>signature_docs</literal> - this entry can be used\r
- to provide documentation for the single parameters. It must match\r
- in structure the 'signature' member. By default, only the\r
- <classname>documenting_xmlrpc_server</classname> class in the\r
- extras package will take advantage of this, since the\r
- "system.methodHelp" protocol does not support documenting method\r
- parameters individually.</para>\r
- </listitem>\r
- </itemizedlist>\r
-\r
- <para>Look at the <filename>server.php</filename> example in the\r
- distribution to see what a dispatch map looks like.</para>\r
- </sect2>\r
-\r
- <sect2 id="signatures" xreflabel="Signatures">\r
- <title>Method signatures</title>\r
-\r
- <para>A signature is a description of a method's return type and its\r
- parameter types. A method may have more than one signature.</para>\r
-\r
- <para>Within a server's dispatch map, each method has an array of\r
- possible signatures. Each signature is an array of types. The first\r
- entry is the return type. For instance, the method <programlisting\r
- language="php">string examples.getStateName(int)\r
-</programlisting> has the signature <programlisting language="php">array($xmlrpcString, $xmlrpcInt)\r
-</programlisting> and, assuming that it is the only possible signature for the\r
- method, it might be used like this in server creation: <programlisting\r
- language="php">\r
-$findstate_sig = array(array($xmlrpcString, $xmlrpcInt));\r
-\r
-$findstate_doc = 'When passed an integer between 1 and 51 returns the\r
-name of a US state, where the integer is the index of that state name\r
-in an alphabetic order.';\r
-\r
-$s = new xmlrpc_server( array(\r
- "examples.getStateName" => array(\r
- "function" => "findstate",\r
- "signature" => $findstate_sig,\r
- "docstring" => $findstate_doc\r
- )));\r
-</programlisting></para>\r
-\r
- <para>Note that method signatures do not allow to check nested\r
- parameters, e.g. the number, names and types of the members of a\r
- struct param cannot be validated.</para>\r
-\r
- <para>If a method that you want to expose has a definite number of\r
- parameters, but each of those parameters could reasonably be of\r
- multiple types, the array of acceptable signatures will easily grow\r
- into a combinatorial explosion. To avoid such a situation, the lib\r
- defines the global var <varname>$xmlrpcValue</varname>, which can be\r
- used in method signatures as a placeholder for 'any xmlrpc\r
- type':</para>\r
-\r
- <para><programlisting language="php">\r
-$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));\r
-\r
-$findstate_doc = 'Echoes back to the client the received value, regardless of its type';\r
-\r
-$s = new xmlrpc_server( array(\r
- "echoBack" => array(\r
- "function" => "echoback",\r
- "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter\r
- "docstring" => $echoback_doc\r
- )));\r
-</programlisting></para>\r
-\r
- <para>Methods <methodname>system.listMethods</methodname>,\r
- <methodname>system.methodHelp</methodname>,\r
- <methodname>system.methodSignature</methodname> and\r
- <methodname>system.multicall</methodname> are already defined by the\r
- server, and should not be reimplemented (see Reserved Methods\r
- below).</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Delaying the server response</title>\r
-\r
- <para>You may want to construct the server, but for some reason not\r
- fulfill the request immediately (security verification, for instance).\r
- If you omit to pass to the constructor the dispatch map or pass it a\r
- second argument of <literal>0</literal> this will have the desired\r
- effect. You can then use the <function>service()</function> method of\r
- the server class to service the request. For example:</para>\r
-\r
- <programlisting language="php">\r
-$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request\r
-\r
-// ... some code that does other stuff here\r
-\r
-$s->service();\r
-</programlisting>\r
-\r
- <para>Note that the <methodname>service</methodname> method will print\r
- the complete result payload to screen and send appropriate HTTP\r
- headers back to the client, but also return the response object. This\r
- permits further manipulation of the response.</para>\r
-\r
- <para>To prevent the server from sending HTTP headers back to the\r
- client, you can pass a second parameter with a value of\r
- <literal>TRUE</literal> to the <methodname>service</methodname>\r
- method. In this case, the response payload will be returned instead of\r
- the response object.</para>\r
-\r
- <para>Xmlrpc requests retrieved by other means than HTTP POST bodies\r
- can also be processed. For example:</para>\r
-\r
- <programlisting language="php">\r
-$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request\r
-\r
-// ... some code that does other stuff here, including setting dispatch map into server object\r
-\r
-$resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload\r
-\r
-// ... some code that does other stuff with xml response $resp here\r
-</programlisting>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Modifying the server behaviour</title>\r
-\r
- <para>A couple of methods / class variables are available to modify\r
- the behaviour of the server. The only way to take advantage of their\r
- existence is by usage of a delayed server response (see above)</para>\r
-\r
- <sect3>\r
- <title>setDebug()</title>\r
-\r
- <para>This function controls weather the server is going to echo\r
- debugging messages back to the client as comments in response body.\r
- Valid values: 0,1,2,3, with 1 being the default. At level 0, no\r
- debug info is returned to the client. At level 2, the complete\r
- client request is added to the response, as part of the xml\r
- comments. At level 3, a new PHP error handler is set when executing\r
- user functions exposed as server methods, and all non-fatal errors\r
- are trapped and added as comments into the response.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>allow_system_funcs</title>\r
-\r
- <para>Default_value: TRUE. When set to FALSE, disables support for\r
- <methodname>System.xxx</methodname> functions in the server. It\r
- might be useful e.g. if you do not wish the server to respond to\r
- requests to <methodname>System.ListMethods</methodname>.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>compress_response</title>\r
-\r
- <para>When set to TRUE, enables the server to take advantage of HTTP\r
- compression, otherwise disables it. Responses will be transparently\r
- compressed, but only when an xmlrpc-client declares its support for\r
- compression in the HTTP headers of the request.</para>\r
-\r
- <para>Note that the ZLIB php extension must be installed for this to\r
- work. If it is, <varname>compress_response</varname> will default to\r
- TRUE.</para>\r
- </sect3>\r
-\r
- <sect3>\r
- <title>response_charset_encoding</title>\r
-\r
- <para>Charset encoding to be used for response (only affects string\r
- values).</para>\r
-\r
- <para>If it can, the server will convert the generated response from\r
- internal_encoding to the intended one.</para>\r
-\r
- <para>Valid values are: a supported xml encoding (only UTF-8 and\r
- ISO-8859-1 at present, unless mbstring is enabled), null (leave\r
- charset unspecified in response and convert output stream to\r
- US_ASCII), 'default' (use xmlrpc library default as specified in\r
- xmlrpc.inc, convert output stream if needed), or 'auto' (use\r
- client-specified charset encoding or same as request if request\r
- headers do not specify it (unless request is US-ASCII: then use\r
- library default anyway).</para>\r
- </sect3>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>Fault reporting</title>\r
-\r
- <para>Fault codes for your servers should start at the value indicated\r
- by the global <literal>$xmlrpcerruser</literal> + 1.</para>\r
-\r
- <para>Standard errors returned by the server include:</para>\r
-\r
- <variablelist>\r
- <varlistentry>\r
- <term><literal>1</literal> <phrase>Unknown method</phrase></term>\r
-\r
- <listitem>\r
- <para>Returned if the server was asked to dispatch a method it\r
- didn't know about</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>2</literal> <phrase>Invalid return\r
- payload</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is actually generated by the client, not\r
- server, code, but signifies that a server returned something it\r
- couldn't understand. A more detailed error report is sometimes\r
- added onto the end of the phrase above.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>3</literal> <phrase>Incorrect\r
- parameters</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is generated when the server has signature(s)\r
- defined for a method, and the parameters passed by the client do\r
- not match any of signatures.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>4</literal> <phrase>Can't introspect: method\r
- unknown</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is generated by the builtin\r
- <function>system.*</function> methods when any kind of\r
- introspection is attempted on a method undefined by the\r
- server.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>5</literal> <phrase>Didn't receive 200 OK from\r
- remote server</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is generated by the client when a remote server\r
- doesn't return HTTP/1.1 200 OK in response to a request. A more\r
- detailed error report is added onto the end of the phrase\r
- above.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>6</literal> <phrase>No data received from\r
- server</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is generated by the client when a remote server\r
- returns HTTP/1.1 200 OK in response to a request, but no\r
- response body follows the HTTP headers.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>7</literal> <phrase>No SSL support compiled\r
- in</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is generated by the client when trying to send\r
- a request with HTTPS and the CURL extension is not available to\r
- PHP.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>8</literal> <phrase>CURL error</phrase></term>\r
-\r
- <listitem>\r
- <para>This error is generated by the client when trying to send\r
- a request with HTTPS and the HTTPS communication fails.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>9-14</literal> <phrase>multicall\r
- errors</phrase></term>\r
-\r
- <listitem>\r
- <para>These errors are generated by the server when something\r
- fails inside a system.multicall request.</para>\r
- </listitem>\r
- </varlistentry>\r
-\r
- <varlistentry>\r
- <term><literal>100-</literal> <phrase>XML parse\r
- errors</phrase></term>\r
-\r
- <listitem>\r
- <para>Returns 100 plus the XML parser error code for the fault\r
- that occurred. The <function>faultString</function> returned\r
- explains where the parse error was in the incoming XML\r
- stream.</para>\r
- </listitem>\r
- </varlistentry>\r
- </variablelist>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>'New style' servers</title>\r
-\r
- <para>In the same spirit of simplification that inspired the\r
- <varname>xmlrpc_client::return_type</varname> class variable, a new\r
- class variable has been added to the server class:\r
- <varname>functions_parameters_type</varname>. When set to 'phpvals',\r
- the functions registered in the server dispatch map will be called\r
- with plain php values as parameters, instead of a single xmlrpcmsg\r
- instance parameter. The return value of those functions is expected to\r
- be a plain php value, too. An example is worth a thousand\r
- words:<programlisting language="php">\r
- function foo($usr_id, $out_lang='en') {\r
- global $xmlrpcerruser;\r
-\r
- ...\r
-\r
- if ($someErrorCondition)\r
- return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');\r
- else\r
- return array(\r
- 'name' => 'Joe',\r
- 'age' => 27,\r
- 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')\r
- );\r
- }\r
-\r
- $s = new xmlrpc_server(\r
- array(\r
- "examples.myFunc" => array(\r
- "function" => "bar::foobar",\r
- "signature" => array(\r
- array($xmlrpcString, $xmlrpcInt),\r
- array($xmlrpcString, $xmlrpcInt, $xmlrpcString)\r
- )\r
- )\r
- ), false);\r
- $s->functions_parameters_type = 'phpvals';\r
- $s->service();\r
-</programlisting>There are a few things to keep in mind when using this\r
- simplified syntax:</para>\r
-\r
- <para>to return an xmlrpc error, the method handler function must\r
- return an instance of xmlrpcresp. There is no other way for the server\r
- to know when an error response should be served to the client;</para>\r
-\r
- <para>to return a base64 value, the method handler function must\r
- encode it on its own, creating an instance of an xmlrpcval\r
- object;</para>\r
-\r
- <para>the method handler function cannot determine the name of the\r
- xmlrpc method it is serving, unlike standard handler functions that\r
- can retrieve it from the message object;</para>\r
-\r
- <para>when receiving nested parameters, the method handler function\r
- has no way to distinguish a php string that was sent as base64 value\r
- from one that was sent as a string value;</para>\r
-\r
- <para>this has a direct consequence on the support of\r
- system.multicall: a method whose signature contains datetime or base64\r
- values will not be available to multicall calls;</para>\r
-\r
- <para>last but not least, the direct parsing of xml to php values is\r
- much faster than using xmlrpcvals, and allows the library to handle\r
- much bigger messages without allocating all available server memory or\r
- smashing PHP recursive call stack.</para>\r
- </sect2>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="globalvars">\r
- <title>Global variables</title>\r
-\r
- <para>Many global variables are defined in the xmlrpc.inc file. Some of\r
- those are meant to be used as constants (and modifying their value might\r
- cause unpredictable behaviour), while some others can be modified in your\r
- php scripts to alter the behaviour of the xml-rpc client and\r
- server.</para>\r
-\r
- <sect1>\r
- <title>"Constant" variables</title>\r
-\r
- <sect2>\r
- <title>$xmlrpcerruser</title>\r
-\r
- <para><fieldsynopsis>\r
- <varname>$xmlrpcerruser</varname>\r
-\r
- <initializer>800</initializer>\r
- </fieldsynopsis>The minimum value for errors reported by user\r
- implemented XML-RPC servers. Error numbers lower than that are\r
- reserved for library usage.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,\r
- $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,\r
- $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>\r
-\r
- <para>For convenience the strings representing the XML-RPC types have\r
- been encoded as global variables:<programlisting language="php">\r
-$xmlrpcI4="i4";\r
-$xmlrpcInt="int";\r
-$xmlrpcBoolean="boolean";\r
-$xmlrpcDouble="double";\r
-$xmlrpcString="string";\r
-$xmlrpcDateTime="dateTime.iso8601";\r
-$xmlrpcBase64="base64";\r
-$xmlrpcArray="array";\r
-$xmlrpcStruct="struct";\r
-$xmlrpcValue="undefined";\r
-$xmlrpcNull="null";\r
-</programlisting></para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,\r
- $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,\r
- $xmlEntities, $xmlrpcs_capabilities</title>\r
-\r
- <para>Reserved for internal usage.</para>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>Variables whose value can be modified</title>\r
-\r
- <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">\r
- <title xreflabel="">xmlrpc_defencoding</title>\r
-\r
- <fieldsynopsis>\r
- <varname>$xmlrpc_defencoding</varname>\r
-\r
- <initializer>"UTF8"</initializer>\r
- </fieldsynopsis>\r
-\r
- <para>This variable defines the character set encoding that will be\r
- used by the xml-rpc client and server to decode the received messages,\r
- when a specific charset declaration is not found (in the messages sent\r
- non-ascii chars are always encoded using character references, so that\r
- the produced xml is valid regardless of the charset encoding\r
- assumed).</para>\r
-\r
- <para>Allowed values: <literal>"UTF8"</literal>,\r
- <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>\r
-\r
- <para>Note that the appropriate RFC actually mandates that XML\r
- received over HTTP without indication of charset encoding be treated\r
- as US-ASCII, but many servers and clients 'in the wild' violate the\r
- standard, and assume the default encoding is UTF-8.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>xmlrpc_internalencoding</title>\r
-\r
- <para><fieldsynopsis>\r
- <varname>$xmlrpc_internalencoding</varname>\r
-\r
- <initializer>"ISO-8859-1"</initializer>\r
- </fieldsynopsis>This variable defines the character set encoding\r
- that the library uses to transparently encode into valid XML the\r
- xml-rpc values created by the user and to re-encode the received\r
- xml-rpc values when it passes them to the PHP application. It only\r
- affects xml-rpc values of string type. It is a separate value from\r
- xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded\r
- on-the-wire in US-ASCII and process them as UTF-8. It defaults to the\r
- character set used internally by PHP (unless you are running an\r
- MBString-enabled installation), so you should change it only in\r
- special situations, if e.g. the string values exchanged in the xml-rpc\r
- messages are directly inserted into / fetched from a database\r
- configured to return UTF8 encoded strings to PHP. Example\r
- usage:</para>\r
-\r
- <para><programlisting language="php">\r
-<?php\r
-\r
-include('xmlrpc.inc');\r
-$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above\r
-$v = new xmlrpcval('κόÏ\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'\r
-</programlisting></para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>xmlrpcName</title>\r
-\r
- <para><fieldsynopsis>\r
- <varname>$xmlrpcName</varname>\r
-\r
- <initializer>"XML-RPC for PHP"</initializer>\r
- </fieldsynopsis>The string representation of the name of the XML-RPC\r
- for PHP library. It is used by the client for building the User-Agent\r
- HTTP header that is sent with every request to the server. You can\r
- change its value if you need to customize the User-Agent\r
- string.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>xmlrpcVersion</title>\r
-\r
- <para><fieldsynopsis>\r
- <varname>$xmlrpcVersion</varname>\r
-\r
- <initializer>"2.2"</initializer>\r
- </fieldsynopsis>The string representation of the version number of\r
- the XML-RPC for PHP library in use. It is used by the client for\r
- building the User-Agent HTTP header that is sent with every request to\r
- the server. You can change its value if you need to customize the\r
- User-Agent string.</para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>xmlrpc_null_extension</title>\r
-\r
- <para>When set to <constant>TRUE</constant>, the lib will enable\r
- support for the <NIL/> xmlrpc value, as per the extension to the\r
- standard proposed here. This means that <NIL/> tags will be\r
- parsed as valid xmlrpc, and the corresponding xmlrpcvals will return\r
- "null" for <methodname>scalarTyp()</methodname>.</para>\r
- </sect2>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="helpers">\r
- <title>Helper functions</title>\r
-\r
- <para>XML-RPC for PHP contains some helper functions which you can use to\r
- make processing of XML-RPC requests easier.</para>\r
-\r
- <sect1>\r
- <title>Date functions</title>\r
-\r
- <para>The XML-RPC specification has this to say on dates:</para>\r
-\r
- <blockquote>\r
- <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be\r
- specified by the server in its documentation what assumptions it makes\r
- about timezones.</para>\r
- </blockquote>\r
-\r
- <para>Unfortunately, this means that date processing isn't\r
- straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't\r
- use the timezone specifier.</para>\r
-\r
- <para>We strongly recommend that in every case where you pass dates in\r
- XML-RPC calls, you use UTC (GMT) as your timezone. Most computer\r
- languages include routines for handling GMT times natively, and you\r
- won't have to translate between timezones.</para>\r
-\r
- <para>For more information about dates, see <ulink\r
- url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right\r
- Format for Dates</ulink>, which has a handy link to a PDF of the ISO\r
- 8601 specification. Note that XML-RPC uses exactly one of the available\r
- representations: CCYYMMDDTHH:MM:SS.</para>\r
-\r
- <sect2 id="iso8601encode" xreflabel="iso8601_encode()">\r
- <title>iso8601_encode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>iso8601_encode</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>\r
-\r
- <paramdef\r
- choice="opt"><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns an ISO 8601 formatted date generated from the UNIX\r
- timestamp <parameter>$time_t</parameter>, as returned by the PHP\r
- function <function>time()</function>.</para>\r
-\r
- <para>The argument <parameter>$utc</parameter> can be omitted, in\r
- which case it defaults to <literal>0</literal>. If it is set to\r
- <literal>1</literal>, then the function corrects the time passed in\r
- for UTC. Example: if you're in the GMT-6:00 timezone and set\r
- <parameter>$utc</parameter>, you will receive a date representation\r
- six hours ahead of your local time.</para>\r
-\r
- <para>The included demo program <filename>vardemo.php</filename>\r
- includes a demonstration of this function.</para>\r
- </sect2>\r
-\r
- <sect2 id="iso8601decode" xreflabel="iso8601_decode()">\r
- <title>iso8601_decode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>int</type><function>iso8601_decode</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>\r
-\r
- <paramdef><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date\r
- string passed in. If <parameter>$utc</parameter> is\r
- <literal>1</literal> then <parameter>$isoString</parameter> is assumed\r
- to be in the UTC timezone, and thus the result is also UTC: otherwise,\r
- the timezone is assumed to be your local timezone and you receive a\r
- local timestamp.</para>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="arrayuse">\r
- <title>Easy use with nested PHP values</title>\r
-\r
- <para>Dan Libby was kind enough to contribute two helper functions that\r
- make it easier to translate to and from PHP values. This makes it easier\r
- to deal with complex structures. At the moment support is limited to\r
- <type>int</type>, <type>double</type>, <type>string</type>,\r
- <type>array</type>, <type>datetime</type> and <type>struct</type>\r
- datatypes; note also that all PHP arrays are encoded as structs, except\r
- arrays whose keys are integer numbers starting with 0 and incremented by\r
- 1.</para>\r
-\r
- <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>\r
-\r
- <sect2 id="phpxmlrpcdecode">\r
- <title>php_xmlrpc_decode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>mixed</type><function>php_xmlrpc_decode</function></funcdef>\r
-\r
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>\r
-\r
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>array</type><function>php_xmlrpc_decode</function></funcdef>\r
-\r
- <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$options</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns a native PHP value corresponding to the values found in\r
- the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,\r
- translated into PHP types. Base-64 and datetime values are\r
- automatically decoded to strings.</para>\r
-\r
- <para>In the second form, returns an array containing the parameters\r
- of the given\r
- <parameter><classname>xmlrpcmsg</classname>_val</parameter>, decoded\r
- to php types.</para>\r
-\r
- <para>The <parameter>options</parameter> parameter is optional. If\r
- specified, it must consist of an array of options to be enabled in the\r
- decoding process. At the moment the only valid option is\r
- <symbol>decode_php_objs</symbol>. When it is set, php objects that\r
- have been converted to xml-rpc structs using the\r
- <function>php_xmlrpc_encode</function> function and a corresponding\r
- encoding option will be converted back into object values instead of\r
- arrays (provided that the class definition is available at\r
- reconstruction time).</para>\r
-\r
- <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take\r
- extreme care before enabling the <symbol>decode_php_objs</symbol>\r
- option: when php objects are rebuilt from the received xml, their\r
- constructor function will be silently invoked. This means that you are\r
- allowing the remote end to trigger execution of uncontrolled PHP code\r
- on your server, opening the door to code injection exploits. Only\r
- enable this option when you have complete trust of the remote\r
- server/client.</para>\r
-\r
- <para>Example:<programlisting language="php">\r
-// wrapper to expose an existing php function as xmlrpc method handler\r
-function foo_wrapper($m)\r
-{\r
- $params = php_xmlrpc_decode($m);\r
- $retval = call_user_func_array('foo', $params);\r
- return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string\r
-}\r
-\r
-$s = new xmlrpc_server(array(\r
- "examples.myFunc1" => array(\r
- "function" => "foo_wrapper",\r
- "signatures" => ...\r
- )));\r
-</programlisting></para>\r
- </sect2>\r
-\r
- <sect2 id="phpxmlrpcencode">\r
- <title>php_xmlrpc_encode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type><function>php_xmlrpc_encode</function></funcdef>\r
-\r
- <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>\r
-\r
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Returns an <type>xmlrpcval</type> object populated with the PHP\r
- values in <parameter>$phpval</parameter>. Works recursively on arrays\r
- and objects, encoding numerically indexed php arrays into array-type\r
- xmlrpcval objects and non numerically indexed php arrays into\r
- struct-type xmlrpcval objects. Php objects are encoded into\r
- struct-type xmlrpcvals, excepted for php values that are already\r
- instances of the xmlrpcval class or descendants thereof, which will\r
- not be further encoded. Note that there's no support for encoding php\r
- values into base-64 values. Encoding of date-times is optionally\r
- carried on on php strings with the correct format.</para>\r
-\r
- <para>The <parameter>options</parameter> parameter is optional. If\r
- specified, it must consist of an array of options to be enabled in the\r
- encoding process. At the moment the only valid options are\r
- <symbol>encode_php_objs</symbol> and\r
- <symbol>auto_dates</symbol>.</para>\r
-\r
- <para>The first will enable the creation of 'particular' xmlrpcval\r
- objects out of php objects, that add a "php_class" xml attribute to\r
- their serialized representation. This attribute allows the function\r
- php_xmlrpc_decode to rebuild the native php objects (provided that the\r
- same class definition exists on both sides of the\r
- communication)</para>\r
-\r
- <para>Example:<programlisting language="php">\r
-// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values\r
-$val = php_xmlrpc_encode(array(\r
- 'first struct_element: an int' => 666,\r
- 'second: an array' => array ('apple', 'orange', 'banana'),\r
- 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),\r
- 'fourth: a datetime' => '20060107T01:53:00'\r
- ), array('auto_dates'));\r
-</programlisting></para>\r
- </sect2>\r
-\r
- <sect2>\r
- <title>php_xmlrpc_decode_xml</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval | xmlrpcresp |\r
- xmlrpcmsg</type><function>php_xmlrpc_decode_xml</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$xml</parameter></paramdef>\r
-\r
- <paramdef><type>array</type><parameter>$options</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Decodes the xml representation of either an xmlrpc request,\r
- response or single value, returning the corresponding php-xmlrpc\r
- object, or <literal>FALSE</literal> in case of an error.</para>\r
-\r
- <para>The <parameter>options</parameter> parameter is optional. If\r
- specified, it must consist of an array of options to be enabled in the\r
- decoding process. At the moment, no option is supported.</para>\r
-\r
- <para>Example:<programlisting language="php">\r
-$text = '<value><array><data><value>Hello world</value></data></array></value>';\r
-$val = php_xmlrpc_decode_xml($text);\r
-if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';\r
-</programlisting></para>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>Automatic conversion of php functions into xmlrpc methods (and\r
- vice versa)</title>\r
-\r
- <para>For the extremely lazy coder, helper functions have been added\r
- that allow to convert a php function into an xmlrpc method, and a\r
- remotely exposed xmlrpc method into a local php function - or a set of\r
- methods into a php class. Note that these comes with many caveat.</para>\r
-\r
- <sect2>\r
- <title>wrap_xmlrpc_method</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>\r
-\r
- <paramdef>$client</paramdef>\r
-\r
- <paramdef>$methodname</paramdef>\r
-\r
- <paramdef>$extra_options</paramdef>\r
- </funcprototype>\r
-\r
- <funcprototype>\r
- <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>\r
-\r
- <paramdef>$client</paramdef>\r
-\r
- <paramdef>$methodname</paramdef>\r
-\r
- <paramdef>$signum</paramdef>\r
-\r
- <paramdef>$timeout</paramdef>\r
-\r
- <paramdef>$protocol</paramdef>\r
-\r
- <paramdef>$funcname</paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Given an xmlrpc server and a method name, creates a php wrapper\r
- function that will call the remote method and return results using\r
- native php types for both params and results. The generated php\r
- function will return an xmlrpcresp object for failed xmlrpc\r
- calls.</para>\r
-\r
- <para>The second syntax is deprecated, and is listed here only for\r
- backward compatibility.</para>\r
-\r
- <para>The server must support the\r
- <methodname>system.methodSignature</methodname> xmlrpc method call for\r
- this function to work.</para>\r
-\r
- <para>The <parameter>client</parameter> param must be a valid\r
- xmlrpc_client object, previously created with the address of the\r
- target xmlrpc server, and to which the preferred communication options\r
- have been set.</para>\r
-\r
- <para>The optional parameters can be passed as array key,value pairs\r
- in the <parameter>extra_options</parameter> param.</para>\r
-\r
- <para>The <parameter>signum</parameter> optional param has the purpose\r
- of indicating which method signature to use, if the given server\r
- method has multiple signatures (defaults to 0).</para>\r
-\r
- <para>The <parameter>timeout</parameter> and\r
- <parameter>protocol</parameter> optional params are the same as in the\r
- <methodname>xmlrpc_client::send()</methodname> method.</para>\r
-\r
- <para>If set, the optional <parameter>new_function_name</parameter>\r
- parameter indicates which name should be used for the generated\r
- function. In case it is not set the function name will be\r
- auto-generated.</para>\r
-\r
- <para>If the <literal>return_source</literal> optional parameter is\r
- set, the function will return the php source code to build the wrapper\r
- function, instead of evaluating it (useful to save the code and use it\r
- later as stand-alone xmlrpc client).</para>\r
-\r
- <para>If the <literal>encode_php_objs</literal> optional parameter is\r
- set, instances of php objects later passed as parameters to the newly\r
- created function will receive a 'special' treatment that allows the\r
- server to rebuild them as php objects instead of simple arrays. Note\r
- that this entails using a "slightly augmented" version of the xmlrpc\r
- protocol (ie. using element attributes), which might not be understood\r
- by xmlrpc servers implemented using other libraries.</para>\r
-\r
- <para>If the <literal>decode_php_objs</literal> optional parameter is\r
- set, instances of php objects that have been appropriately encoded by\r
- the server using a coordinate option will be deserialized as php\r
- objects instead of simple arrays (the same class definition should be\r
- present server side and client side).</para>\r
-\r
- <para><emphasis>Note that this might pose a security risk</emphasis>,\r
- since in order to rebuild the object instances their constructor\r
- method has to be invoked, and this means that the remote server can\r
- trigger execution of unforeseen php code on the client: not really a\r
- code injection, but almost. Please enable this option only when you\r
- trust the remote server.</para>\r
-\r
- <para>In case of an error during generation of the wrapper function,\r
- FALSE is returned, otherwise the name (or source code) of the new\r
- function.</para>\r
-\r
- <para>Known limitations: server must support\r
- <methodname>system.methodsignature</methodname> for the wanted xmlrpc\r
- method; for methods that expose multiple signatures, only one can be\r
- picked; for remote calls with nested xmlrpc params, the caller of the\r
- generated php function has to encode on its own the params passed to\r
- the php function if these are structs or arrays whose (sub)members\r
- include values of type base64.</para>\r
-\r
- <para>Note: calling the generated php function 'might' be slow: a new\r
- xmlrpc client is created on every invocation and an xmlrpc-connection\r
- opened+closed. An extra 'debug' param is appended to the parameter\r
- list of the generated php function, useful for debugging\r
- purposes.</para>\r
-\r
- <para>Example usage:</para>\r
-\r
- <programlisting language="php">\r
-$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');\r
-\r
-$function = wrap_xmlrpc_method($client, 'examples.getStateName');\r
-\r
-if (!$function)\r
- die('Cannot introspect remote method');\r
-else {\r
- $stateno = 15;\r
- $statename = $function($a);\r
- if (is_a($statename, 'xmlrpcresp')) // call failed\r
- {\r
- echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';\r
- $function($a, true);\r
- }\r
- else\r
- echo "OK, state nr. $stateno is $statename";\r
-}\r
-</programlisting>\r
- </sect2>\r
-\r
- <sect2 id="wrap_php_function">\r
- <title>wrap_php_function</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>array</type><function>wrap_php_function</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>\r
-\r
- <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>\r
-\r
- <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Given a user-defined PHP function, create a PHP 'wrapper'\r
- function that can be exposed as xmlrpc method from an xmlrpc_server\r
- object and called from remote clients, and return the appropriate\r
- definition to be added to a server's dispatch map.</para>\r
-\r
- <para>The optional <parameter>$wrapper_function_name</parameter>\r
- specifies the name that will be used for the auto-generated\r
- function.</para>\r
-\r
- <para>Since php is a typeless language, to infer types of input and\r
- output parameters, it relies on parsing the javadoc-style comment\r
- block associated with the given function. Usage of xmlrpc native types\r
- (such as datetime.dateTime.iso8601 and base64) in the docblock @param\r
- tag is also allowed, if you need the php function to receive/send data\r
- in that particular format (note that base64 encoding/decoding is\r
- transparently carried out by the lib, while datetime vals are passed\r
- around as strings).</para>\r
-\r
- <para>Known limitations: requires PHP 5.0.3 +; only works for\r
- user-defined functions, not for PHP internal functions (reflection\r
- does not support retrieving number/type of params for those); the\r
- wrapped php function will not be able to programmatically return an\r
- xmlrpc error response.</para>\r
-\r
- <para>If the <literal>return_source</literal> optional parameter is\r
- set, the function will return the php source code to build the wrapper\r
- function, instead of evaluating it (useful to save the code and use it\r
- later in a stand-alone xmlrpc server). It will be in the stored in the\r
- <literal>source</literal> member of the returned array.</para>\r
-\r
- <para>If the <literal>suppress_warnings</literal> optional parameter\r
- is set, any runtime warning generated while processing the\r
- user-defined php function will be catched and not be printed in the\r
- generated xml response.</para>\r
-\r
- <para>If the <parameter>extra_options</parameter> array contains the\r
- <literal>encode_php_objs</literal> value, wrapped functions returning\r
- php objects will generate "special" xmlrpc responses: when the xmlrpc\r
- decoding of those responses is carried out by this same lib, using the\r
- appropriate param in php_xmlrpc_decode(), the objects will be\r
- rebuilt.</para>\r
-\r
- <para>In short: php objects can be serialized, too (except for their\r
- resource members), using this function. Other libs might choke on the\r
- very same xml that will be generated in this case (i.e. it has a\r
- nonstandard attribute on struct element tags)</para>\r
-\r
- <para>If the <literal>decode_php_objs</literal> optional parameter is\r
- set, instances of php objects that have been appropriately encoded by\r
- the client using a coordinate option will be deserialized and passed\r
- to the user function as php objects instead of simple arrays (the same\r
- class definition should be present server side and client\r
- side).</para>\r
-\r
- <para><emphasis>Note that this might pose a security risk</emphasis>,\r
- since in order to rebuild the object instances their constructor\r
- method has to be invoked, and this means that the remote client can\r
- trigger execution of unforeseen php code on the server: not really a\r
- code injection, but almost. Please enable this option only when you\r
- trust the remote clients.</para>\r
-\r
- <para>Example usage:</para>\r
-\r
- <para><programlisting language="php">/**\r
-* State name from state number decoder. NB: do NOT remove this comment block.\r
-* @param integer $stateno the state number\r
-* @return string the name of the state (or error description)\r
-*/\r
-function findstate($stateno)\r
-{\r
- global $stateNames;\r
- if (isset($stateNames[$stateno-1]))\r
- {\r
- return $stateNames[$stateno-1];\r
- }\r
- else\r
- {\r
- return "I don't have a state for the index '" . $stateno . "'";\r
- }\r
-}\r
-\r
-// wrap php function, build xmlrpc server\r
-$methods = array();\r
-$findstate_sig = wrap_php_function('findstate');\r
-if ($findstate_sig)\r
- $methods['examples.getStateName'] = $findstate_sig;\r
-$srv = new xmlrpc_server($methods);\r
-</programlisting></para>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="deprecated">\r
- <title>Functions removed from the library</title>\r
-\r
- <para>The following two functions have been deprecated in version 1.1 of\r
- the library, and removed in version 2, in order to avoid conflicts with\r
- the EPI xml-rpc library, which also defines two functions with the same\r
- names.</para>\r
-\r
- <para>To ease the transition to the new naming scheme and avoid breaking\r
- existing implementations, the following scheme has been adopted:\r
- <itemizedlist>\r
- <listitem>\r
- <para>If EPI-XMLRPC is not active in the current PHP installation,\r
- the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to\r
- <literal>'0'</literal></para>\r
- </listitem>\r
-\r
- <listitem>\r
- <para>If EPI-XMLRPC is active in the current PHP installation, the\r
- constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to\r
- <literal>'1'</literal></para>\r
- </listitem>\r
- </itemizedlist></para>\r
-\r
- <para>The following documentation is kept for historical\r
- reference:</para>\r
-\r
- <sect2 id="xmlrpcdecode">\r
- <title>xmlrpc_decode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>mixed</type><function>xmlrpc_decode</function></funcdef>\r
-\r
- <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Alias for php_xmlrpc_decode.</para>\r
- </sect2>\r
-\r
- <sect2 id="xmlrpcencode">\r
- <title>xmlrpc_encode</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>xmlrpcval</type><function>xmlrpc_encode</function></funcdef>\r
-\r
- <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Alias for php_xmlrpc_encode.</para>\r
- </sect2>\r
- </sect1>\r
-\r
- <sect1 id="debugging">\r
- <title>Debugging aids</title>\r
-\r
- <sect2>\r
- <title>xmlrpc_debugmsg</title>\r
-\r
- <funcsynopsis>\r
- <funcprototype>\r
- <funcdef><type>void</type><function>xmlrpc_debugmsg</function></funcdef>\r
-\r
- <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>\r
- </funcprototype>\r
- </funcsynopsis>\r
-\r
- <para>Sends the contents of <parameter>$debugstring</parameter> in XML\r
- comments in the server return payload. If a PHP client has debugging\r
- turned on, the user will be able to see server debug\r
- information.</para>\r
-\r
- <para>Use this function in your methods so you can pass back\r
- diagnostic information. It is only available from\r
- <filename>xmlrpcs.inc</filename>.</para>\r
- </sect2>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="reserved" xreflabel="Reserved methods">\r
- <title>Reserved methods</title>\r
-\r
- <para>In order to extend the functionality offered by XML-RPC servers\r
- without impacting on the protocol, reserved methods are supported in this\r
- release.</para>\r
-\r
- <para>All methods starting with <function>system.</function> are\r
- considered reserved by the server. PHP for XML-RPC itself provides four\r
- special methods, detailed in this chapter.</para>\r
-\r
- <para>Note that all server objects will automatically respond to clients\r
- querying these methods, unless the property\r
- <property>allow_system_funcs</property> has been set to\r
- <constant>false</constant> before calling the\r
- <methodname>service()</methodname> method. This might pose a security risk\r
- if the server is exposed to public access, e.g. on the internet.</para>\r
-\r
- <sect1>\r
- <title>system.getCapabilities</title>\r
-\r
- <para></para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>system.listMethods</title>\r
-\r
- <para>This method may be used to enumerate the methods implemented by\r
- the XML-RPC server.</para>\r
-\r
- <para>The <function>system.listMethods</function> method requires no\r
- parameters. It returns an array of strings, each of which is the name of\r
- a method implemented by the server.</para>\r
- </sect1>\r
-\r
- <sect1 id="sysmethodsig">\r
- <title>system.methodSignature</title>\r
-\r
- <para>This method takes one parameter, the name of a method implemented\r
- by the XML-RPC server.</para>\r
-\r
- <para>It returns an array of possible signatures for this method. A\r
- signature is an array of types. The first of these types is the return\r
- type of the method, the rest are parameters.</para>\r
-\r
- <para>Multiple signatures (i.e. overloading) are permitted: this is the\r
- reason that an array of signatures are returned by this method.</para>\r
-\r
- <para>Signatures themselves are restricted to the top level parameters\r
- expected by a method. For instance if a method expects one array of\r
- structs as a parameter, and it returns a string, its signature is simply\r
- "string, array". If it expects three integers, its signature is "string,\r
- int, int, int".</para>\r
-\r
- <para>For parameters that can be of more than one type, the "undefined"\r
- string is supported.</para>\r
-\r
- <para>If no signature is defined for the method, a not-array value is\r
- returned. Therefore this is the way to test for a non-signature, if\r
- <parameter>$resp</parameter> below is the response object from a method\r
- call to <function>system.methodSignature</function>:</para>\r
-\r
- <programlisting language="php">\r
-$v = $resp->value();\r
-if ($v->kindOf() != "array") {\r
- // then the method did not have a signature defined\r
-}\r
-</programlisting>\r
-\r
- <para>See the <filename>introspect.php</filename> demo included in this\r
- distribution for an example of using this method.</para>\r
- </sect1>\r
-\r
- <sect1 id="sysmethhelp">\r
- <title>system.methodHelp</title>\r
-\r
- <para>This method takes one parameter, the name of a method implemented\r
- by the XML-RPC server.</para>\r
-\r
- <para>It returns a documentation string describing the use of that\r
- method. If no such string is available, an empty string is\r
- returned.</para>\r
-\r
- <para>The documentation string may contain HTML markup.</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>system.multicall</title>\r
-\r
- <para>This method takes one parameter, an array of 'request' struct\r
- types. Each request struct must contain a\r
- <parameter>methodName</parameter> member of type string and a\r
- <parameter>params</parameter> member of type array, and corresponds to\r
- the invocation of the corresponding method.</para>\r
-\r
- <para>It returns a response of type array, with each value of the array\r
- being either an error struct (containing the faultCode and faultString\r
- members) or the successful response value of the corresponding single\r
- method call.</para>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="examples" xreflabel="Examples">\r
- <title>Examples</title>\r
-\r
- <para>The best examples are to be found in the sample files included with\r
- the distribution. Some are included here.</para>\r
-\r
- <sect1 id="statename">\r
- <title>XML-RPC client: state name query</title>\r
-\r
- <para>Code to get the corresponding state name from a number (1-50) from\r
- the demo server available on SourceForge</para>\r
-\r
- <programlisting language="php">\r
- $m = new xmlrpcmsg('examples.getStateName',\r
- array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));\r
- $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);\r
- $r = $c->send($m);\r
- if (!$r->faultCode()) {\r
- $v = $r->value();\r
- print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .\r
- htmlentities($v->scalarval()) . "<BR>";\r
- print "<HR>I got this value back<BR><PRE>" .\r
- htmlentities($r->serialize()) . "</PRE><HR>\n";\r
- } else {\r
- print "Fault <BR>";\r
- print "Code: " . htmlentities($r->faultCode()) . "<BR>" .\r
- "Reason: '" . htmlentities($r->faultString()) . "'<BR>";\r
- }\r
-</programlisting>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>Executing a multicall call</title>\r
-\r
- <para>To be documented...</para>\r
- </sect1>\r
- </chapter>\r
-\r
- <chapter id="faq">\r
- <title>Frequently Asked Questions</title>\r
-\r
- <sect1>\r
- <title>How to send custom XML as payload of a method call</title>\r
-\r
- <para>Unfortunately, at the time the XML-RPC spec was designed, support\r
- for namespaces in XML was not as ubiquitous as it is now. As a\r
- consequence, no support was provided in the protocol for embedding XML\r
- elements from other namespaces into an xmlrpc request.</para>\r
-\r
- <para>To send an XML "chunk" as payload of a method call or response,\r
- two options are available: either send the complete XML block as a\r
- string xmlrpc value, or as a base64 value. Since the '<' character in\r
- string values is encoded as '&lt;' in the xml payload of the method\r
- call, the XML string will not break the surrounding xmlrpc, unless\r
- characters outside of the assumed character set are used. The second\r
- method has the added benefits of working independently of the charset\r
- encoding used for the xml to be transmitted, and preserving exactly\r
- whitespace, whilst incurring in some extra message length and cpu load\r
- (for carrying out the base64 encoding/decoding).</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>Is there any limitation on the size of the requests / responses\r
- that can be successfully sent?</title>\r
-\r
- <para>Yes. But I have no hard figure to give; it most likely will depend\r
- on the version of PHP in usage and its configuration.</para>\r
-\r
- <para>Keep in mind that this library is not optimized for speed nor for\r
- memory usage. Better alternatives exist when there are strict\r
- requirements on throughput or resource usage, such as the php native\r
- xmlrpc extension (see the PHP manual for more information).</para>\r
-\r
- <para>Keep in mind also that HTTP is probably not the best choice in\r
- such a situation, and XML is a deadly enemy. CSV formatted data over\r
- socket would be much more efficient.</para>\r
-\r
- <para>If you really need to move a massive amount of data around, and\r
- you are crazy enough to do it using phpxmlrpc, your best bet is to\r
- bypass usage of the xmlrpcval objects, at least in the decoding phase,\r
- and have the server (or client) object return to the calling function\r
- directly php values (see <varname>xmlrpc_client::return_type</varname>\r
- and <varname>xmlrpc_server::functions_parameters_type</varname> for more\r
- details).</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>My server (client) returns an error whenever the client (server)\r
- returns accented characters</title>\r
-\r
- <para>To be documented...</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>My php error log is getting full of "deprecated" errors on\r
- different lines of xmlrpc.inc and xmlrpcs.inc</title>\r
-\r
- <para>This happens when the PHP in usage is version 5, and the error\r
- reporting level is set to include <constant>E_STRICT</constant> errors.\r
- Since the main development platform of the library remains (for the time\r
- being) PHP 4, there are no plans to fix this asap. The best workaround\r
- is to set the error reporting level to <constant>E_ALL ^\r
- E_STRICT</constant>.</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>How to enable long-lasting method calls</title>\r
-\r
- <para>To be documented...</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>My client returns "XML-RPC Fault #2: Invalid return payload:\r
- enable debugging to examine incoming payload": what should I do?</title>\r
-\r
- <para>The response you are seeing is a default error response that the\r
- client object returns to the php application when the server did not\r
- respond to the call with a valid xmlrpc response.</para>\r
-\r
- <para>The most likely cause is that you are not using the correct URL\r
- when creating the client object, or you do not have appropriate access\r
- rights to the web page you are requesting, or some other common http\r
- misconfiguration.</para>\r
-\r
- <para>To find out what the server is really returning to your client,\r
- you have to enable the debug mode of the client, using\r
- $client->setdebug(1);</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>How can I save to a file the xml of the xmlrpc responses received\r
- from servers?</title>\r
-\r
- <para>If what you need is to save the responses received from the server\r
- as xml, you have two options:</para>\r
-\r
- <para>1- use the serialize() method on the response object.</para>\r
-\r
- <programlisting language="php">\r
-$resp = $client->send($msg);\r
-if (!$resp->faultCode())\r
- $data_to_be_saved = $resp->serialize();\r
-</programlisting>\r
-\r
- <para>Note that this will not be 100% accurate, since the xml generated\r
- by the response object can be different from the xml received,\r
- especially if there is some character set conversion involved, or such\r
- (eg. if you receive an empty string tag as <string/>, serialize()\r
- will output <string></string>), or if the server sent back\r
- as response something invalid (in which case the xml generated client\r
- side using serialize() will correspond to the error response generated\r
- internally by the lib).</para>\r
-\r
- <para>2 - set the client object to return the raw xml received instead\r
- of the decoded objects:</para>\r
-\r
- <programlisting language="php">\r
-$client = new xmlrpc_client($url);\r
-$client->return_type = 'xml';\r
-$resp = $client->send($msg);\r
-if (!$resp->faultCode())\r
- $data_to_be_saved = $resp->value();\r
-</programlisting>\r
-\r
- <para>Note that using this method the xml response response will not be\r
- parsed at all by the library, only the http communication protocol will\r
- be checked. This means that xmlrpc responses sent by the server that\r
- would have generated an error response on the client (eg. malformed xml,\r
- responses that have faultcode set, etc...) now will not be flagged as\r
- invalid, and you might end up saving not valid xml but random\r
- junk...</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>Can I use the ms windows character set?</title>\r
-\r
- <para>If the data your application is using comes from a Microsoft\r
- application, there are some chances that the character set used to\r
- encode it is CP1252 (the same might apply to data received from an\r
- external xmlrpc server/client, but it is quite rare to find xmlrpc\r
- toolkits that encode to CP1252 instead of UTF8). It is a character set\r
- which is "almost" compatible with ISO 8859-1, but for a few extra\r
- characters.</para>\r
-\r
- <para>PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.\r
- The net result of this situation is that those extra characters will not\r
- be properly encoded, and will be received at the other end of the\r
- XML-RPC tranmission as "garbled data". Unfortunately the library cannot\r
- provide real support for CP1252 because of limitations in the PHP 4 xml\r
- parser. Luckily, we tried our best to support this character set anyway,\r
- and, since version 2.2.1, there is some form of support, left commented\r
- in the code.</para>\r
-\r
- <para>To properly encode outgoing data that is natively in CP1252, you\r
- will have to uncomment all relative code in the file\r
- <filename>xmlrpc.inc</filename> (you can search for the string "1252"),\r
- then set <code>$GLOBALS['xmlrpc_internalencoding']='CP1252';</code>\r
- Please note that all incoming data will then be fed to your application\r
- as UTF-8 to avoid any potentail data loss.</para>\r
- </sect1>\r
-\r
- <sect1>\r
- <title>Does the library support using cookies / http sessions?</title>\r
-\r
- <para>In short: yes, but a little coding is needed to make it\r
- happen.</para>\r
-\r
- <para>The code below uses sessions to e.g. let the client store a value\r
- on the server and retrieve it later.</para>\r
-\r
- <para><programlisting>\r
-$resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));\r
-if (!$resp->faultCode())\r
-{\r
- $cookies = $resp->cookies();\r
- if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name\r
- {\r
- $session_id = $cookies['PHPSESSID']['value'];\r
-\r
- // do some other stuff here...\r
-\r
- $client->setcookie('PHPSESSID', $session_id);\r
- $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));\r
- }\r
-}\r
-</programlisting>Server-side sessions are handled normally like in any other\r
- php application. Please see the php manual for more information about\r
- sessions.</para>\r
-\r
- <para>NB: unlike web browsers, not all xmlrpc clients support usage of\r
- http cookies. If you have troubles with sessions and control only the\r
- server side of the communication, please check with the makers of the\r
- xmlrpc client in use.</para>\r
- </sect1>\r
- </chapter>\r
-\r
- <appendix id="integration">\r
- <title>Integration with the PHP xmlrpc extension</title>\r
-\r
- <para>To be documented more...</para>\r
-\r
- <para>In short: for the fastest execution possible, you can enable the php\r
- native xmlrpc extension, and use it in conjunction with phpxmlrpc. The\r
- following code snippet gives an example of such integration</para>\r
-\r
- <programlisting language="php">\r
-/*** client side ***/\r
-$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');\r
-\r
-// tell the client to return raw xml as response value\r
-$c->return_type = 'xml';\r
-\r
-// let the native xmlrpc extension take care of encoding request parameters\r
-$r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));\r
-\r
-if ($r->faultCode())\r
- // HTTP transport error\r
- echo 'Got error '.$r->faultCode();\r
-else\r
-{\r
- // HTTP request OK, but XML returned from server not parsed yet\r
- $v = xmlrpc_decode($r->value());\r
- // check if we got a valid xmlrpc response from server\r
- if ($v === NULL)\r
- echo 'Got invalid response';\r
- else\r
- // check if server sent a fault response\r
- if (xmlrpc_is_fault($v))\r
- echo 'Got xmlrpc fault '.$v['faultCode'];\r
- else\r
- echo'Got response: '.htmlentities($v);\r
-}\r
-</programlisting>\r
- </appendix>\r
-\r
- <appendix id="substitution">\r
- <title>Substitution of the PHP xmlrpc extension</title>\r
-\r
- <para>Yet another interesting situation is when you are using a ready-made\r
- php application, that provides support for the XMLRPC protocol via the\r
- native php xmlrpc extension, but the extension is not available on your\r
- php install (e.g. because of shared hosting constraints).</para>\r
-\r
- <para>Since version 2.1, the PHP-XMLRPC library provides a compatibility\r
- layer that aims to be 100% compliant with the xmlrpc extension API. This\r
- means that any code written to run on the extension should obtain the\r
- exact same results, albeit using more resources and a longer processing\r
- time, using the PHP-XMLRPC library and the extension compatibility module.\r
- The module is part of the EXTRAS package, available as a separate download\r
- from the sourceforge.net website, since version 0.2</para>\r
- </appendix>\r
-\r
- <appendix id="enough">\r
- <title>'Enough of xmlrpcvals!': new style library usage</title>\r
-\r
- <para>To be documented...</para>\r
-\r
- <para>In the meantime, see docs about xmlrpc_client::return_type and\r
- xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,\r
- php_xmlrpc_decode and php_xmlrpc_decode_xml</para>\r
- </appendix>\r
-\r
- <appendix id="debugger">\r
- <title>Usage of the debugger</title>\r
-\r
- <para>A webservice debugger is included in the library to help during\r
- development and testing.</para>\r
-\r
- <para>The interface should be self-explicative enough to need little\r
- documentation.</para>\r
-\r
- <para><graphic align="center" fileref="debugger.gif"\r
- format="GIF" /></para>\r
-\r
- <para>The most useful feature of the debugger is without doubt the "Show\r
- debug info" option. It allows to have a screen dump of the complete http\r
- communication between client and server, including the http headers as\r
- well as the request and response payloads, and is invaluable when\r
- troubleshooting problems with charset encoding, authentication or http\r
- compression.</para>\r
-\r
- <para>The debugger can take advantage of the JSONRPC library extension, to\r
- allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library\r
- visual editor to allow easy mouse-driven construction of the payload for\r
- remote methods. Both components have to be downloaded separately from the\r
- sourceforge.net web pages and copied to the debugger directory to enable\r
- the extra functionality:</para>\r
-\r
- <para><itemizedlist>\r
- <listitem>\r
- <para>to enable jsonrpc functionality, download the PHP-XMLRPC\r
- EXTRAS package, and copy the file <filename>jsonrpc.inc</filename>\r
- either to the same directory as the debugger or somewhere in your\r
- php include path</para>\r
- </listitem>\r
- </itemizedlist><itemizedlist>\r
- <listitem>\r
- <para>to enable the visual value editing dialog, download the\r
- JS-XMLRPC library, and copy somewhere in the web root files\r
- <filename>visualeditor.php</filename>,\r
- <filename>visualeditor.css</filename> and the folders\r
- <filename>yui</filename> and <filename>img</filename>. Then edit the\r
- debugger file <filename>controller.php</filename> and set\r
- appropriately the variable <varname>$editorpath</varname>.</para>\r
- </listitem>\r
- </itemizedlist></para>\r
- </appendix>\r
-</book>\r
-<!-- Keep this comment at the end of the file\r
-Local variables:\r
-mode: sgml\r
-sgml-omittag:nil\r
-sgml-shorttag:t\r
-sgml-minimize-attributes:nil\r
-sgml-always-quote-attributes:t\r
-sgml-indent-step:2\r
-sgml-indent-data:t\r
-sgml-parent-document:nil\r
-sgml-exposed-tags:nil\r
-sgml-local-catalogs:nil\r
-sgml-local-ecat-files:nil\r
-sgml-namecase-general:t\r
-sgml-general-insert-case:lower\r
-End:\r
--->\r
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"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>
+
+ <bookinfo>
+ <date>XXX YY, 2008</date>
+
+ <authorgroup>
+ <author>
+ <firstname>Edd</firstname>
+
+ <surname>Dumbill</surname>
+ </author>
+
+ <author>
+ <firstname>Gaetano</firstname>
+
+ <surname>Giunta</surname>
+ </author>
+
+ <author>
+ <firstname>Miles</firstname>
+
+ <surname>Lott</surname>
+ </author>
+
+ <author>
+ <firstname>Justin R.</firstname>
+
+ <surname>Miller</surname>
+ </author>
+
+ <author>
+ <firstname>Andres</firstname>
+
+ <surname>Salomon</surname>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>1999,2000,2001</year>
+
+ <holder>Edd Dumbill, Useful Information Company</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>All rights reserved.</para>
+
+ <para>Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>Redistributions of source code must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer.</para>
+ </listitem>
+
+ <listitem>
+ <para>Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.</para>
+ </listitem>
+
+ <listitem>
+ <para>Neither the name of the "XML-RPC for PHP" nor the names of
+ its contributors may be used to endorse or promote products
+ derived from this software without specific prior written
+ permission.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
+ </legalnotice>
+ </bookinfo>
+
+ <chapter id="introduction">
+ <title>Introduction</title>
+
+ <para>XML-RPC is a format devised by <ulink
+ url="http://www.userland.com/">Userland Software</ulink> for achieving
+ remote procedure call via XML using HTTP as the transport. XML-RPC has its
+ own web site, <ulink
+ url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>
+
+ <para>This collection of PHP classes provides a framework for writing
+ XML-RPC clients and servers in PHP.</para>
+
+ <para>Main goals of the project are ease of use, flexibility and
+ completeness.</para>
+
+ <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>
+
+ <para>A list of XML-RPC implementations for other languages such as Perl
+ and Python can be found on the <ulink
+ url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>
+
+ <sect1>
+ <title>Acknowledgements</title>
+
+ <para>Daniel E. Baumann</para>
+
+ <para>James Bercegay</para>
+
+ <para>Leon Blackwell</para>
+
+ <para>Stephane Bortzmeyer</para>
+
+ <para>Daniel Convissor</para>
+
+ <para>Geoffrey T. Dairiki</para>
+
+ <para>Stefan Esser</para>
+
+ <para>James Flemer</para>
+
+ <para>Ernst de Haan</para>
+
+ <para>Tom Knight</para>
+
+ <para>Axel Kollmorgen</para>
+
+ <para>Peter Kocks</para>
+
+ <para>Daniel Krippner</para>
+
+ <para>S. Kuip</para>
+
+ <para>A. Lambert</para>
+
+ <para>Dan Libby</para>
+
+ <para>Arnaud Limbourg</para>
+
+ <para>Ernest MacDougal Campbell III</para>
+
+ <para>Lukasz Mach</para>
+
+ <para>Kjartan Mannes</para>
+
+ <para>Ben Margolin</para>
+
+ <para>Nicolay Mausz</para>
+
+ <para>Justin Miller</para>
+
+ <para>Jan Pfeifer</para>
+
+ <para>Giancarlo Pinerolo</para>
+
+ <para>Peter Russel</para>
+
+ <para>Viliam Simko</para>
+
+ <para>Douglas Squirrel</para>
+
+ <para>Idan Sofer</para>
+
+ <para>Anatoly Techtonik</para>
+
+ <para>Eric van der Vlist</para>
+
+ <para>Christian Wenz</para>
+
+ <para>Jim Winstead</para>
+
+ <para>Przemyslaw Wroblewski</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="news">
+ <title>What's new</title>
+
+ <para><emphasis>Note:</emphasis> 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 javadoc-like form.</para>
+
+ <sect1>
+ <title>2.2.2</title>
+
+ <para><emphasis>Note:</emphasis> this might the last release of the
+ library that will support PHP 4. Future releases (if any) should target
+ php 5.0 as minimum supported version.</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>fixed: encoding of utf-8 characters outside of the BMP
+ plane</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: character set declarations surrounded by double
+ quotes were not recognized in http headers</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: be more tolerant in detection of charset in http
+ headers</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: fix detection of zlib.output_compression</para>
+ </listitem>
+
+ <listitem>
+ <para>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)</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: format floating point values using the correct
+ decimal separator even when php locale is set to one that uses
+ comma</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: improve robustness of the debugger when parsing weird
+ results from non-compliant servers</para>
+ </listitem>
+
+ <listitem>
+ <para>php warning when receiving 'false' in a bool value</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: allow the add_to_map server method to add docs for
+ single params too</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: added the possibility to wrap for exposure as
+ xmlrpc methods plain php class methods, object methods and even
+ whole classes</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>2.2.1</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>fixed: work aroung bug in php 5.2.2 which broke support of
+ HTTP_RAW_POST_DATA</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: is_dir parameter of setCaCertificate() method is
+ reversed</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: a php warning in xmlrpc_client creator method</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: parsing of '1e+1' as valid float</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: allow errorlevel 3 to work when prev. error handler was
+ a static method</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: usage of client::setcookie() for multiple cookies in
+ non-ssl mode</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: support for CP1252 charset is not part or the
+ library but almost possible</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: more info when curl is enabled and debug mode is
+ on</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>2.2</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>fixed: debugger errors on php installs with magic_quotes_gpc
+ on</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: support for https connections via proxy</para>
+ </listitem>
+
+ <listitem>
+ <para>fixed: wrap_xmlrpc_method() generated code failed to properly
+ encode php objects</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: slightly faster encoding of data which is internally
+ UTF-8</para>
+ </listitem>
+
+ <listitem>
+ <para>improved: debugger always generates a 'null' id for jsonrpc if
+ user omits it</para>
+ </listitem>
+
+ <listitem>
+ <para>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)</para>
+ </listitem>
+
+ <listitem>
+ <para>new: support for the <NIL/> xmlrpc extension. see below
+ for more details</para>
+ </listitem>
+
+ <listitem>
+ <para>new: server support for the system.getCapabilities xmlrpc
+ extension</para>
+ </listitem>
+
+ <listitem>
+ <para>new: <function><link
+ linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>
+ accepts two new options: debug and return_on_fault</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>2.1</title>
+
+ <para><itemizedlist>
+ <listitem>
+ <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
+ will have to include() / require() it in your scripts if you have
+ been using those functions. For increased security, the automatic
+ rebuilding of php object instances out of received xmlrpc structs
+ in <function>wrap_xmlrpc_method()</function> has been disabled
+ (but it can be optionally re-enabled). Both
+ <function>wrap_php_function()</function> and
+ <function>wrap_xmlrpc_method()</function> 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</para>
+ </listitem>
+
+ <listitem>
+ <para>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 <code>new xmlrpcval('true', 'boolean')</code>
+ is not supported anymore</para>
+ </listitem>
+
+ <listitem>
+ <para>The new function
+ <function>php_xmlrpc_decode_xml()</function> will take the xml
+ representation of either an xmlrpc request, response or single
+ value and return the corresponding php-xmlrpc object
+ instance</para>
+ </listitem>
+
+ <listitem>
+ <para>A new function <function>wrap_xmlrpc_server()</function>has
+ been added, to wrap all (or some) of the methods exposed by a
+ remote xmlrpc server into a php class</para>
+ </listitem>
+
+ <listitem>
+ <para>A new file has been added:
+ <filename>verify_compat.php</filename>, to help users diagnose the
+ level of compliance of their php installation with the
+ library</para>
+ </listitem>
+
+ <listitem>
+ <para>Restored compatibility with php 4.0.5 (for those poor souls
+ still stuck on it)</para>
+ </listitem>
+
+ <listitem>
+ <para>Method <methodname>xmlrpc_server->service()</methodname>
+ now returns a value: either the response payload or xmlrpcresp
+ object instance</para>
+ </listitem>
+
+ <listitem>
+ <para>Method
+ <methodname>xmlrpc_server->add_to_map()</methodname> now
+ accepts xmlrpc methods with no param definitions</para>
+ </listitem>
+
+ <listitem>
+ <para>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)</para>
+ </listitem>
+
+ <listitem>
+ <para>Full response payload is saved into xmlrpcresp object for
+ further debugging</para>
+ </listitem>
+
+ <listitem>
+ <para>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)</para>
+ </listitem>
+
+ <listitem>
+ <para>Stricter parsing of incoming xmlrpc messages: two more
+ invalid cases are now detected (double <literal>data</literal>
+ element inside <literal>array</literal> and
+ <literal>struct</literal>/<literal>array</literal> after scalar
+ inside <literal>value</literal> element)</para>
+ </listitem>
+
+ <listitem>
+ <para>More logging of errors in a lot of situations</para>
+ </listitem>
+
+ <listitem>
+ <para>Javadoc documentation of lib files (almost) complete</para>
+ </listitem>
+
+ <listitem>
+ <para>Many performance tweaks and code cleanups, plus the usual
+ crop of bugs fixed (see NEWS file for complete list of
+ bugs)</para>
+ </listitem>
+
+ <listitem>
+ <para>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)...</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>2.0 final</title>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>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</para>
+ </listitem>
+
+ <listitem>
+ <para>Added to the client class the possibility to specify
+ alternate certificate files/directories for authenticating the
+ peer with when using HTTPS communication</para>
+ </listitem>
+
+ <listitem>
+ <para>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)</para>
+ </listitem>
+
+ <listitem>
+ <para>The debugger has been upgraded to reflect the new client
+ capabilities</para>
+ </listitem>
+
+ <listitem>
+ <para>All known bugs have been squashed, and the lib is more
+ tolerant than ever of commonly-found mistakes</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>2.0 Release candidate 3</title>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>Added to server class the property
+ <property>functions_parameters_type</property>, 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)</para>
+ </listitem>
+
+ <listitem>
+ <para>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)</para>
+ </listitem>
+
+ <listitem>
+ <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid
+ input</para>
+ </listitem>
+
+ <listitem>
+ <para>'class::method' syntax is now accepted in the server
+ dispatch map</para>
+ </listitem>
+
+ <listitem>
+ <para><function>xmlrpc_clent::SetDebug()</function> accepts
+ integer values instead of a boolean value, with debugging level 2
+ adding to the information printed to screen the complete client
+ request</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>2.0 Release candidate 2</title>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>Added a new property of the client object:
+ <code>xmlrpc_client->return_type</code>, 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.</para>
+ </listitem>
+
+ <listitem>
+ <para>Added in the extras dir. two new library file:
+ <filename>jsonrpc.inc</filename> and
+ <filename>jsonrpcs.inc</filename> containing new classes that
+ implement support for the json-rpc protocol (alpha quality
+ code)</para>
+ </listitem>
+
+ <listitem>
+ <para>Added a new client method: <code>setKey($key,
+ $keypass)</code> to be used in HTTPS connections</para>
+ </listitem>
+
+ <listitem>
+ <para>Added a new file containing some benchmarks in the testsuite
+ directory</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>2.0 Release candidate 1</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Support for HTTP proxies (new method:
+ <code>xmlrpc_client::setProxy()</code>)</para>
+ </listitem>
+
+ <listitem>
+ <para>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:
+ <code>xmlrpc_client::setAcceptedCompression()</code>,
+ <code>xmlrpc_client::setRequestCompression()</code>). Note that the
+ ZLIB php extension needs to be enabled in PHP to support
+ compression.</para>
+ </listitem>
+
+ <listitem>
+ <para>Implement HTTP 1.1 connections, but only if CURL is enabled
+ (added an extra parameter to
+ <code>xmlrpc_client::xmlrpc_client</code> to set the desired HTTP
+ protocol at creation time and a new supported value for the last
+ parameter of <code>xmlrpc_client::send</code>, which now can be
+ safely omitted if it has been specified at creation time)</para>
+
+ <para>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.</para>
+ </listitem>
+
+ <listitem>
+ <para>Introduce support for cookies. Cookies to be sent to the
+ server with a request can be set using
+ <code>xmlrpc_client::setCookie()</code>, while cookies received from
+ the server are found in <code>xmlrpcresp::cookies()</code>. It is
+ left to the user to check for validity of received cookies and
+ decide whether they apply to successive calls or not.</para>
+ </listitem>
+
+ <listitem>
+ <para>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.</para>
+
+ <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>
+ </listitem>
+
+ <listitem>
+ <para>Added one new xmlrpcmsg constructor syntax, allowing usage of
+ a single string with the complete URL of the target server</para>
+ </listitem>
+
+ <listitem>
+ <para>Convert xml-rpc boolean values into native php values instead
+ of 0 and 1</para>
+ </listitem>
+
+ <listitem>
+ <para>Force the <code>php_xmlrpc_encode</code> 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)</para>
+ </listitem>
+
+ <listitem>
+ <para>Prevent the <code>php_xmlrpc_encode</code> function from
+ further re-encoding any objects of class <code>xmlrpcval</code> that
+ are passed to it. This allows to call the function with arguments
+ consisting of mixed php values / xmlrpcval objects.</para>
+ </listitem>
+
+ <listitem>
+ <para>Allow a server to NOT respond to system.* method calls
+ (setting the <code>$server->allow_system_funcs</code>
+ property).</para>
+ </listitem>
+
+ <listitem>
+ <para>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: <code>xmlrpcval::structMemExists()</code></para>
+ </listitem>
+
+ <listitem>
+ <para>Expand methods <code>xmlrpcval::addArray</code>,
+ <code>addScalar</code> and <code>addStruct</code> allowing extra php
+ values to be added to xmlrpcval objects already formed.</para>
+ </listitem>
+
+ <listitem>
+ <para>Let the <code>xmlrpc_client::send</code> method accept an XML
+ string for sending instead of an xmlrpcmsg object, to facilitate
+ debugging and integration with the php native xmlrpc
+ extension</para>
+ </listitem>
+
+ <listitem>
+ <para>Extend the <code>php_xmlrpc_encode</code> and
+ <code>php_xmlrpc_decode</code> 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.</para>
+
+ <para>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 <code>php_xmlrpc_encode</code> and
+ <code>php_xmlrpc_decode</code>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Extend the <code>php_xmlrpc_encode</code> function to allow
+ automatic serialization of iso8601-conforming php strings as
+ datetime.iso8601 xmlrpcvals, by usage of an optional
+ parameter</para>
+ </listitem>
+
+ <listitem>
+ <para>Added an automatic stub code generator for converting xmlrpc
+ methods to php functions and vice-versa.</para>
+
+ <para>This is done via two new functions:
+ <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>
+ <para>Allow object methods to be used in server dispatch map</para>
+ </listitem>
+
+ <listitem>
+ <para>Added a complete debugger solution, in the
+ <filename>debugger</filename> folder</para>
+ </listitem>
+
+ <listitem>
+ <para>Added configurable server-side debug messages, controlled by
+ the new method <code>xmlrpc_server::SetDebug()</code>. 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</para>
+ </listitem>
+
+ <listitem>
+ <para>New XML parsing code, yields smaller memory footprint and
+ faster execution times, not to mention complete elimination of the
+ dreaded <filename>eval()</filename> construct, so prone to code
+ injection exploits</para>
+ </listitem>
+
+ <listitem>
+ <para>Rewritten most of the error messages, making text more
+ explicative</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+ </chapter>
+
+ <chapter id="requirements">
+ <title>System Requirements</title>
+
+ <para>The library has been designed with goals of scalability and backward
+ compatibility. As such, it supports a wide range of PHP installs. Note
+ that not all features of the lib are available in every
+ configuration.</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>
+
+ <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>
+
+ <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
+ the operation of this library.</para>
+ </chapter>
+
+ <chapter id="manifest">
+ <title>Files in the distribution</title>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>lib/xmlrpc.inc</glossterm>
+
+ <glossdef>
+ <para>the XML-RPC classes. <function>include()</function> this in
+ your PHP files to use the classes.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>lib/xmlrpcs.inc</glossterm>
+
+ <glossdef>
+ <para>the XML-RPC server class. <function>include()</function> this
+ in addition to xmlrpc.inc to get server functionality</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>lib/xmlrpc_wrappers.inc</glossterm>
+
+ <glossdef>
+ <para>helper functions to "automagically" convert plain php
+ functions to xmlrpc services and vice versa</para>
+ </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>
+
+ <glossdef>
+ <para>a sample server implementing xmlrpc proxy
+ functionality.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/server/server.php</glossterm>
+
+ <glossdef>
+ <para>a sample server hosting various demo functions, as well as a
+ full suite of functions used for interoperability testing. It is
+ used by testsuite.php (see below) for unit testing the library, and
+ is not to be copied literally into your production servers</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/client/client.php, demo/client/agesort.php,
+ demo/client/which.php</glossterm>
+
+ <glossdef>
+ <para>client code to exercise some of the functions in server.php,
+ including the <function>interopEchoTests.whichToolkit</function>
+ method.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/client/wrap.php</glossterm>
+
+ <glossdef>
+ <para>client code to illustrate 'wrapping' of remote methods into
+ php functions.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/client/introspect.php</glossterm>
+
+ <glossdef>
+ <para>client code to illustrate usage of introspection capabilities
+ offered by server.php.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/client/mail.php</glossterm>
+
+ <glossdef>
+ <para>client code to illustrate usage of an xmlrpc-to-email gateway
+ using Dave Winer's XML-RPC server at userland.com.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/client/zopetest.php</glossterm>
+
+ <glossdef>
+ <para>example client code that queries an xmlrpc server built in
+ Zope.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/vardemo.php</glossterm>
+
+ <glossdef>
+ <para>examples of how to construct xmlrpcval types</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>
+
+ <glossdef>
+ <para>XML-RPC responses captured in a file for testing purposes (you
+ can use these to test the
+ <function>xmlrpcmsg->parseResponse()</function> method).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>demo/server/discuss.php,
+ demo/client/comment.php</glossterm>
+
+ <glossdef>
+ <para>Software used in the PHP chapter of <xref
+ linkend="jellyfish" /> to provide a comment server and allow the
+ attachment of comments to stories from Meerkat's data store.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>test/testsuite.php, test/parse_args.php</glossterm>
+
+ <glossdef>
+ <para>A unit test suite for this software package. If you do
+ development on this software, please consider submitting tests for
+ this suite.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>test/benchmark.php</glossterm>
+
+ <glossdef>
+ <para>A (very limited) benchmarking suite for this software package.
+ If you do development on this software, please consider submitting
+ benchmarks for this suite.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>
+
+ <glossdef>
+ <para>An (incomplete) version PEAR's unit test framework for PHP.
+ The complete package can be found at <ulink
+ url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>test/verify_compat.php</glossterm>
+
+ <glossdef>
+ <para>Script designed to help the user to verify the level of
+ compatibility of the library with the current php install</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>extras/test.pl, extras/test.py</glossterm>
+
+ <glossdef>
+ <para>Perl and Python programs to exercise server.php to test that
+ some of the methods work.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>extras/workspace.testPhpServer.fttb</glossterm>
+
+ <glossdef>
+ <para>Frontier scripts to exercise the demo server. Thanks to Dave
+ Winer for permission to include these. See <ulink
+ url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's
+ announcement of these.</ulink></para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>extras/rsakey.pem</glossterm>
+
+ <glossdef>
+ <para>A test certificate key for the SSL support, which can be used
+ to generate dummy certificates. It has the passphrase "test."</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </chapter>
+
+ <chapter id="bugs">
+ <title>Known bugs and limitations</title>
+
+ <para>This started out as a bare framework. Many "nice" bits haven't been
+ put in yet. Specifically, very little type validation or coercion has been
+ put in. PHP being a loosely-typed language, this is going to have to be
+ done explicitly (in other words: you can call a lot of library functions
+ passing them arguments of the wrong type and receive an error message only
+ much further down the code, where it will be difficult to
+ understand).</para>
+
+ <para>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 <xref
+ linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions
+ to do the encoding and decoding for you.</para>
+
+ <para>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.</para>
+
+ <para>If a specific character set encoding other than US-ASCII, ISO-8859-1
+ or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
+ or response messages then it will be ignored for the moment, and the
+ content will be parsed as if it had been encoded using the charset defined
+ by <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">
+ <title>Support</title>
+
+ <sect1>
+ <title>Online Support</title>
+
+ <para>XML-RPC for PHP is offered "as-is" without any warranty or
+ commitment to support. However, informal advice and help is available
+ via the XML-RPC for PHP website and mailing list and from
+ XML-RPC.com.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
+ on <ulink
+ url="http://phpxmlrpc.sourceforge.net">phpxmlrpc.sourceforge.net</ulink>.
+ Bugs, feature requests and patches can be posted to the <ulink
+ url="http://sourceforge.net/projects/phpxmlrpc">project's
+ website</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is
+ run by the author. More details <ulink
+ url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be
+ found here</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>For more general XML-RPC questions, there is a Yahoo! Groups
+ <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing
+ list</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <ulink
+ url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion
+ group is a useful place to get help with using XML-RPC. This group
+ is also gatewayed into the Yahoo! Groups mailing list.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="jellyfish" xreflabel="The Jellyfish Book">
+ <title>The Jellyfish Book</title>
+
+ <para><graphic align="right" depth="190" fileref="progxmlrpc.s.gif"
+ format="GIF" width="145" />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.</para>
+
+ <para>Complete details of the book are <ulink
+ url="http://www.oreilly.com/catalog/progxmlrpc/">available from
+ O'Reilly's web site.</ulink></para>
+
+ <para>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
+ <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in
+ order to allow commenting on news stories from around the Web.</para>
+
+ <para>If you've benefited from the effort that has been put into writing
+ this software, then please consider buying the book!</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="apidocs">
+ <title>Class documentation</title>
+
+ <sect1 id="xmlrpcval" xreflabel="xmlrpcval">
+ <title>xmlrpcval</title>
+
+ <para>This is where a lot of the hard work gets done. This class enables
+ the creation and encapsulation of values for XML-RPC.</para>
+
+ <para>Ensure you've read the XML-RPC spec at <ulink
+ url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>
+ before reading on as it will make things clearer.</para>
+
+ <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>
+
+ <sect2>
+ <title>Notes on types</title>
+
+ <sect3>
+ <title>int</title>
+
+ <para>The type <classname>i4</classname> is accepted as a synonym
+ for <classname>int</classname> when creating xmlrpcval objects. The
+ xml parsing code will always convert <classname>i4</classname> to
+ <classname>int</classname>: <classname>int</classname> is regarded
+ by this implementation as the canonical name for this type.</para>
+ </sect3>
+
+ <sect3>
+ <title>base64</title>
+
+ <para>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.</para>
+ </sect3>
+
+ <sect3>
+ <title>boolean</title>
+
+ <para>The php values <literal>true</literal> and
+ <literal>1</literal> map to <literal>true</literal>. All other
+ values (including the empty string) are converted to
+ <literal>false</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>string</title>
+
+ <para>Characters <, >, ', ", &, are encoded using their
+ entity reference as &lt; &gt; &apos; &quot; and
+ &amp; All other characters outside of the ASCII range are
+ encoded using their character reference representation (e.g.
+ &#200 for é). The XML-RPC spec recommends only encoding
+ <literal>< &</literal> but this implementation goes further,
+ for reasons explained by <ulink
+ url="http://www.w3.org/TR/REC-xml#syntax">the XML 1.0
+ recommendation</ulink>. In particular, using character reference
+ representation has the advantage of producing XML that is valid
+ independently of the charset encoding assumed.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
+ <title>Creation</title>
+
+ <para>The constructor is the normal way to create an
+ <classname>xmlrpcval</classname>. The constructor can take these
+ forms:</para>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type>new
+ <function>xmlrpcval</function></funcdef>
+
+ <void />
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type>new
+ <function>xmlrpcval</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type>new
+ <function>xmlrpcval</function></funcdef>
+
+ <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type>new
+ <function>xmlrpcval</function></funcdef>
+
+ <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>The first constructor creates an empty value, which must be
+ altered using the methods <function>addScalar</function>,
+ <function>addArray</function> or <function>addStruct</function> before
+ it can be used.</para>
+
+ <para>The second constructor creates a simple string value.</para>
+
+ <para>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:
+ "<literal>int</literal>", "<literal>boolean</literal>",
+ "<literal>string</literal>", "<literal>double</literal>",
+ "<literal>dateTime.iso8601</literal>",
+ "<literal>base64</literal>".</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
+</programlisting>
+
+ <para>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 <classname>array</classname> or an associative
+ array in the case of a <classname>struct</classname>. The elements of
+ the array <emphasis>must be <classname>xmlrpcval</classname> objects
+ themselves</emphasis>.</para>
+
+ <para>The second parameter must be either "<literal>array</literal>"
+ or "<literal>struct</literal>".</para>
+
+ <para>Examples:</para>
+
+ <programlisting language="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");
+</programlisting>
+
+ <para>See the file <literal>vardemo.php</literal> in this distribution
+ for more examples.</para>
+ </sect2>
+
+ <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">
+ <title>Methods</title>
+
+ <sect3>
+ <title>addScalar</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>addScalar</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>int</type><function>addScalar</function></funcdef>
+
+ <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>If <parameter>$val</parameter> is an empty
+ <classname>xmlrpcval</classname> this method makes it a scalar
+ value, and sets that value.</para>
+
+ <para>If <parameter>$val</parameter> is already a scalar value, then
+ no more scalars can be added and <literal>0</literal> is
+ returned.</para>
+
+ <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
+ the php value <parameter>$scalarval</parameter> is added as its last
+ element.</para>
+
+ <para>If all went OK, <literal>1</literal> is returned, otherwise
+ <literal>0</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>addArray</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>addArray</function></funcdef>
+
+ <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>The argument is a simple (numerically indexed) array. The
+ elements of the array <emphasis>must be
+ <classname>xmlrpcval</classname> objects
+ themselves</emphasis>.</para>
+
+ <para>Turns an empty <classname>xmlrpcval</classname> into an
+ <classname>array</classname> with contents as specified by
+ <parameter>$arrayVal</parameter>.</para>
+
+ <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
+ the elements of <parameter>$arrayVal</parameter> are appended to the
+ existing ones.</para>
+
+ <para>See the fourth constructor form for more information.</para>
+
+ <para>If all went OK, <literal>1</literal> is returned, otherwise
+ <literal>0</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>addStruct</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>addStruct</function></funcdef>
+
+ <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>The argument is an associative array. The elements of the
+ array <emphasis>must be <classname>xmlrpcval</classname> objects
+ themselves</emphasis>.</para>
+
+ <para>Turns an empty <classname>xmlrpcval</classname> into a
+ <classname>struct</classname> with contents as specified by
+ <parameter>$assocArrayVal</parameter>.</para>
+
+ <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,
+ the elements of <parameter>$arrayVal</parameter> are merged with the
+ existing ones.</para>
+
+ <para>See the fourth constructor form for more information.</para>
+
+ <para>If all went OK, <literal>1</literal> is returned, otherwise
+ <literal>0</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>kindOf</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>kindOf</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns a string containing "struct", "array" or "scalar"
+ describing the base type of the value. If it returns "undef" it
+ means that the value hasn't been initialised.</para>
+ </sect3>
+
+ <sect3>
+ <title>serialize</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>serialize</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns a string containing the XML-RPC representation of this
+ value.</para>
+ </sect3>
+
+ <sect3>
+ <title>scalarVal</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>mixed</type><function>scalarVal</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>If <function>$val->kindOf() == "scalar"</function>, this
+ method returns the actual PHP-language value of the scalar (base 64
+ decoding is automatically handled here).</para>
+ </sect3>
+
+ <sect3>
+ <title>scalarTyp</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>scalarTyp</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>If <function>$val->kindOf() == "scalar"</function>, this
+ method returns a string denoting the type of the scalar. As
+ mentioned before, <literal>i4</literal> is always coerced to
+ <literal>int</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>arrayMem</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type><function>arrayMem</function></funcdef>
+
+ <paramdef><type>int</type><parameter>$n</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>If <function>$val->kindOf() == "array"</function>, returns
+ the <parameter>$n</parameter>th element in the array represented by
+ the value <parameter>$val</parameter>. The value returned is an
+ <classname>xmlrpcval</classname> object.</para>
+
+ <para><programlisting language="php">
+// iterating over values of an array object
+for ($i = 0; $i < $val->arraySize(); $i++)
+{
+ $v = $val->arrayMem($i);
+ echo "Element $i of the array is of type ".$v->kindOf();
+}
+</programlisting></para>
+ </sect3>
+
+ <sect3>
+ <title>arraySize</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>arraySize</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>If <parameter>$val</parameter> is an
+ <classname>array</classname>, returns the number of elements in that
+ array.</para>
+ </sect3>
+
+ <sect3>
+ <title>structMem</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type><function>structMem</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>If <function>$val->kindOf() == "struct"</function>, returns
+ the element called <parameter>$memberName</parameter> from the
+ struct represented by the value <parameter>$val</parameter>. The
+ value returned is an <classname>xmlrpcval</classname> object.</para>
+ </sect3>
+
+ <sect3>
+ <title>structEach</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>array</type><function>structEach</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns the next (key, value) pair from the struct, when
+ <parameter>$val</parameter> is a struct.
+ <parameter>$value</parameter> is an xmlrpcval itself. See also <xref
+ linkend="structreset" />.</para>
+
+ <para><programlisting language="php">
+// iterating over all values of a struct object
+$val->structreset();
+while (list($key, $v) = $val->structEach())
+{
+ echo "Element $key of the struct is of type ".$v->kindOf();
+}
+</programlisting></para>
+ </sect3>
+
+ <sect3 id="structreset" xreflabel="structreset()">
+ <title>structReset</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>structReset</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Resets the internal pointer for
+ <function>structEach()</function> to the beginning of the struct,
+ where <parameter>$val</parameter> is a struct.</para>
+ </sect3>
+
+ <sect3 id="structmemexists" xreflabel="structmemexists()">
+ <title>structMemExists</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>bool</type><function>structMemExsists</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns <constant>TRUE</constant> or
+ <constant>FALSE</constant> depending on whether a member of the
+ given name exists in the struct.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">
+ <title>xmlrpcmsg</title>
+
+ <para>This class provides a representation for a request to an XML-RPC
+ server. A client sends an <classname>xmlrpcmsg</classname> to a server,
+ and receives back an <classname>xmlrpcresp</classname> (see <xref
+ linkend="xmlrpc-client-send" />).</para>
+
+ <sect2>
+ <title>Creation</title>
+
+ <para>The constructor takes the following forms:</para>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcmsg</type>new
+ <function>xmlrpcmsg</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>
+
+ <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Where <parameter>methodName</parameter> is a string indicating
+ the name of the method you wish to invoke, and
+ <parameter>parameterArray</parameter> is a simple php
+ <classname>Array</classname> of <classname>xmlrpcval</classname>
+ objects. Here's an example message to the <emphasis>US state
+ name</emphasis> server:</para>
+
+ <programlisting language="php">
+$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
+</programlisting>
+
+ <para>This example requests the name of state number 23. For more
+ information on <classname>xmlrpcval</classname> objects, see <xref
+ linkend="xmlrpcval" />.</para>
+
+ <para>Note that the <parameter>parameterArray</parameter> parameter is
+ optional and can be omitted for methods that take no input parameters
+ or if you plan to add parameters one by one.</para>
+ </sect2>
+
+ <sect2>
+ <title>Methods</title>
+
+ <sect3>
+ <title>addParam</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>bool</type><function>addParam</function></funcdef>
+
+ <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Adds the <classname>xmlrpcval</classname>
+ <parameter>xmlrpcVal</parameter> to the parameter list for this
+ method call. Returns TRUE or FALSE on error.</para>
+ </sect3>
+
+ <sect3>
+ <title>getNumParams</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>getNumParams</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns the number of parameters attached to this
+ message.</para>
+ </sect3>
+
+ <sect3>
+ <title>getParam</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type><function>getParam</function></funcdef>
+
+ <paramdef><type>int</type><parameter>$n</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Gets the <parameter>n</parameter>th parameter in the message
+ (with the index zero-based). Use this method in server
+ implementations to retrieve the values sent by the client.</para>
+ </sect3>
+
+ <sect3>
+ <title>method</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>method</function></funcdef>
+
+ <void />
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>string</type><function>method</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$methName</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Gets or sets the method contained in the XML-RPC
+ message.</para>
+ </sect3>
+
+ <sect3>
+ <title>parseResponse</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcresp</type><function>parseResponse</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Given an incoming XML-RPC server response contained in the
+ string <parameter>$xmlString</parameter>, this method constructs an
+ <classname>xmlrpcresp</classname> response object and returns it,
+ setting error codes as appropriate (see <xref
+ linkend="xmlrpc-client-send" />).</para>
+
+ <para>This method processes any HTTP/MIME headers it finds.</para>
+ </sect3>
+
+ <sect3>
+ <title>parseResponseFile</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcresp</type><function>parseResponseFile</function></funcdef>
+
+ <paramdef><type>file handle
+ resource</type><parameter>$fileHandle</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Given an incoming XML-RPC server response on the open file
+ handle <parameter>fileHandle</parameter>, this method reads all the
+ data it finds and passes it to
+ <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>
+ in this distribution). It processes any HTTP headers it finds, and
+ does not close the file handle.</para>
+ </sect3>
+
+ <sect3>
+ <title>serialize</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string
+ </type><function>serialize</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns the an XML string representing the XML-RPC
+ message.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">
+ <title>xmlrpc_client</title>
+
+ <para>This is the basic class used to represent a client of an XML-RPC
+ server.</para>
+
+ <sect2>
+ <title>Creation</title>
+
+ <para>The constructor accepts one of two possible syntaxes:</para>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpc_client</type>new
+ <function>xmlrpc_client</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>xmlrpc_client</type>new
+ <function>xmlrpc_client</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>
+
+ <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Here are a couple of usage examples of the first form:</para>
+
+ <programlisting language="php">
+$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
+$another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/xmlrpcserver?agent=007");
+</programlisting>
+
+ <para>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.</para>
+
+ <para>Here's another example client set up to query Userland's XML-RPC
+ server at <emphasis>betty.userland.com</emphasis>:</para>
+
+ <programlisting language="php">
+$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
+</programlisting>
+
+ <para>The <parameter>server_port</parameter> parameter is optional,
+ and if omitted will default to 80 when using HTTP and 443 when using
+ HTTPS (see the <xref linkend="xmlrpc-client-send" /> method
+ below).</para>
+
+ <para>The <parameter>transport</parameter> parameter is optional, and
+ if omitted will default to 'http'. Allowed values are either
+ '<symbol>http'</symbol>, '<symbol>https</symbol>' or
+ '<symbol>http11'</symbol>. Its value can be overridden with every call
+ to the <methodname>send</methodname> method. See the
+ <methodname>send</methodname> method below for more details about the
+ meaning of the different values.</para>
+ </sect2>
+
+ <sect2>
+ <title>Methods</title>
+
+ <para>This class supports the following methods.</para>
+
+ <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client->send">
+ <title>send</title>
+
+ <para>This method takes the forms:</para>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
+
+ <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpc_message</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>array</type><function>send</function></funcdef>
+
+ <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Where <parameter>xmlrpc_message</parameter> is an instance of
+ <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),
+ and <parameter>response</parameter> is an instance of
+ <classname>xmlrpcresp</classname> (see <xref
+ linkend="xmlrpcresp" />).</para>
+
+ <para><parameter>If xmlrpc_messages</parameter> is an array of
+ message instances, <code>responses</code> will be an array of
+ response instances. The client will try to make use of a single
+ <code>system.multicall</code> xml-rpc method call to forward to the
+ server all the messages in a single HTTP round trip, unless
+ <code>$client->no_multicall</code> has been previously set to
+ <code>TRUE</code> (see the multicall method below), in which case
+ many consecutive xmlrpc requests will be sent.</para>
+
+ <para>The third syntax allows to build by hand (or any other means)
+ a complete xmlrpc request message, and send it to the server.
+ <parameter>xml_payload</parameter> should be a string containing the
+ complete xml representation of the request. It is e.g. useful when,
+ for maximal speed of execution, the request is serialized into a
+ string using the native php xmlrpc functions (see <ulink
+ url="http://www.php.net/xmlrpc">the php manual on
+ xmlrpc</ulink>).</para>
+
+ <para>The <parameter>timeout</parameter> is optional, and will be
+ set to <literal>0</literal> (wait for platform-specific predefined
+ timeout) if omitted. This timeout value is passed to
+ <function>fsockopen()</function>. It is also used for detecting
+ server timeouts during communication (i.e. if the server does not
+ send anything to the client for <parameter>timeout</parameter>
+ seconds, the connection will be closed).</para>
+
+ <para>The <parameter>transport</parameter> parameter is optional,
+ and if omitted will default to the transport set using instance
+ creator or 'http' if omitted. The only other valid values are
+ 'https', which will use an SSL HTTP connection to connect to the
+ remote server, and 'http11'. Note that your PHP must have the "curl"
+ extension compiled in order to use both these features. Note that
+ when using SSL you should normally set your port number to 443,
+ unless the SSL server you are contacting runs at any other
+ port.</para>
+
+ <warning>
+ <para>PHP 4.0.6 has a bug which prevents SSL working.</para>
+ </warning>
+
+ <para>In addition to low-level errors, the XML-RPC server you were
+ querying may return an error in the
+ <classname>xmlrpcresp</classname> object. See <xref
+ linkend="xmlrpcresp" /> for details of how to handle these
+ errors.</para>
+ </sect3>
+
+ <sect3 id="multicall" xreflabel="xmlrpc_client->multicall">
+ <title>multiCall</title>
+
+ <para>This method takes the form:</para>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>array</type><function>multiCall</function></funcdef>
+
+ <paramdef><type>array</type><parameter>$messages</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
+
+ <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method is used to boxcar many method calls in a single
+ xml-rpc request. It will try first to make use of the
+ <code>system.multicall</code> xml-rpc method call, and fall back to
+ executing many separate requests if the server returns any
+ error.</para>
+
+ <para><parameter>msgs</parameter> is an array of
+ <classname>xmlrpcmsg</classname> objects (see <xref
+ linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an
+ array of <classname>xmlrpcresp</classname> objects (see <xref
+ linkend="xmlrpcresp" />).</para>
+
+ <para>The <parameter>timeout</parameter> and
+ <parameter>transport</parameter> parameters are optional, and behave
+ as in the <methodname>send</methodname> method above.</para>
+
+ <para>The <parameter>fallback</parameter> parameter is optional, and
+ defaults to <constant>TRUE</constant>. When set to
+ <constant>FALSE</constant> it will prevent the client to try using
+ many single method calls in case of failure of the first multicall
+ request. It should be set only when the server is known to support
+ the multicall extension.</para>
+ </sect3>
+
+ <sect3>
+ <title>setAcceptedCompression</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setAcceptedCompression</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method defines whether the client will accept compressed
+ xml payload forming the bodies of the xmlrpc responses received from
+ servers. Note that enabling reception of compressed responses merely
+ adds some standard http headers to xmlrpc requests. It is up to the
+ xmlrpc server to return compressed responses when receiving such
+ requests. Allowed values for
+ <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
+ 'any' or null (with any meaning either gzip or deflate).</para>
+
+ <para>This requires the "zlib" extension to be enabled in your php
+ install. If it is, by default <classname>xmlrpc_client</classname>
+ instances will enable reception of compressed content.</para>
+ </sect3>
+
+ <sect3>
+ <title>setCaCertificate</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setCaCertificate</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
+
+ <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method sets an optional certificate to be used in
+ SSL-enabled communication to validate a remote server with (when the
+ <parameter>server_method</parameter> is set to 'https' in the
+ client's construction or in the send method and
+ <methodname>SetSSLVerifypeer</methodname> has been set to
+ <constant>TRUE</constant>).</para>
+
+ <para>The <parameter>certificate</parameter> parameter must be the
+ filename of a PEM formatted certificate, or a directory containing
+ multiple certificate files. The <parameter>is_dir</parameter>
+ parameter defaults to <constant>FALSE</constant>, set it to
+ <constant>TRUE</constant> to specify that
+ <parameter>certificate</parameter> indicates a directory instead of
+ a single file.</para>
+
+ <para>This requires the "curl" extension to be compiled into your
+ installation of PHP. For more details see the man page for the
+ <function>curl_setopt</function> function.</para>
+ </sect3>
+
+ <sect3>
+ <title>setCertificate</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setCertificate</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method sets the optional certificate and passphrase used
+ in SSL-enabled communication with a remote server (when the
+ <parameter>server_method</parameter> is set to 'https' in the
+ client's construction or in the send method).</para>
+
+ <para>The <parameter>certificate</parameter> parameter must be the
+ filename of a PEM formatted certificate. The
+ <parameter>passphrase</parameter> parameter must contain the
+ password required to use the certificate.</para>
+
+ <para>This requires the "curl" extension to be compiled into your
+ installation of PHP. For more details see the man page for the
+ <function>curl_setopt</function> function.</para>
+
+ <para>Note: to retrieve information about the client certificate on
+ the server side, you will need to look into the environment
+ variables which are set up by the webserver. Different webservers
+ will typically set up different variables.</para>
+ </sect3>
+
+ <sect3>
+ <title>setCookie</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setCookie</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$name</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$value</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$path</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$domain</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$port</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method sets a cookie that will be sent to the xmlrpc
+ server along with every further request (useful e.g. for keeping
+ session info outside of the xml-rpc payload).</para>
+
+ <para><parameter>$value</parameter> is optional, and defaults to
+ null.</para>
+
+ <para><parameter>$path, $domain and $port</parameter> are optional,
+ and will be omitted from the cookie header if unspecified. Note that
+ setting any of these values will turn the cookie into a 'version 1'
+ cookie, that might not be fully supported by the server (see RFC2965
+ for more details).</para>
+ </sect3>
+
+ <sect3>
+ <title>setCredentials</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setCredentials</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$username</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$password</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method sets the username and password for authorizing the
+ client to a server. With the default (HTTP) transport, this
+ information is used for HTTP Basic authorization. Note that username
+ and password can also be set using the class constructor. With HTTP
+ 1.1 and HTTPS transport, NTLM and Digest authentication protocols
+ are also supported. To enable them use the constants
+ <constant>CURLAUTH_DIGEST</constant> and
+ <constant>CURLAUTH_NTLM</constant> as values for the authtype
+ parameter.</para>
+ </sect3>
+
+ <sect3>
+ <title>setDebug</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setDebug</function></funcdef>
+
+ <paramdef><type>int</type><parameter>$debugLvl</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para><parameter>debugLvl</parameter> is either <literal>0,
+ 1</literal> or 2 depending on whether you require the client to
+ print debugging information to the browser. The default is not to
+ output this information (0).</para>
+
+ <para>The debugging information at level 1includes the raw data
+ returned from the XML-RPC server it was querying (including bot HTTP
+ headers and the full XML payload), and the PHP value the client
+ attempts to create to represent the value returned by the server. At
+ level2, the complete payload of the xmlrpc request is also printed,
+ before being sent t the server.</para>
+
+ <para>This option can be very useful when debugging servers as it
+ allows you to see exactly what the client sends and the server
+ returns.</para>
+ </sect3>
+
+ <sect3>
+ <title>setKey</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setKey</function></funcdef>
+
+ <paramdef><type>int</type><parameter>$key</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method sets the optional certificate key and passphrase
+ used in SSL-enabled communication with a remote server (when the
+ <parameter>transport</parameter> is set to 'https' in the client's
+ construction or in the send method).</para>
+
+ <para>This requires the "curl" extension to be compiled into your
+ installation of PHP. For more details see the man page for the
+ <function>curl_setopt</function> function.</para>
+ </sect3>
+
+ <sect3>
+ <title>setProxy</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setProxy</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method enables calling servers via an HTTP proxy. The
+ <parameter>proxyusername</parameter>,<parameter>
+ proxypassword</parameter> and <parameter>authtype</parameter>
+ parameters are optional. <parameter>Authtype</parameter> defaults to
+ <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);
+ the only other valid value is the constant
+ <constant>CURLAUTH_NTLM</constant>, and has effect only when the
+ client uses the HTTP 1.1 protocol.</para>
+
+ <para>NB: CURL versions before 7.11.10 cannot use a proxy to
+ communicate with https servers.</para>
+ </sect3>
+
+ <sect3>
+ <title>setRequestCompression</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setRequestCompression</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method defines whether the xml payload forming the
+ request body will be sent to the server in compressed format, as per
+ the HTTP specification. This is particularly useful for large
+ request parameters and over slow network connections. Allowed values
+ for <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
+ 'any' or null (with any meaning either gzip or deflate). Note that
+ there is no automatic fallback mechanism in place for errors due to
+ servers not supporting receiving compressed request bodies, so make
+ sure that the particular server you are querying does accept
+ compressed requests before turning it on.</para>
+
+ <para>This requires the "zlib" extension to be enabled in your php
+ install.</para>
+ </sect3>
+
+ <sect3>
+ <title>setSSLVerifyHost</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setSSLVerifyHost</function></funcdef>
+
+ <paramdef><type>int</type><parameter>$i</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method defines whether connections made to XML-RPC
+ backends via HTTPS should verify the remote host's SSL certificate's
+ common name (CN). By default, only the existence of a CN is checked.
+ <parameter><parameter>$i</parameter></parameter> should be an
+ integer value; 0 to not check the CN at all, 1 to merely check for
+ its existence, and 2 to check that the CN on the certificate matches
+ the hostname that is being connected to.</para>
+ </sect3>
+
+ <sect3>
+ <title>setSSLVerifyPeer</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>setSSLVerifyPeer</function></funcdef>
+
+ <paramdef><type>bool</type><parameter>$i</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>This method defines whether connections made to XML-RPC
+ backends via HTTPS should verify the remote host's SSL certificate,
+ and cause the connection to fail if the cert verification fails.
+ <parameter><parameter>$i</parameter></parameter> should be a boolean
+ value. Default value: <constant>TRUE</constant>. To specify custom
+ SSL certificates to validate the server with, use the
+ <methodname>setCaCertificate</methodname> method.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Variables</title>
+
+ <para>NB: direct manipulation of these variables is only recommended
+ for advanced users.</para>
+
+ <sect3>
+ <title>no_multicall</title>
+
+ <para>This member variable determines whether the multicall() method
+ will try to take advantage of the system.multicall xmlrpc method to
+ dispatch to the server an array of requests in a single http
+ roundtrip or simply execute many consecutive http calls. Defaults to
+ FALSE, but it will be enabled automatically on the first failure of
+ execution of system.multicall.</para>
+ </sect3>
+
+ <sect3>
+ <title>request_charset_encoding</title>
+
+ <para>This is the charset encoding that will be used for serializing
+ request sent by the client.</para>
+
+ <para>If defaults to NULL, which means using US-ASCII and encoding
+ all characters outside of the ASCII range using their xml character
+ entity representation (this has the benefit that line end characters
+ will not be mangled in the transfer, a CR-LF will be preserved as
+ well as a singe LF).</para>
+
+ <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>
+ </sect3>
+
+ <sect3 id="return-type" xreflabel="return_type">
+ <title>return_type</title>
+
+ <para>This member variable determines whether the value returned
+ inside an xmlrpcresp object as results of calls to the send() and
+ multicall() methods will be an xmlrpcval object, a plain php value
+ or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
+ 'phpvals' and 'xml'. To allow the user to differentiate between a
+ correct and a faulty response, fault responses will be returned as
+ xmlrpcresp objects in any case. Note that the 'phpvals' setting will
+ yield faster execution times, but some of the information from the
+ original response will be lost. It will be e.g. impossible to tell
+ whether a particular php string value was sent by the server as an
+ xmlrpc string or base64 value.</para>
+
+ <para>Example usage:</para>
+
+ <programlisting language="php">
+$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server");
+$client->return_type = 'phpvals';
+$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
+$resp = $client->send($message);
+if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();
+</programlisting>
+
+ <para>For more details about usage of the 'xml' value, see Appendix
+ A.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">
+ <title>xmlrpcresp</title>
+
+ <para>This class is used to contain responses to XML-RPC requests. A
+ server method handler will construct an
+ <classname>xmlrpcresp</classname> and pass it as a return value. This
+ same value will be returned by the result of an invocation of the
+ <function>send</function> method of the
+ <classname>xmlrpc_client</classname> class.</para>
+
+ <sect2>
+ <title>Creation</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcresp</type>new
+ <function>xmlrpcresp</function></funcdef>
+
+ <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>xmlrpcresp</type>new
+ <function>xmlrpcresp</function></funcdef>
+
+ <paramdef><parameter>0</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>The first syntax is used when execution has happened without
+ difficulty: <parameter>$xmlrpcval</parameter> is an
+ <classname>xmlrpcval</classname> value with the result of the method
+ execution contained in it. Alternatively it can be a string containing
+ the xml serialization of the single xml-rpc value result of method
+ execution.</para>
+
+ <para>The second type of constructor is used in case of failure.
+ <parameter>errcode</parameter> and <parameter>err_string</parameter>
+ are used to provide indication of what has gone wrong. See <xref
+ linkend="xmlrpc-server" /> for more information on passing error
+ codes.</para>
+ </sect2>
+
+ <sect2>
+ <title>Methods</title>
+
+ <sect3>
+ <title>faultCode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>faultCode</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns the integer fault code return from the XML-RPC
+ response. A zero value indicates success, any other value indicates
+ a failure response.</para>
+ </sect3>
+
+ <sect3>
+ <title>faultString</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>faultString</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns the human readable explanation of the fault indicated
+ by <function>$resp->faultCode</function>().</para>
+ </sect3>
+
+ <sect3>
+ <title>value</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type><function>value</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns an <classname>xmlrpcval</classname> object containing
+ the return value sent by the server. If the response's
+ <function>faultCode</function> is non-zero then the value returned
+ by this method should not be used (it may not even be an
+ object).</para>
+
+ <para>Note: if the xmlrpcresp instance in question has been created
+ by an <classname>xmlrpc_client</classname> object whose
+ <varname>return_type</varname> was set to 'phpvals', then a plain
+ php value will be returned instead of an
+ <classname>xmlrpcval</classname> object. If the
+ <varname>return_type</varname> was set to 'xml', an xml string will
+ be returned (see the return_type member var above for more
+ details).</para>
+ </sect3>
+
+ <sect3>
+ <title>serialize</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>serialize</function></funcdef>
+
+ <void />
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns an XML string representation of the response (xml
+ prologue not included).</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">
+ <title>xmlrpc_server</title>
+
+ <para>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:</para>
+
+ <programlisting language="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"),
+ ));
+</programlisting>
+
+ <para>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
+ <classname>xmlrpcresp</classname> object, that will be serialized back
+ to the caller.</para>
+
+ <sect2>
+ <title>Method handler functions</title>
+
+ <para>Both php functions and class methods can be registered as xmlrpc
+ method handlers.</para>
+
+ <para>The synopsis of a method handler function is:</para>
+
+ <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>
+
+ <para>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
+ below).</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
+ server with two parameters, the first being the server itself and the
+ second being the <classname>xmlrpcmsg</classname> object.</para>
+
+ <para>The same php function can be registered as handler of multiple
+ xmlrpc methods.</para>
+
+ <para>Here is a more detailed example of what the handler function
+ <function>foo</function> may do:</para>
+
+ <programlisting language="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"));
+ }
+ }
+</programlisting>
+
+ <para>See <filename>server.php</filename> in this distribution for
+ more examples of how to do this.</para>
+
+ <para>Since release 2.0RC3 there is a new, even simpler way of
+ registering php functions with the server. See section 5.7
+ below</para>
+ </sect2>
+
+ <sect2>
+ <title>The dispatch map</title>
+
+ <para>The first argument to the <function>xmlrpc_server</function>
+ constructor is an array, called the <emphasis>dispatch map</emphasis>.
+ In this array is the information the server needs to service the
+ XML-RPC methods you define.</para>
+
+ <para>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:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><function><literal>function</literal></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).</para>
+ </listitem>
+
+ <listitem>
+ <para><function><literal>signature</literal></function> - this
+ entry is an array containing the possible signatures (see <xref
+ linkend="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.</para>
+ </listitem>
+
+ <listitem>
+ <para><function><literal>docstring</literal></function> - this
+ entry is a string containing documentation for the method. The
+ documentation may contain HTML markup.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>signature_docs</literal> - this entry can be used
+ to provide documentation for the single parameters. It must match
+ in structure the 'signature' member. By default, only the
+ <classname>documenting_xmlrpc_server</classname> class in the
+ extras package will take advantage of this, since the
+ "system.methodHelp" protocol does not support documenting method
+ parameters individually.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Look at the <filename>server.php</filename> example in the
+ distribution to see what a dispatch map looks like.</para>
+ </sect2>
+
+ <sect2 id="signatures" xreflabel="Signatures">
+ <title>Method signatures</title>
+
+ <para>A signature is a description of a method's return type and its
+ parameter types. A method may have more than one signature.</para>
+
+ <para>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 <programlisting
+ language="php">string examples.getStateName(int)
+</programlisting> has the signature <programlisting language="php">array($xmlrpcString, $xmlrpcInt)
+</programlisting> and, assuming that it is the only possible signature for the
+ method, it might be used like this in server creation: <programlisting
+ language="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
+ )));
+</programlisting></para>
+
+ <para>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.</para>
+
+ <para>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 <varname>$xmlrpcValue</varname>, which can be
+ used in method signatures as a placeholder for 'any xmlrpc
+ type':</para>
+
+ <para><programlisting language="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
+ )));
+</programlisting></para>
+
+ <para>Methods <methodname>system.listMethods</methodname>,
+ <methodname>system.methodHelp</methodname>,
+ <methodname>system.methodSignature</methodname> and
+ <methodname>system.multicall</methodname> are already defined by the
+ server, and should not be reimplemented (see Reserved Methods
+ below).</para>
+ </sect2>
+
+ <sect2>
+ <title>Delaying the server response</title>
+
+ <para>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 <literal>0</literal> this will have the desired
+ effect. You can then use the <function>service()</function> method of
+ the server class to service the request. For example:</para>
+
+ <programlisting language="php">
+$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
+
+// ... some code that does other stuff here
+
+$s->service();
+</programlisting>
+
+ <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>
+
+ <para>To prevent the server from sending HTTP headers back to the
+ client, you can pass a second parameter with a value of
+ <literal>TRUE</literal> to the <methodname>service</methodname>
+ method. In this case, the response payload will be returned instead of
+ the response object.</para>
+
+ <para>Xmlrpc requests retrieved by other means than HTTP POST bodies
+ can also be processed. For example:</para>
+
+ <programlisting language="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
+</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Modifying the server behaviour</title>
+
+ <para>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)</para>
+
+ <sect3>
+ <title>setDebug()</title>
+
+ <para>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.</para>
+ </sect3>
+
+ <sect3>
+ <title>allow_system_funcs</title>
+
+ <para>Default_value: TRUE. When set to FALSE, disables support for
+ <methodname>System.xxx</methodname> functions in the server. It
+ might be useful e.g. if you do not wish the server to respond to
+ requests to <methodname>System.ListMethods</methodname>.</para>
+ </sect3>
+
+ <sect3>
+ <title>compress_response</title>
+
+ <para>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.</para>
+
+ <para>Note that the ZLIB php extension must be installed for this to
+ work. If it is, <varname>compress_response</varname> will default to
+ TRUE.</para>
+ </sect3>
+
+ <sect3>
+ <title>response_charset_encoding</title>
+
+ <para>Charset encoding to be used for response (only affects string
+ values).</para>
+
+ <para>If it can, the server will convert the generated response from
+ internal_encoding to the intended one.</para>
+
+ <para>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).</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Fault reporting</title>
+
+ <para>Fault codes for your servers should start at the value indicated
+ by the global <literal>$xmlrpcerruser</literal> + 1.</para>
+
+ <para>Standard errors returned by the server include:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>1</literal> <phrase>Unknown method</phrase></term>
+
+ <listitem>
+ <para>Returned if the server was asked to dispatch a method it
+ didn't know about</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>2</literal> <phrase>Invalid return
+ payload</phrase></term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>3</literal> <phrase>Incorrect
+ parameters</phrase></term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>4</literal> <phrase>Can't introspect: method
+ unknown</phrase></term>
+
+ <listitem>
+ <para>This error is generated by the builtin
+ <function>system.*</function> methods when any kind of
+ introspection is attempted on a method undefined by the
+ server.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>5</literal> <phrase>Didn't receive 200 OK from
+ remote server</phrase></term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>6</literal> <phrase>No data received from
+ server</phrase></term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>7</literal> <phrase>No SSL support compiled
+ in</phrase></term>
+
+ <listitem>
+ <para>This error is generated by the client when trying to send
+ a request with HTTPS and the CURL extension is not available to
+ PHP.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>8</literal> <phrase>CURL error</phrase></term>
+
+ <listitem>
+ <para>This error is generated by the client when trying to send
+ a request with HTTPS and the HTTPS communication fails.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>9-14</literal> <phrase>multicall
+ errors</phrase></term>
+
+ <listitem>
+ <para>These errors are generated by the server when something
+ fails inside a system.multicall request.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>100-</literal> <phrase>XML parse
+ errors</phrase></term>
+
+ <listitem>
+ <para>Returns 100 plus the XML parser error code for the fault
+ that occurred. The <function>faultString</function> returned
+ explains where the parse error was in the incoming XML
+ stream.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>'New style' servers</title>
+
+ <para>In the same spirit of simplification that inspired the
+ <varname>xmlrpc_client::return_type</varname> class variable, a new
+ class variable has been added to the server class:
+ <varname>functions_parameters_type</varname>. 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:<programlisting language="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();
+</programlisting>There are a few things to keep in mind when using this
+ 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>
+
+ <para>to return a base64 value, the method handler function must
+ encode it on its own, creating an instance of an xmlrpcval
+ object;</para>
+
+ <para>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;</para>
+
+ <para>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;</para>
+
+ <para>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;</para>
+
+ <para>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.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="globalvars">
+ <title>Global variables</title>
+
+ <para>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.</para>
+
+ <sect1>
+ <title>"Constant" variables</title>
+
+ <sect2>
+ <title>$xmlrpcerruser</title>
+
+ <para><fieldsynopsis>
+ <varname>$xmlrpcerruser</varname>
+
+ <initializer>800</initializer>
+ </fieldsynopsis>The minimum value for errors reported by user
+ implemented XML-RPC servers. Error numbers lower than that are
+ reserved for library usage.</para>
+ </sect2>
+
+ <sect2>
+ <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
+ $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,
+ $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>
+
+ <para>For convenience the strings representing the XML-RPC types have
+ been encoded as global variables:<programlisting language="php">
+$xmlrpcI4="i4";
+$xmlrpcInt="int";
+$xmlrpcBoolean="boolean";
+$xmlrpcDouble="double";
+$xmlrpcString="string";
+$xmlrpcDateTime="dateTime.iso8601";
+$xmlrpcBase64="base64";
+$xmlrpcArray="array";
+$xmlrpcStruct="struct";
+$xmlrpcValue="undefined";
+$xmlrpcNull="null";
+</programlisting></para>
+ </sect2>
+
+ <sect2>
+ <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
+ $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
+ $xmlEntities, $xmlrpcs_capabilities</title>
+
+ <para>Reserved for internal usage.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Variables whose value can be modified</title>
+
+ <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">
+ <title xreflabel="">xmlrpc_defencoding</title>
+
+ <fieldsynopsis>
+ <varname>$xmlrpc_defencoding</varname>
+
+ <initializer>"UTF8"</initializer>
+ </fieldsynopsis>
+
+ <para>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).</para>
+
+ <para>Allowed values: <literal>"UTF8"</literal>,
+ <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>
+
+ <para>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.</para>
+ </sect2>
+
+ <sect2>
+ <title>xmlrpc_internalencoding</title>
+
+ <para><fieldsynopsis>
+ <varname>$xmlrpc_internalencoding</varname>
+
+ <initializer>"ISO-8859-1"</initializer>
+ </fieldsynopsis>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:</para>
+
+ <para><programlisting language="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'
+</programlisting></para>
+ </sect2>
+
+ <sect2>
+ <title>xmlrpcName</title>
+
+ <para><fieldsynopsis>
+ <varname>$xmlrpcName</varname>
+
+ <initializer>"XML-RPC for PHP"</initializer>
+ </fieldsynopsis>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.</para>
+ </sect2>
+
+ <sect2>
+ <title>xmlrpcVersion</title>
+
+ <para><fieldsynopsis>
+ <varname>$xmlrpcVersion</varname>
+
+ <initializer>"2.2"</initializer>
+ </fieldsynopsis>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.</para>
+ </sect2>
+
+ <sect2>
+ <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>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="helpers">
+ <title>Helper functions</title>
+
+ <para>XML-RPC for PHP contains some helper functions which you can use to
+ make processing of XML-RPC requests easier.</para>
+
+ <sect1>
+ <title>Date functions</title>
+
+ <para>The XML-RPC specification has this to say on dates:</para>
+
+ <blockquote>
+ <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be
+ specified by the server in its documentation what assumptions it makes
+ about timezones.</para>
+ </blockquote>
+
+ <para>Unfortunately, this means that date processing isn't
+ straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
+ use the timezone specifier.</para>
+
+ <para>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.</para>
+
+ <para>For more information about dates, see <ulink
+ url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right
+ Format for Dates</ulink>, 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.</para>
+
+ <sect2 id="iso8601encode" xreflabel="iso8601_encode()">
+ <title>iso8601_encode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>iso8601_encode</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>
+
+ <paramdef
+ choice="opt"><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns an ISO 8601 formatted date generated from the UNIX
+ timestamp <parameter>$time_t</parameter>, as returned by the PHP
+ function <function>time()</function>.</para>
+
+ <para>The argument <parameter>$utc</parameter> can be omitted, in
+ which case it defaults to <literal>0</literal>. If it is set to
+ <literal>1</literal>, then the function corrects the time passed in
+ for UTC. Example: if you're in the GMT-6:00 timezone and set
+ <parameter>$utc</parameter>, you will receive a date representation
+ six hours ahead of your local time.</para>
+
+ <para>The included demo program <filename>vardemo.php</filename>
+ includes a demonstration of this function.</para>
+ </sect2>
+
+ <sect2 id="iso8601decode" xreflabel="iso8601_decode()">
+ <title>iso8601_decode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>int</type><function>iso8601_decode</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>
+
+ <paramdef><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date
+ string passed in. If <parameter>$utc</parameter> is
+ <literal>1</literal> then <parameter>$isoString</parameter> 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.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="arrayuse">
+ <title>Easy use with nested PHP values</title>
+
+ <para>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
+ <type>int</type>, <type>double</type>, <type>string</type>,
+ <type>array</type>, <type>datetime</type> and <type>struct</type>
+ 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.</para>
+
+ <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>
+
+ <sect2 id="phpxmlrpcdecode">
+ <title>php_xmlrpc_decode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>mixed</type><function>php_xmlrpc_decode</function></funcdef>
+
+ <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
+
+ <paramdef><type>array</type><parameter>$options</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>array</type><function>php_xmlrpc_decode</function></funcdef>
+
+ <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$options</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns a native PHP value corresponding to the values found in
+ the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,
+ translated into PHP types. Base-64 and datetime values are
+ automatically decoded to strings.</para>
+
+ <para>In the second form, returns an array containing the parameters
+ of the given
+ <parameter><classname>xmlrpcmsg</classname>_val</parameter>, decoded
+ to php types.</para>
+
+ <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
+ <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>
+
+ <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
+ extreme care before enabling the <symbol>decode_php_objs</symbol>
+ 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.</para>
+
+ <para>Example:<programlisting language="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" => ...
+ )));
+</programlisting></para>
+ </sect2>
+
+ <sect2 id="phpxmlrpcencode">
+ <title>php_xmlrpc_encode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type><function>php_xmlrpc_encode</function></funcdef>
+
+ <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
+
+ <paramdef><type>array</type><parameter>$options</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Returns an <type>xmlrpcval</type> object populated with the PHP
+ values in <parameter>$phpval</parameter>. 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.</para>
+
+ <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>
+
+ <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>
+
+ <para>Example:<programlisting language="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'));
+</programlisting></para>
+ </sect2>
+
+ <sect2>
+ <title>php_xmlrpc_decode_xml</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval | xmlrpcresp |
+ xmlrpcmsg</type><function>php_xmlrpc_decode_xml</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$xml</parameter></paramdef>
+
+ <paramdef><type>array</type><parameter>$options</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Decodes the xml representation of either an xmlrpc request,
+ response or single value, returning the corresponding php-xmlrpc
+ object, or <literal>FALSE</literal> in case of an error.</para>
+
+ <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, no option is supported.</para>
+
+ <para>Example:<programlisting language="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';
+</programlisting></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Automatic conversion of php functions into xmlrpc methods (and
+ vice versa)</title>
+
+ <para>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.</para>
+
+ <sect2>
+ <title>wrap_xmlrpc_method</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
+
+ <paramdef>$client</paramdef>
+
+ <paramdef>$methodname</paramdef>
+
+ <paramdef>$extra_options</paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
+
+ <paramdef>$client</paramdef>
+
+ <paramdef>$methodname</paramdef>
+
+ <paramdef>$signum</paramdef>
+
+ <paramdef>$timeout</paramdef>
+
+ <paramdef>$protocol</paramdef>
+
+ <paramdef>$funcname</paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Given 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.</para>
+
+ <para>The second syntax is deprecated, and is listed here only for
+ backward compatibility.</para>
+
+ <para>The server must support the
+ <methodname>system.methodSignature</methodname> xmlrpc method call for
+ this function to work.</para>
+
+ <para>The <parameter>client</parameter> 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.</para>
+
+ <para>The optional parameters can be passed as array key,value pairs
+ in the <parameter>extra_options</parameter> param.</para>
+
+ <para>The <parameter>signum</parameter> optional param has the purpose
+ of indicating which method signature to use, if the given server
+ method has multiple signatures (defaults to 0).</para>
+
+ <para>The <parameter>timeout</parameter> and
+ <parameter>protocol</parameter> optional params are the same as in the
+ <methodname>xmlrpc_client::send()</methodname> method.</para>
+
+ <para>If set, the optional <parameter>new_function_name</parameter>
+ parameter indicates which name should be used for the generated
+ function. In case it is not set the function name will be
+ auto-generated.</para>
+
+ <para>If the <literal>return_source</literal> 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).</para>
+
+ <para>If the <literal>encode_php_objs</literal> 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.</para>
+
+ <para>If the <literal>decode_php_objs</literal> 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).</para>
+
+ <para><emphasis>Note that this might pose a security risk</emphasis>,
+ 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.</para>
+
+ <para>In case of an error during generation of the wrapper function,
+ FALSE is returned, otherwise the name (or source code) of the new
+ function.</para>
+
+ <para>Known limitations: server must support
+ <methodname>system.methodsignature</methodname> 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.</para>
+
+ <para>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.</para>
+
+ <para>Example usage:</para>
+
+ <programlisting language="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";
+}
+</programlisting>
+ </sect2>
+
+ <sect2 id="wrap_php_function">
+ <title>wrap_php_function</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>array</type><function>wrap_php_function</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>
+
+ <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>
+
+ <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Given 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.</para>
+
+ <para>The optional <parameter>$wrapper_function_name</parameter>
+ specifies the name that will be used for the auto-generated
+ function.</para>
+
+ <para>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).</para>
+
+ <para>Known limitations: requires PHP 5.0.3 +; 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.</para>
+
+ <para>If the <literal>return_source</literal> 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
+ <literal>source</literal> member of the returned array.</para>
+
+ <para>If the <literal>suppress_warnings</literal> 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.</para>
+
+ <para>If the <parameter>extra_options</parameter> array contains the
+ <literal>encode_php_objs</literal> 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.</para>
+
+ <para>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)</para>
+
+ <para>If the <literal>decode_php_objs</literal> 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).</para>
+
+ <para><emphasis>Note that this might pose a security risk</emphasis>,
+ 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.</para>
+
+ <para>Example usage:</para>
+
+ <para><programlisting language="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);
+</programlisting></para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="deprecated">
+ <title>Functions removed from the library</title>
+
+ <para>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.</para>
+
+ <para>To ease the transition to the new naming scheme and avoid breaking
+ existing implementations, the following scheme has been adopted:
+ <itemizedlist>
+ <listitem>
+ <para>If EPI-XMLRPC is not active in the current PHP installation,
+ the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
+ <literal>'0'</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>If EPI-XMLRPC is active in the current PHP installation, the
+ constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
+ <literal>'1'</literal></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The following documentation is kept for historical
+ reference:</para>
+
+ <sect2 id="xmlrpcdecode">
+ <title>xmlrpc_decode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>mixed</type><function>xmlrpc_decode</function></funcdef>
+
+ <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Alias for php_xmlrpc_decode.</para>
+ </sect2>
+
+ <sect2 id="xmlrpcencode">
+ <title>xmlrpc_encode</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>xmlrpcval</type><function>xmlrpc_encode</function></funcdef>
+
+ <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Alias for php_xmlrpc_encode.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="debugging">
+ <title>Debugging aids</title>
+
+ <sect2>
+ <title>xmlrpc_debugmsg</title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><type>void</type><function>xmlrpc_debugmsg</function></funcdef>
+
+ <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <para>Sends the contents of <parameter>$debugstring</parameter> 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.</para>
+
+ <para>Use this function in your methods so you can pass back
+ diagnostic information. It is only available from
+ <filename>xmlrpcs.inc</filename>.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="reserved" xreflabel="Reserved methods">
+ <title>Reserved methods</title>
+
+ <para>In order to extend the functionality offered by XML-RPC servers
+ without impacting on the protocol, reserved methods are supported in this
+ release.</para>
+
+ <para>All methods starting with <function>system.</function> are
+ considered reserved by the server. PHP for XML-RPC itself provides four
+ special methods, detailed in this chapter.</para>
+
+ <para>Note that all server objects will automatically respond to clients
+ querying these methods, unless the property
+ <property>allow_system_funcs</property> has been set to
+ <constant>false</constant> before calling the
+ <methodname>service()</methodname> method. This might pose a security risk
+ if the server is exposed to public access, e.g. on the internet.</para>
+
+ <sect1>
+ <title>system.getCapabilities</title>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>system.listMethods</title>
+
+ <para>This method may be used to enumerate the methods implemented by
+ the XML-RPC server.</para>
+
+ <para>The <function>system.listMethods</function> method requires no
+ parameters. It returns an array of strings, each of which is the name of
+ a method implemented by the server.</para>
+ </sect1>
+
+ <sect1 id="sysmethodsig">
+ <title>system.methodSignature</title>
+
+ <para>This method takes one parameter, the name of a method implemented
+ by the XML-RPC server.</para>
+
+ <para>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.</para>
+
+ <para>Multiple signatures (i.e. overloading) are permitted: this is the
+ reason that an array of signatures are returned by this method.</para>
+
+ <para>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".</para>
+
+ <para>For parameters that can be of more than one type, the "undefined"
+ string is supported.</para>
+
+ <para>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
+ <parameter>$resp</parameter> below is the response object from a method
+ call to <function>system.methodSignature</function>:</para>
+
+ <programlisting language="php">
+$v = $resp->value();
+if ($v->kindOf() != "array") {
+ // then the method did not have a signature defined
+}
+</programlisting>
+
+ <para>See the <filename>introspect.php</filename> demo included in this
+ distribution for an example of using this method.</para>
+ </sect1>
+
+ <sect1 id="sysmethhelp">
+ <title>system.methodHelp</title>
+
+ <para>This method takes one parameter, the name of a method implemented
+ by the XML-RPC server.</para>
+
+ <para>It returns a documentation string describing the use of that
+ method. If no such string is available, an empty string is
+ returned.</para>
+
+ <para>The documentation string may contain HTML markup.</para>
+ </sect1>
+
+ <sect1>
+ <title>system.multicall</title>
+
+ <para>This method takes one parameter, an array of 'request' struct
+ types. Each request struct must contain a
+ <parameter>methodName</parameter> member of type string and a
+ <parameter>params</parameter> member of type array, and corresponds to
+ the invocation of the corresponding method.</para>
+
+ <para>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.</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="examples" xreflabel="Examples">
+ <title>Examples</title>
+
+ <para>The best examples are to be found in the sample files included with
+ the distribution. Some are included here.</para>
+
+ <sect1 id="statename">
+ <title>XML-RPC client: state name query</title>
+
+ <para>Code to get the corresponding state name from a number (1-50) from
+ the demo server available on SourceForge</para>
+
+ <programlisting language="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>";
+ }
+</programlisting>
+ </sect1>
+
+ <sect1>
+ <title>Executing a multicall call</title>
+
+ <para>To be documented...</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="faq">
+ <title>Frequently Asked Questions</title>
+
+ <sect1>
+ <title>How to send custom XML as payload of a method call</title>
+
+ <para>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.</para>
+
+ <para>To send an XML "chunk" as payload of a method call or response,
+ two options are available: either send the complete XML block as a
+ string xmlrpc value, or as a base64 value. Since the '<' character in
+ string values is encoded as '&lt;' in the xml payload of the method
+ call, the XML string will not break the surrounding xmlrpc, unless
+ characters outside of the assumed character set are used. The second
+ method has the added benefits of working independently of the charset
+ encoding used for the xml to be transmitted, and preserving exactly
+ whitespace, whilst incurring in some extra message length and cpu load
+ (for carrying out the base64 encoding/decoding).</para>
+ </sect1>
+
+ <sect1>
+ <title>Is there any limitation on the size of the requests / responses
+ that can be successfully sent?</title>
+
+ <para>Yes. But I have no hard figure to give; it most likely will depend
+ on the version of PHP in usage and its configuration.</para>
+
+ <para>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).</para>
+
+ <para>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.</para>
+
+ <para>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 <varname>xmlrpc_client::return_type</varname>
+ and <varname>xmlrpc_server::functions_parameters_type</varname> for more
+ details).</para>
+ </sect1>
+
+ <sect1>
+ <title>My server (client) returns an error whenever the client (server)
+ returns accented characters</title>
+
+ <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>To be documented...</para>
+ </sect1>
+
+ <sect1>
+ <title>My client returns "XML-RPC Fault #2: Invalid return payload:
+ enable debugging to examine incoming payload": what should I do?</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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);</para>
+ </sect1>
+
+ <sect1>
+ <title>How can I save to a file the xml of the xmlrpc responses received
+ from servers?</title>
+
+ <para>If what you need is to save the responses received from the server
+ as xml, you have two options:</para>
+
+ <para>1- use the serialize() method on the response object.</para>
+
+ <programlisting language="php">
+$resp = $client->send($msg);
+if (!$resp->faultCode())
+ $data_to_be_saved = $resp->serialize();
+</programlisting>
+
+ <para>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).</para>
+
+ <para>2 - set the client object to return the raw xml received instead
+ of the decoded objects:</para>
+
+ <programlisting language="php">
+$client = new xmlrpc_client($url);
+$client->return_type = 'xml';
+$resp = $client->send($msg);
+if (!$resp->faultCode())
+ $data_to_be_saved = $resp->value();
+</programlisting>
+
+ <para>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...</para>
+ </sect1>
+
+ <sect1>
+ <title>Can I use the ms windows character set?</title>
+
+ <para>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.</para>
+
+ <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
+ 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.</para>
+
+ <para>To properly encode outgoing data that is natively in CP1252, you
+ will have to uncomment all relative code in the file
+ <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>
+ </sect1>
+
+ <sect1>
+ <title>Does the library support using cookies / http sessions?</title>
+
+ <para>In short: yes, but a little coding is needed to make it
+ happen.</para>
+
+ <para>The code below uses sessions to e.g. let the client store a value
+ on the server and retrieve it later.</para>
+
+ <para><programlisting>
+$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')));
+ }
+}
+</programlisting>Server-side sessions are handled normally like in any other
+ php application. Please see the php manual for more information about
+ sessions.</para>
+
+ <para>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.</para>
+ </sect1>
+ </chapter>
+
+ <appendix id="integration">
+ <title>Integration with the PHP xmlrpc extension</title>
+
+ <para>To be documented more...</para>
+
+ <para>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</para>
+
+ <programlisting language="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);
+}
+</programlisting>
+ </appendix>
+
+ <appendix id="substitution">
+ <title>Substitution of the PHP xmlrpc extension</title>
+
+ <para>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).</para>
+
+ <para>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</para>
+ </appendix>
+
+ <appendix id="enough">
+ <title>'Enough of xmlrpcvals!': new style library usage</title>
+
+ <para>To be documented...</para>
+
+ <para>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</para>
+ </appendix>
+
+ <appendix id="debugger">
+ <title>Usage of the debugger</title>
+
+ <para>A webservice debugger is included in the library to help during
+ development and testing.</para>
+
+ <para>The interface should be self-explicative enough to need little
+ documentation.</para>
+
+ <para><graphic align="center" fileref="debugger.gif"
+ format="GIF" /></para>
+
+ <para>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.</para>
+
+ <para>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:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>to enable jsonrpc functionality, download the PHP-XMLRPC
+ EXTRAS package, and copy the file <filename>jsonrpc.inc</filename>
+ either to the same directory as the debugger or somewhere in your
+ php include path</para>
+ </listitem>
+ </itemizedlist><itemizedlist>
+ <listitem>
+ <para>to enable the visual value editing dialog, download the
+ JS-XMLRPC library, and copy somewhere in the web root files
+ <filename>visualeditor.php</filename>,
+ <filename>visualeditor.css</filename> and the folders
+ <filename>yui</filename> and <filename>img</filename>. Then edit the
+ debugger file <filename>controller.php</filename> and set
+ appropriately the variable <varname>$editorpath</varname>.</para>
+ </listitem>
+ </itemizedlist></para>
+ </appendix>
+</book>
+<!-- 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:
+-->
git://git.onelab.eu / plcapi.git / commitdiff