1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
\r
3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
\r
4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
\r
6 PHP-XMLRPC User manual
\r
7 $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $
\r
10 <title>XML-RPC for PHP</title>
\r
12 <subtitle>version 2.2.2</subtitle>
\r
15 <date>XXX YY, 2008</date>
\r
19 <firstname>Edd</firstname>
\r
21 <surname>Dumbill</surname>
\r
25 <firstname>Gaetano</firstname>
\r
27 <surname>Giunta</surname>
\r
31 <firstname>Miles</firstname>
\r
33 <surname>Lott</surname>
\r
37 <firstname>Justin R.</firstname>
\r
39 <surname>Miller</surname>
\r
43 <firstname>Andres</firstname>
\r
45 <surname>Salomon</surname>
\r
50 <year>1999,2000,2001</year>
\r
52 <holder>Edd Dumbill, Useful Information Company</holder>
\r
56 <para>All rights reserved.</para>
\r
58 <para>Redistribution and use in source and binary forms, with or without
\r
59 modification, are permitted provided that the following conditions are
\r
62 <para><itemizedlist>
\r
64 <para>Redistributions of source code must retain the above
\r
65 copyright notice, this list of conditions and the following
\r
70 <para>Redistributions in binary form must reproduce the above
\r
71 copyright notice, this list of conditions and the following
\r
72 disclaimer in the documentation and/or other materials provided
\r
73 with the distribution.</para>
\r
77 <para>Neither the name of the "XML-RPC for PHP" nor the names of
\r
78 its contributors may be used to endorse or promote products
\r
79 derived from this software without specific prior written
\r
82 </itemizedlist></para>
\r
84 <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
\r
85 CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
\r
86 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
\r
87 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
\r
88 REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
\r
89 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
\r
90 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
\r
91 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
\r
92 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
\r
93 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
\r
94 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
\r
98 <chapter id="introduction">
\r
99 <title>Introduction</title>
\r
101 <para>XML-RPC is a format devised by <ulink
\r
102 url="http://www.userland.com/">Userland Software</ulink> for achieving
\r
103 remote procedure call via XML using HTTP as the transport. XML-RPC has its
\r
104 own web site, <ulink
\r
105 url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>
\r
107 <para>This collection of PHP classes provides a framework for writing
\r
108 XML-RPC clients and servers in PHP.</para>
\r
110 <para>Main goals of the project are ease of use, flexibility and
\r
111 completeness.</para>
\r
113 <para>The original author is Edd Dumbill of <ulink
\r
114 url="http://usefulinc.com/">Useful Information Company</ulink>. As of the
\r
115 1.0 stable release, the project has been opened to wider involvement and
\r
117 url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>.</para>
\r
119 <para>A list of XML-RPC implementations for other languages such as Perl
\r
120 and Python can be found on the <ulink
\r
121 url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>
\r
124 <title>Acknowledgements</title>
\r
126 <para>Daniel E. Baumann</para>
\r
128 <para>James Bercegay</para>
\r
130 <para>Leon Blackwell</para>
\r
132 <para>Stephane Bortzmeyer</para>
\r
134 <para>Daniel Convissor</para>
\r
136 <para>Geoffrey T. Dairiki</para>
\r
138 <para>Stefan Esser</para>
\r
140 <para>James Flemer</para>
\r
142 <para>Ernst de Haan</para>
\r
144 <para>Tom Knight</para>
\r
146 <para>Axel Kollmorgen</para>
\r
148 <para>Peter Kocks</para>
\r
150 <para>Daniel Krippner</para>
\r
152 <para>S. Kuip</para>
\r
154 <para>A. Lambert</para>
\r
156 <para>Dan Libby</para>
\r
158 <para>Arnaud Limbourg</para>
\r
160 <para>Ernest MacDougal Campbell III</para>
\r
162 <para>Lukasz Mach</para>
\r
164 <para>Kjartan Mannes</para>
\r
166 <para>Ben Margolin</para>
\r
168 <para>Nicolay Mausz</para>
\r
170 <para>Justin Miller</para>
\r
172 <para>Jan Pfeifer</para>
\r
174 <para>Giancarlo Pinerolo</para>
\r
176 <para>Peter Russel</para>
\r
178 <para>Viliam Simko</para>
\r
180 <para>Douglas Squirrel</para>
\r
182 <para>Idan Sofer</para>
\r
184 <para>Anatoly Techtonik</para>
\r
186 <para>Eric van der Vlist</para>
\r
188 <para>Christian Wenz</para>
\r
190 <para>Jim Winstead</para>
\r
192 <para>Przemyslaw Wroblewski</para>
\r
196 <chapter id="news">
\r
197 <title>What's new</title>
\r
199 <para><emphasis>Note:</emphasis> not all items the following list have
\r
200 (yet) been fully documented, and some might not be present in any other
\r
201 chapter in the manual. To find a more detailed description of new
\r
202 functions and methods please take a look at the source code of the
\r
203 library, which is quite thoroughly commented in javadoc-like form.</para>
\r
206 <title>2.2.2</title>
\r
208 <para><itemizedlist>
\r
210 <para>fixed: encoding of utf-8 characters outside of the BMP
\r
215 <para>fixed: character set declarations surrounded by double
\r
216 quotes were not recognized in http headers</para>
\r
218 </itemizedlist></para>
\r
222 <title>2.2.1</title>
\r
224 <para><emphasis>Note:</emphasis> this is the last release of the library
\r
225 that will support PHP 4. Future releases (if any) will target php 5.0 as
\r
226 minimum supported version.</para>
\r
230 <para>fixed: work aroung bug in php 5.2.2 which broke support of
\r
231 HTTP_RAW_POST_DATA</para>
\r
235 <para>fixed: is_dir parameter of setCaCertificate() method is
\r
240 <para>fixed: a php warning in xmlrpc_client creator method</para>
\r
244 <para>fixed: parsing of '1e+1' as valid float</para>
\r
248 <para>fixed: allow errorlevel 3 to work when prev. error handler was
\r
249 a static method</para>
\r
253 <para>fixed: usage of client::setcookie() for multiple cookies in
\r
254 non-ssl mode</para>
\r
258 <para>improved: support for CP1252 charset is not part or the
\r
259 library but almost possible</para>
\r
263 <para>improved: more info when curl is enabled and debug mode is
\r
274 <para>fixed: debugger errors on php installs with magic_quotes_gpc
\r
279 <para>fixed: support for https connections via proxy</para>
\r
283 <para>fixed: wrap_xmlrpc_method() generated code failed to properly
\r
284 encode php objects</para>
\r
288 <para>improved: slightly faster encoding of data which is internally
\r
293 <para>improved: debugger always generates a 'null' id for jsonrpc if
\r
294 user omits it</para>
\r
298 <para>new: debugger can take advantage of a graphical value builder
\r
299 (it has to be downloaded separately, as part of jsxmlrpc package.
\r
300 See Appendix D for more details)</para>
\r
304 <para>new: support for the <NIL/> xmlrpc extension. see below
\r
305 for more details</para>
\r
309 <para>new: server support for the system.getCapabilities xmlrpc
\r
314 <para>new: <function><link
\r
315 linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>
\r
316 accepts two new options: debug and return_on_fault</para>
\r
324 <para><itemizedlist>
\r
326 <para>The <function>wrap_php_function</function> and
\r
327 <function>wrap_xmlrpc_method</function> functions have been moved
\r
328 out of the base library file <filename>xmlrpc.inc</filename> into
\r
329 a file of their own: <filename>xmlrpc_wrappers.inc</filename>. You
\r
330 will have to include() / require() it in your scripts if you have
\r
331 been using those functions. For increased security, the automatic
\r
332 rebuilding of php object instances out of received xmlrpc structs
\r
333 in <function>wrap_xmlrpc_method()</function> has been disabled
\r
334 (but it can be optionally re-enabled). Both
\r
335 <function>wrap_php_function()</function> and
\r
336 <function>wrap_xmlrpc_method()</function> functions accept many
\r
337 more options to fine tune their behaviour, including one to return
\r
338 the php code to be saved and later used as standalone php
\r
343 <para>The constructor of xmlrpcval() values has seen some internal
\r
344 changes, and it will not throw a php warning anymore when invoked
\r
345 using an unknown xmlrpc type: the error will only be written to
\r
346 php error log. Also <code>new xmlrpcval('true', 'boolean')</code>
\r
347 is not supported anymore</para>
\r
351 <para>The new function
\r
352 <function>php_xmlrpc_decode_xml()</function> will take the xml
\r
353 representation of either an xmlrpc request, response or single
\r
354 value and return the corresponding php-xmlrpc object
\r
359 <para>A new function <function>wrap_xmlrpc_server()</function>has
\r
360 been added, to wrap all (or some) of the methods exposed by a
\r
361 remote xmlrpc server into a php class</para>
\r
365 <para>A new file has been added:
\r
366 <filename>verify_compat.php</filename>, to help users diagnose the
\r
367 level of compliance of their php installation with the
\r
372 <para>Restored compatibility with php 4.0.5 (for those poor souls
\r
373 still stuck on it)</para>
\r
377 <para>Method <methodname>xmlrpc_server->service()</methodname>
\r
378 now returns a value: either the response payload or xmlrpcresp
\r
379 object instance</para>
\r
384 <methodname>xmlrpc_server->add_to_map()</methodname> now
\r
385 accepts xmlrpc methods with no param definitions</para>
\r
389 <para>Documentation for single parameters of exposed methods can
\r
390 be added to the dispatch map (and turned into html docs in
\r
391 conjunction with a future release of the 'extras' package)</para>
\r
395 <para>Full response payload is saved into xmlrpcresp object for
\r
396 further debugging</para>
\r
400 <para>The debugger can now generate code that wraps a remote
\r
401 method into a php function (works for jsonrpc, too); it also has
\r
402 better support for being activated via a single GET call (e.g. for
\r
403 integration into other tools)</para>
\r
407 <para>Stricter parsing of incoming xmlrpc messages: two more
\r
408 invalid cases are now detected (double <literal>data</literal>
\r
409 element inside <literal>array</literal> and
\r
410 <literal>struct</literal>/<literal>array</literal> after scalar
\r
411 inside <literal>value</literal> element)</para>
\r
415 <para>More logging of errors in a lot of situations</para>
\r
419 <para>Javadoc documentation of lib files (almost) complete</para>
\r
423 <para>Many performance tweaks and code cleanups, plus the usual
\r
424 crop of bugs fixed (see NEWS file for complete list of
\r
429 <para>Lib internals have been modified to provide better support
\r
430 for grafting extra functionality on top of it. Stay tuned for
\r
431 future releases of the EXTRAS package (or go read Appendix
\r
434 </itemizedlist></para>
\r
438 <title>2.0 final</title>
\r
440 <para><itemizedlist>
\r
442 <para>Added to the client class the possibility to use Digest and
\r
443 NTLM authentication methods (when using the CURL library) for
\r
444 connecting to servers and NTLM for connecting to proxies</para>
\r
448 <para>Added to the client class the possibility to specify
\r
449 alternate certificate files/directories for authenticating the
\r
450 peer with when using HTTPS communication</para>
\r
454 <para>Reviewed all examples and added a new demo file, containing
\r
455 a proxy to forward xmlrpc requests to other servers (useful e.g.
\r
456 for ajax coding)</para>
\r
460 <para>The debugger has been upgraded to reflect the new client
\r
461 capabilities</para>
\r
465 <para>All known bugs have been squashed, and the lib is more
\r
466 tolerant than ever of commonly-found mistakes</para>
\r
468 </itemizedlist></para>
\r
472 <title>2.0 Release candidate 3</title>
\r
474 <para><itemizedlist>
\r
476 <para>Added to server class the property
\r
477 <property>functions_parameters_type</property>, that allows the
\r
478 server to register plain php functions as xmlrpc methods (i.e.
\r
479 functions that do not take an xmlrpcmsg object as unique
\r
484 <para>let server and client objects serialize calls using a
\r
485 specified character set encoding for the produced xml instead of
\r
486 US-ASCII (ISO-8859-1 and UTF-8 supported)</para>
\r
490 <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid
\r
495 <para>'class::method' syntax is now accepted in the server
\r
496 dispatch map</para>
\r
500 <para><function>xmlrpc_clent::SetDebug()</function> accepts
\r
501 integer values instead of a boolean value, with debugging level 2
\r
502 adding to the information printed to screen the complete client
\r
505 </itemizedlist></para>
\r
509 <title>2.0 Release candidate 2</title>
\r
511 <para><itemizedlist>
\r
513 <para>Added a new property of the client object:
\r
514 <code>xmlrpc_client->return_type</code>, indicating whether
\r
515 calls to the send() method will return xmlrpcresp objects whose
\r
516 value() is an xmlrpcval object, a php value (automatically
\r
517 decoded) or the raw xml received from the server.</para>
\r
521 <para>Added in the extras dir. two new library file:
\r
522 <filename>jsonrpc.inc</filename> and
\r
523 <filename>jsonrpcs.inc</filename> containing new classes that
\r
524 implement support for the json-rpc protocol (alpha quality
\r
529 <para>Added a new client method: <code>setKey($key,
\r
530 $keypass)</code> to be used in HTTPS connections</para>
\r
534 <para>Added a new file containing some benchmarks in the testsuite
\r
537 </itemizedlist></para>
\r
541 <title>2.0 Release candidate 1</title>
\r
545 <para>Support for HTTP proxies (new method:
\r
546 <code>xmlrpc_client::setProxy()</code>)</para>
\r
550 <para>Support HTTP compression of both requests and responses.
\r
551 Clients can specify what kind of compression they accept for
\r
552 responses between deflate/gzip/any, and whether to compress the
\r
553 requests. Servers by default compress responses to clients that
\r
554 explicitly declare support for compression (new methods:
\r
555 <code>xmlrpc_client::setAcceptedCompression()</code>,
\r
556 <code>xmlrpc_client::setRequestCompression()</code>). Note that the
\r
557 ZLIB php extension needs to be enabled in PHP to support
\r
558 compression.</para>
\r
562 <para>Implement HTTP 1.1 connections, but only if CURL is enabled
\r
563 (added an extra parameter to
\r
564 <code>xmlrpc_client::xmlrpc_client</code> to set the desired HTTP
\r
565 protocol at creation time and a new supported value for the last
\r
566 parameter of <code>xmlrpc_client::send</code>, which now can be
\r
567 safely omitted if it has been specified at creation time)</para>
\r
569 <para>With PHP versions greater than 4.3.8 keep-alives are enabled
\r
570 by default for HTTP 1.1 connections. This should yield faster
\r
571 execution times when making multiple calls in sequence to the same
\r
572 xml-rpc server from a single client.</para>
\r
576 <para>Introduce support for cookies. Cookies to be sent to the
\r
577 server with a request can be set using
\r
578 <code>xmlrpc_client::setCookie()</code>, while cookies received from
\r
579 the server are found in <code>xmlrpcresp::cookies()</code>. It is
\r
580 left to the user to check for validity of received cookies and
\r
581 decide whether they apply to successive calls or not.</para>
\r
585 <para>Better support for detecting different character set encodings
\r
586 of xml-rpc requests and responses: both client and server objects
\r
587 will correctly detect the charset encoding of received xml, and use
\r
588 an appropriate xml parser.</para>
\r
590 <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>
\r
594 <para>Added one new xmlrpcmsg constructor syntax, allowing usage of
\r
595 a single string with the complete URL of the target server</para>
\r
599 <para>Convert xml-rpc boolean values into native php values instead
\r
604 <para>Force the <code>php_xmlrpc_encode</code> function to properly
\r
605 encode numerically indexed php arrays into xml-rpc arrays
\r
606 (numerically indexed php arrays always start with a key of 0 and
\r
607 increment keys by values of 1)</para>
\r
611 <para>Prevent the <code>php_xmlrpc_encode</code> function from
\r
612 further re-encoding any objects of class <code>xmlrpcval</code> that
\r
613 are passed to it. This allows to call the function with arguments
\r
614 consisting of mixed php values / xmlrpcval objects.</para>
\r
618 <para>Allow a server to NOT respond to system.* method calls
\r
619 (setting the <code>$server->allow_system_funcs</code>
\r
624 <para>Implement a new xmlrpcval method to determine if a value of
\r
625 type struct has a member of a given name without having to loop
\r
626 trough all members: <code>xmlrpcval::structMemExists()</code></para>
\r
630 <para>Expand methods <code>xmlrpcval::addArray</code>,
\r
631 <code>addScalar</code> and <code>addStruct</code> allowing extra php
\r
632 values to be added to xmlrpcval objects already formed.</para>
\r
636 <para>Let the <code>xmlrpc_client::send</code> method accept an XML
\r
637 string for sending instead of an xmlrpcmsg object, to facilitate
\r
638 debugging and integration with the php native xmlrpc
\r
643 <para>Extend the <code>php_xmlrpc_encode</code> and
\r
644 <code>php_xmlrpc_decode</code> functions to allow serialization and
\r
645 rebuilding of PHP objects. To successfully rebuild a serialized
\r
646 object, the object class must be defined in the deserializing end of
\r
647 the transfer. Note that object members of type resource will be
\r
648 deserialized as NULL values.</para>
\r
650 <para>Note that his has been implemented adding a "php_class"
\r
651 attribute to xml representation of xmlrpcval of STRUCT type, which,
\r
652 strictly speaking, breaks the xml-rpc spec. Other xmlrpc
\r
653 implementations are supposed to ignore such an attribute (unless
\r
654 they implement a brain-dead custom xml parser...), so it should be
\r
655 safe enabling it in heterogeneous environments. The activation of
\r
656 this feature is done by usage of an option passed as second
\r
657 parameter to both <code>php_xmlrpc_encode</code> and
\r
658 <code>php_xmlrpc_decode</code>.</para>
\r
662 <para>Extend the <code>php_xmlrpc_encode</code> function to allow
\r
663 automatic serialization of iso8601-conforming php strings as
\r
664 datetime.iso8601 xmlrpcvals, by usage of an optional
\r
669 <para>Added an automatic stub code generator for converting xmlrpc
\r
670 methods to php functions and vice-versa.</para>
\r
672 <para>This is done via two new functions:
\r
673 <code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,
\r
674 and has many caveats, with php being a typeless language and
\r
677 <para>With PHP versions lesser than 5.0.3 wrapping of php functions
\r
678 into xmlrpc methods is not supported yet.</para>
\r
682 <para>Allow object methods to be used in server dispatch map</para>
\r
686 <para>Added a complete debugger solution, in the
\r
687 <filename>debugger</filename> folder</para>
\r
691 <para>Added configurable server-side debug messages, controlled by
\r
692 the new method <code>xmlrpc_server::SetDebug()</code>. At level 0,
\r
693 no debug messages are sent to the client; level 1 is the same as the
\r
694 old behaviour; at level 2 a lot more info is echoed back to the
\r
695 client, regarding the received call; at level 3 all warnings raised
\r
696 during server processing are trapped (this prevents breaking the xml
\r
697 to be echoed back to the client) and added to the debug info sent
\r
698 back to the client</para>
\r
702 <para>New XML parsing code, yields smaller memory footprint and
\r
703 faster execution times, not to mention complete elimination of the
\r
704 dreaded <filename>eval()</filename> construct, so prone to code
\r
705 injection exploits</para>
\r
709 <para>Rewritten most of the error messages, making text more
\r
716 <chapter id="requirements">
\r
717 <title>System Requirements</title>
\r
719 <para>The library has been designed with goals of scalability and backward
\r
720 compatibility. As such, it supports a wide range of PHP installs. Note
\r
721 that not all features of the lib are available in every
\r
722 configuration.</para>
\r
724 <para>The <emphasis>minimum supported</emphasis> PHP version is
\r
727 <para>A compatibility layer is provided that allows the code to run on PHP
\r
728 4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest
\r
729 you upgrade as soon as possible.</para>
\r
731 <para>Automatic generation of xml-rpc methods from php functions is only
\r
732 supported with PHP version 5.0.3 and later (note that the lib will
\r
733 generate some warnings with PHP 5 in strict error reporting mode).</para>
\r
735 <para>If you wish to use SSL or HTTP 1.1 to communicate with remote
\r
736 servers, you need the "curl" extension compiled into your PHP
\r
737 installation. This is available in PHP 4.0.2 and greater, although 4.0.6
\r
738 has a bug preventing SSL working, and versions prior to 4.3.8 do not
\r
739 support streamlining multiple requests using HTTP Keep-Alive.</para>
\r
741 <para>The "xmlrpc" native extension is not required to be compiled into
\r
742 your PHP installation, but if it is, there will be no interference with
\r
743 the operation of this library.</para>
\r
746 <chapter id="manifest">
\r
747 <title>Files in the distribution</title>
\r
751 <glossterm>lib/xmlrpc.inc</glossterm>
\r
754 <para>the XML-RPC classes. <function>include()</function> this in
\r
755 your PHP files to use the classes.</para>
\r
760 <glossterm>lib/xmlrpcs.inc</glossterm>
\r
763 <para>the XML-RPC server class. <function>include()</function> this
\r
764 in addition to xmlrpc.inc to get server functionality</para>
\r
769 <glossterm>lib/xmlrpc_wrappers.inc</glossterm>
\r
772 <para>helper functions to "automagically" convert plain php
\r
773 functions to xmlrpc services and vice versa</para>
\r
778 <glossterm>lib/compat/array_key_exists.php, lib/compat/is_a.php,
\r
779 lib/compat/is_scalar.php, lib/compat/var_export.php,
\r
780 lib/compat/vesrions_compare.php</glossterm>
\r
783 <para>compatibility functions: these files implement the
\r
784 compatibility layer needed to run the library with PHP versions 4.0
\r
790 <glossterm>demo/server/proxy.php</glossterm>
\r
793 <para>a sample server implementing xmlrpc proxy
\r
794 functionality.</para>
\r
799 <glossterm>demo/server/server.php</glossterm>
\r
802 <para>a sample server hosting various demo functions, as well as a
\r
803 full suite of functions used for interoperability testing. It is
\r
804 used by testsuite.php (see below) for unit testing the library, and
\r
805 is not to be copied literally into your production servers</para>
\r
810 <glossterm>demo/client/client.php, demo/client/agesort.php,
\r
811 demo/client/which.php</glossterm>
\r
814 <para>client code to exercise some of the functions in server.php,
\r
815 including the <function>interopEchoTests.whichToolkit</function>
\r
821 <glossterm>demo/client/wrap.php</glossterm>
\r
824 <para>client code to illustrate 'wrapping' of remote methods into
\r
825 php functions.</para>
\r
830 <glossterm>demo/client/introspect.php</glossterm>
\r
833 <para>client code to illustrate usage of introspection capabilities
\r
834 offered by server.php.</para>
\r
839 <glossterm>demo/client/mail.php</glossterm>
\r
842 <para>client code to illustrate usage of an xmlrpc-to-email gateway
\r
843 using Dave Winer's XML-RPC server at userland.com.</para>
\r
848 <glossterm>demo/client/zopetest.php</glossterm>
\r
851 <para>example client code that queries an xmlrpc server built in
\r
857 <glossterm>demo/vardemo.php</glossterm>
\r
860 <para>examples of how to construct xmlrpcval types</para>
\r
865 <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>
\r
868 <para>XML-RPC responses captured in a file for testing purposes (you
\r
869 can use these to test the
\r
870 <function>xmlrpcmsg->parseResponse()</function> method).</para>
\r
875 <glossterm>demo/server/discuss.php,
\r
876 demo/client/comment.php</glossterm>
\r
879 <para>Software used in the PHP chapter of <xref
\r
880 linkend="jellyfish" /> to provide a comment server and allow the
\r
881 attachment of comments to stories from Meerkat's data store.</para>
\r
886 <glossterm>test/testsuite.php, test/parse_args.php</glossterm>
\r
889 <para>A unit test suite for this software package. If you do
\r
890 development on this software, please consider submitting tests for
\r
896 <glossterm>test/benchmark.php</glossterm>
\r
899 <para>A (very limited) benchmarking suite for this software package.
\r
900 If you do development on this software, please consider submitting
\r
901 benchmarks for this suite.</para>
\r
906 <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>
\r
909 <para>An (incomplete) version PEAR's unit test framework for PHP.
\r
910 The complete package can be found at <ulink
\r
911 url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>
\r
916 <glossterm>test/verify_compat.php</glossterm>
\r
919 <para>Script designed to help the user to verify the level of
\r
920 compatibility of the library with the current php install</para>
\r
925 <glossterm>extras/test.pl, extras/test.py</glossterm>
\r
928 <para>Perl and Python programs to exercise server.php to test that
\r
929 some of the methods work.</para>
\r
934 <glossterm>extras/workspace.testPhpServer.fttb</glossterm>
\r
937 <para>Frontier scripts to exercise the demo server. Thanks to Dave
\r
938 Winer for permission to include these. See <ulink
\r
939 url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's
\r
940 announcement of these.</ulink></para>
\r
945 <glossterm>extras/rsakey.pem</glossterm>
\r
948 <para>A test certificate key for the SSL support, which can be used
\r
949 to generate dummy certificates. It has the passphrase "test."</para>
\r
955 <chapter id="bugs">
\r
956 <title>Known bugs and limitations</title>
\r
958 <para>This started out as a bare framework. Many "nice" bits haven't been
\r
959 put in yet. Specifically, very little type validation or coercion has been
\r
960 put in. PHP being a loosely-typed language, this is going to have to be
\r
961 done explicitly (in other words: you can call a lot of library functions
\r
962 passing them arguments of the wrong type and receive an error message only
\r
963 much further down the code, where it will be difficult to
\r
964 understand).</para>
\r
966 <para>dateTime.iso8601 is supported opaquely. It can't be done natively as
\r
967 the XML-RPC specification explicitly forbids passing of timezone
\r
968 specifiers in ISO8601 format dates. You can, however, use the <xref
\r
969 linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions
\r
970 to do the encoding and decoding for you.</para>
\r
972 <para>Very little HTTP response checking is performed (e.g. HTTP redirects
\r
973 are not followed and the Content-Length HTTP header, mandated by the
\r
974 xml-rpc spec, is not validated); cookie support still involves quite a bit
\r
975 of coding on the part of the user.</para>
\r
977 <para>If a specific character set encoding other than US-ASCII, ISO-8859-1
\r
978 or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
\r
979 or response messages then it will be ignored for the moment, and the
\r
980 content will be parsed as if it had been encoded using the charset defined
\r
981 by <xref linkend="xmlrpc-defencoding" /></para>
\r
983 <para>Very large floating point numbers are serialized using exponential
\r
984 notation, even though the spec explicitly forbids this behaviour. This
\r
985 will not be a problem if this library is used on both ends of the
\r
986 communication, but might cause problems with other implementations.</para>
\r
988 <para>Support for receiving from servers version 1 cookies (i.e.
\r
989 conforming to RFC 2965) is quite incomplete, and might cause unforeseen
\r
992 <para>A PHP warning will be generated in many places when using
\r
993 <filename>xmlrpc.inc</filename> and <filename>xmlrpcs.inc</filename> with
\r
994 PHP 5 in strict error reporting mode. The simplest workaround to this
\r
995 problem is to lower the <parameter>error_reporting</parameter> level in
\r
999 <chapter id="support">
\r
1000 <title>Support</title>
\r
1003 <title>Online Support</title>
\r
1005 <para>XML-RPC for PHP is offered "as-is" without any warranty or
\r
1006 commitment to support. However, informal advice and help is available
\r
1007 via the XML-RPC for PHP website and mailing list and from
\r
1008 XML-RPC.com.</para>
\r
1012 <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
\r
1014 url="http://phpxmlrpc.sourceforge.net">phpxmlrpc.sourceforge.net</ulink>.
\r
1015 Bugs, feature requests and patches can be posted to the <ulink
\r
1016 url="http://sourceforge.net/projects/phpxmlrpc">project's
\r
1017 website</ulink>.</para>
\r
1021 <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is
\r
1022 run by the author. More details <ulink
\r
1023 url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be
\r
1024 found here</ulink>.</para>
\r
1028 <para>For more general XML-RPC questions, there is a Yahoo! Groups
\r
1029 <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing
\r
1030 list</ulink>.</para>
\r
1035 url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion
\r
1036 group is a useful place to get help with using XML-RPC. This group
\r
1037 is also gatewayed into the Yahoo! Groups mailing list.</para>
\r
1042 <sect1 id="jellyfish" xreflabel="The Jellyfish Book">
\r
1043 <title>The Jellyfish Book</title>
\r
1045 <para><graphic align="right" depth="190" fileref="progxmlrpc.s.gif"
\r
1046 format="GIF" width="145" />Together with Simon St.Laurent and Joe
\r
1047 Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and
\r
1048 Associates on XML-RPC. It features a rather fetching jellyfish on the
\r
1051 <para>Complete details of the book are <ulink
\r
1052 url="http://www.oreilly.com/catalog/progxmlrpc/">available from
\r
1053 O'Reilly's web site.</ulink></para>
\r
1055 <para>Edd is responsible for the chapter on PHP, which includes a worked
\r
1056 example of creating a forum server, and hooking it up the O'Reilly's
\r
1057 <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in
\r
1058 order to allow commenting on news stories from around the Web.</para>
\r
1060 <para>If you've benefited from the effort that has been put into writing
\r
1061 this software, then please consider buying the book!</para>
\r
1065 <chapter id="apidocs">
\r
1066 <title>Class documentation</title>
\r
1068 <sect1 id="xmlrpcval" xreflabel="xmlrpcval">
\r
1069 <title>xmlrpcval</title>
\r
1071 <para>This is where a lot of the hard work gets done. This class enables
\r
1072 the creation and encapsulation of values for XML-RPC.</para>
\r
1074 <para>Ensure you've read the XML-RPC spec at <ulink
\r
1075 url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>
\r
1076 before reading on as it will make things clearer.</para>
\r
1078 <para>The <classname>xmlrpcval</classname> class can store arbitrarily
\r
1079 complicated values using the following types: <literal>i4 int boolean
\r
1080 string double dateTime.iso8601 base64 array struct</literal>. You should
\r
1081 refer to the <ulink url="http://www.xmlrpc.com/spec">spec</ulink> for
\r
1082 more information on what each of these types mean.</para>
\r
1085 <title>Notes on types</title>
\r
1088 <title>int</title>
\r
1090 <para>The type <classname>i4</classname> is accepted as a synonym
\r
1091 for <classname>int</classname> when creating xmlrpcval objects. The
\r
1092 xml parsing code will always convert <classname>i4</classname> to
\r
1093 <classname>int</classname>: <classname>int</classname> is regarded
\r
1094 by this implementation as the canonical name for this type.</para>
\r
1098 <title>base64</title>
\r
1100 <para>Base 64 encoding is performed transparently to the caller when
\r
1101 using this type. Decoding is also transparent. Therefore you ought
\r
1102 to consider it as a "binary" data type, for use when you want to
\r
1103 pass data that is not 7-bit clean.</para>
\r
1107 <title>boolean</title>
\r
1109 <para>The php values <literal>true</literal> and
\r
1110 <literal>1</literal> map to <literal>true</literal>. All other
\r
1111 values (including the empty string) are converted to
\r
1112 <literal>false</literal>.</para>
\r
1116 <title>string</title>
\r
1118 <para>Characters <, >, ', ", &, are encoded using their
\r
1119 entity reference as &lt; &gt; &apos; &quot; and
\r
1120 &amp; All other characters outside of the ASCII range are
\r
1121 encoded using their character reference representation (e.g.
\r
1122 &#200 for é). The XML-RPC spec recommends only encoding
\r
1123 <literal>< &</literal> but this implementation goes further,
\r
1124 for reasons explained by <ulink
\r
1125 url="http://www.w3.org/TR/REC-xml#syntax">the XML 1.0
\r
1126 recommendation</ulink>. In particular, using character reference
\r
1127 representation has the advantage of producing XML that is valid
\r
1128 independently of the charset encoding assumed.</para>
\r
1132 <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
\r
1133 <title>Creation</title>
\r
1135 <para>The constructor is the normal way to create an
\r
1136 <classname>xmlrpcval</classname>. The constructor can take these
\r
1141 <funcdef><type>xmlrpcval</type>new
\r
1142 <function>xmlrpcval</function></funcdef>
\r
1148 <funcdef><type>xmlrpcval</type>new
\r
1149 <function>xmlrpcval</function></funcdef>
\r
1151 <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
\r
1155 <funcdef><type>xmlrpcval</type>new
\r
1156 <function>xmlrpcval</function></funcdef>
\r
1158 <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
\r
1160 <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
\r
1164 <funcdef><type>xmlrpcval</type>new
\r
1165 <function>xmlrpcval</function></funcdef>
\r
1167 <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
\r
1169 <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>
\r
1173 <para>The first constructor creates an empty value, which must be
\r
1174 altered using the methods <function>addScalar</function>,
\r
1175 <function>addArray</function> or <function>addStruct</function> before
\r
1176 it can be used.</para>
\r
1178 <para>The second constructor creates a simple string value.</para>
\r
1180 <para>The third constructor is used to create a scalar value. The
\r
1181 second parameter must be a name of an XML-RPC type. Valid types are:
\r
1182 "<literal>int</literal>", "<literal>boolean</literal>",
\r
1183 "<literal>string</literal>", "<literal>double</literal>",
\r
1184 "<literal>dateTime.iso8601</literal>",
\r
1185 "<literal>base64</literal>".</para>
\r
1187 <para>Examples:</para>
\r
1189 <programlisting language="php">
\r
1190 $myInt = new xmlrpcvalue(1267, "int");
\r
1191 $myString = new xmlrpcvalue("Hello, World!", "string");
\r
1192 $myBool = new xmlrpcvalue(1, "boolean");
\r
1193 $myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
\r
1196 <para>The fourth constructor form can be used to compose complex
\r
1197 XML-RPC values. The first argument is either a simple array in the
\r
1198 case of an XML-RPC <classname>array</classname> or an associative
\r
1199 array in the case of a <classname>struct</classname>. The elements of
\r
1200 the array <emphasis>must be <classname>xmlrpcval</classname> objects
\r
1201 themselves</emphasis>.</para>
\r
1203 <para>The second parameter must be either "<literal>array</literal>"
\r
1204 or "<literal>struct</literal>".</para>
\r
1206 <para>Examples:</para>
\r
1208 <programlisting language="php">
\r
1209 $myArray = new xmlrpcval(
\r
1211 new xmlrpcval("Tom"),
\r
1212 new xmlrpcval("Dick"),
\r
1213 new xmlrpcval("Harry")
\r
1217 // recursive struct
\r
1218 $myStruct = new xmlrpcval(
\r
1220 "name" => new xmlrpcval("Tom", "string"),
\r
1221 "age" => new xmlrpcval(34, "int"),
\r
1222 "address" => new xmlrpcval(
\r
1224 "street" => new xmlrpcval("Fifht Ave", "string"),
\r
1225 "city" => new xmlrpcval("NY", "string")
\r
1232 <para>See the file <literal>vardemo.php</literal> in this distribution
\r
1233 for more examples.</para>
\r
1236 <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">
\r
1237 <title>Methods</title>
\r
1240 <title>addScalar</title>
\r
1244 <funcdef><type>int</type><function>addScalar</function></funcdef>
\r
1246 <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
\r
1250 <funcdef><type>int</type><function>addScalar</function></funcdef>
\r
1252 <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
\r
1254 <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
\r
1258 <para>If <parameter>$val</parameter> is an empty
\r
1259 <classname>xmlrpcval</classname> this method makes it a scalar
\r
1260 value, and sets that value.</para>
\r
1262 <para>If <parameter>$val</parameter> is already a scalar value, then
\r
1263 no more scalars can be added and <literal>0</literal> is
\r
1266 <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
\r
1267 the php value <parameter>$scalarval</parameter> is added as its last
\r
1270 <para>If all went OK, <literal>1</literal> is returned, otherwise
\r
1271 <literal>0</literal>.</para>
\r
1275 <title>addArray</title>
\r
1279 <funcdef><type>int</type><function>addArray</function></funcdef>
\r
1281 <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
\r
1285 <para>The argument is a simple (numerically indexed) array. The
\r
1286 elements of the array <emphasis>must be
\r
1287 <classname>xmlrpcval</classname> objects
\r
1288 themselves</emphasis>.</para>
\r
1290 <para>Turns an empty <classname>xmlrpcval</classname> into an
\r
1291 <classname>array</classname> with contents as specified by
\r
1292 <parameter>$arrayVal</parameter>.</para>
\r
1294 <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
\r
1295 the elements of <parameter>$arrayVal</parameter> are appended to the
\r
1296 existing ones.</para>
\r
1298 <para>See the fourth constructor form for more information.</para>
\r
1300 <para>If all went OK, <literal>1</literal> is returned, otherwise
\r
1301 <literal>0</literal>.</para>
\r
1305 <title>addStruct</title>
\r
1309 <funcdef><type>int</type><function>addStruct</function></funcdef>
\r
1311 <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>
\r
1315 <para>The argument is an associative array. The elements of the
\r
1316 array <emphasis>must be <classname>xmlrpcval</classname> objects
\r
1317 themselves</emphasis>.</para>
\r
1319 <para>Turns an empty <classname>xmlrpcval</classname> into a
\r
1320 <classname>struct</classname> with contents as specified by
\r
1321 <parameter>$assocArrayVal</parameter>.</para>
\r
1323 <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,
\r
1324 the elements of <parameter>$arrayVal</parameter> are merged with the
\r
1325 existing ones.</para>
\r
1327 <para>See the fourth constructor form for more information.</para>
\r
1329 <para>If all went OK, <literal>1</literal> is returned, otherwise
\r
1330 <literal>0</literal>.</para>
\r
1334 <title>kindOf</title>
\r
1338 <funcdef><type>string</type><function>kindOf</function></funcdef>
\r
1344 <para>Returns a string containing "struct", "array" or "scalar"
\r
1345 describing the base type of the value. If it returns "undef" it
\r
1346 means that the value hasn't been initialised.</para>
\r
1350 <title>serialize</title>
\r
1354 <funcdef><type>string</type><function>serialize</function></funcdef>
\r
1360 <para>Returns a string containing the XML-RPC representation of this
\r
1365 <title>scalarVal</title>
\r
1369 <funcdef><type>mixed</type><function>scalarVal</function></funcdef>
\r
1375 <para>If <function>$val->kindOf() == "scalar"</function>, this
\r
1376 method returns the actual PHP-language value of the scalar (base 64
\r
1377 decoding is automatically handled here).</para>
\r
1381 <title>scalarTyp</title>
\r
1385 <funcdef><type>string</type><function>scalarTyp</function></funcdef>
\r
1391 <para>If <function>$val->kindOf() == "scalar"</function>, this
\r
1392 method returns a string denoting the type of the scalar. As
\r
1393 mentioned before, <literal>i4</literal> is always coerced to
\r
1394 <literal>int</literal>.</para>
\r
1398 <title>arrayMem</title>
\r
1402 <funcdef><type>xmlrpcval</type><function>arrayMem</function></funcdef>
\r
1404 <paramdef><type>int</type><parameter>$n</parameter></paramdef>
\r
1408 <para>If <function>$val->kindOf() == "array"</function>, returns
\r
1409 the <parameter>$n</parameter>th element in the array represented by
\r
1410 the value <parameter>$val</parameter>. The value returned is an
\r
1411 <classname>xmlrpcval</classname> object.</para>
\r
1413 <para><programlisting language="php">
\r
1414 // iterating over values of an array object
\r
1415 for ($i = 0; $i < $val->arraySize(); $i++)
\r
1417 $v = $val->arrayMem($i);
\r
1418 echo "Element $i of the array is of type ".$v->kindOf();
\r
1420 </programlisting></para>
\r
1424 <title>arraySize</title>
\r
1428 <funcdef><type>int</type><function>arraySize</function></funcdef>
\r
1434 <para>If <parameter>$val</parameter> is an
\r
1435 <classname>array</classname>, returns the number of elements in that
\r
1440 <title>structMem</title>
\r
1444 <funcdef><type>xmlrpcval</type><function>structMem</function></funcdef>
\r
1446 <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
\r
1450 <para>If <function>$val->kindOf() == "struct"</function>, returns
\r
1451 the element called <parameter>$memberName</parameter> from the
\r
1452 struct represented by the value <parameter>$val</parameter>. The
\r
1453 value returned is an <classname>xmlrpcval</classname> object.</para>
\r
1457 <title>structEach</title>
\r
1461 <funcdef><type>array</type><function>structEach</function></funcdef>
\r
1467 <para>Returns the next (key, value) pair from the struct, when
\r
1468 <parameter>$val</parameter> is a struct.
\r
1469 <parameter>$value</parameter> is an xmlrpcval itself. See also <xref
\r
1470 linkend="structreset" />.</para>
\r
1472 <para><programlisting language="php">
\r
1473 // iterating over all values of a struct object
\r
1474 $val->structreset();
\r
1475 while (list($key, $v) = $val->structEach())
\r
1477 echo "Element $key of the struct is of type ".$v->kindOf();
\r
1479 </programlisting></para>
\r
1482 <sect3 id="structreset" xreflabel="structreset()">
\r
1483 <title>structReset</title>
\r
1487 <funcdef><type>void</type><function>structReset</function></funcdef>
\r
1493 <para>Resets the internal pointer for
\r
1494 <function>structEach()</function> to the beginning of the struct,
\r
1495 where <parameter>$val</parameter> is a struct.</para>
\r
1498 <sect3 id="structmemexists" xreflabel="structmemexists()">
\r
1499 <title>structMemExists</title>
\r
1503 <funcdef><type>bool</type><function>structMemExsists</function></funcdef>
\r
1505 <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
\r
1509 <para>Returns <constant>TRUE</constant> or
\r
1510 <constant>FALSE</constant> depending on whether a member of the
\r
1511 given name exists in the struct.</para>
\r
1516 <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">
\r
1517 <title>xmlrpcmsg</title>
\r
1519 <para>This class provides a representation for a request to an XML-RPC
\r
1520 server. A client sends an <classname>xmlrpcmsg</classname> to a server,
\r
1521 and receives back an <classname>xmlrpcresp</classname> (see <xref
\r
1522 linkend="xmlrpc-client-send" />).</para>
\r
1525 <title>Creation</title>
\r
1527 <para>The constructor takes the following forms:</para>
\r
1531 <funcdef><type>xmlrpcmsg</type>new
\r
1532 <function>xmlrpcmsg</function></funcdef>
\r
1534 <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>
\r
1536 <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>
\r
1540 <para>Where <parameter>methodName</parameter> is a string indicating
\r
1541 the name of the method you wish to invoke, and
\r
1542 <parameter>parameterArray</parameter> is a simple php
\r
1543 <classname>Array</classname> of <classname>xmlrpcval</classname>
\r
1544 objects. Here's an example message to the <emphasis>US state
\r
1545 name</emphasis> server:</para>
\r
1547 <programlisting language="php">
\r
1548 $msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
\r
1551 <para>This example requests the name of state number 23. For more
\r
1552 information on <classname>xmlrpcval</classname> objects, see <xref
\r
1553 linkend="xmlrpcval" />.</para>
\r
1555 <para>Note that the <parameter>parameterArray</parameter> parameter is
\r
1556 optional and can be omitted for methods that take no input parameters
\r
1557 or if you plan to add parameters one by one.</para>
\r
1561 <title>Methods</title>
\r
1564 <title>addParam</title>
\r
1568 <funcdef><type>bool</type><function>addParam</function></funcdef>
\r
1570 <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>
\r
1574 <para>Adds the <classname>xmlrpcval</classname>
\r
1575 <parameter>xmlrpcVal</parameter> to the parameter list for this
\r
1576 method call. Returns TRUE or FALSE on error.</para>
\r
1580 <title>getNumParams</title>
\r
1584 <funcdef><type>int</type><function>getNumParams</function></funcdef>
\r
1590 <para>Returns the number of parameters attached to this
\r
1595 <title>getParam</title>
\r
1599 <funcdef><type>xmlrpcval</type><function>getParam</function></funcdef>
\r
1601 <paramdef><type>int</type><parameter>$n</parameter></paramdef>
\r
1605 <para>Gets the <parameter>n</parameter>th parameter in the message
\r
1606 (with the index zero-based). Use this method in server
\r
1607 implementations to retrieve the values sent by the client.</para>
\r
1611 <title>method</title>
\r
1615 <funcdef><type>string</type><function>method</function></funcdef>
\r
1621 <funcdef><type>string</type><function>method</function></funcdef>
\r
1623 <paramdef><type>string</type><parameter>$methName</parameter></paramdef>
\r
1627 <para>Gets or sets the method contained in the XML-RPC
\r
1632 <title>parseResponse</title>
\r
1636 <funcdef><type>xmlrpcresp</type><function>parseResponse</function></funcdef>
\r
1638 <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>
\r
1642 <para>Given an incoming XML-RPC server response contained in the
\r
1643 string <parameter>$xmlString</parameter>, this method constructs an
\r
1644 <classname>xmlrpcresp</classname> response object and returns it,
\r
1645 setting error codes as appropriate (see <xref
\r
1646 linkend="xmlrpc-client-send" />).</para>
\r
1648 <para>This method processes any HTTP/MIME headers it finds.</para>
\r
1652 <title>parseResponseFile</title>
\r
1656 <funcdef><type>xmlrpcresp</type><function>parseResponseFile</function></funcdef>
\r
1658 <paramdef><type>file handle
\r
1659 resource</type><parameter>$fileHandle</parameter></paramdef>
\r
1663 <para>Given an incoming XML-RPC server response on the open file
\r
1664 handle <parameter>fileHandle</parameter>, this method reads all the
\r
1665 data it finds and passes it to
\r
1666 <function>parseResponse.</function></para>
\r
1668 <para>This method is useful to construct responses from pre-prepared
\r
1669 files (see files <literal>demo1.txt, demo2.txt, demo3.txt</literal>
\r
1670 in this distribution). It processes any HTTP headers it finds, and
\r
1671 does not close the file handle.</para>
\r
1675 <title>serialize</title>
\r
1679 <funcdef><type>string
\r
1680 </type><function>serialize</function></funcdef>
\r
1686 <para>Returns the an XML string representing the XML-RPC
\r
1692 <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">
\r
1693 <title>xmlrpc_client</title>
\r
1695 <para>This is the basic class used to represent a client of an XML-RPC
\r
1699 <title>Creation</title>
\r
1701 <para>The constructor accepts one of two possible syntaxes:</para>
\r
1705 <funcdef><type>xmlrpc_client</type>new
\r
1706 <function>xmlrpc_client</function></funcdef>
\r
1708 <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>
\r
1712 <funcdef><type>xmlrpc_client</type>new
\r
1713 <function>xmlrpc_client</function></funcdef>
\r
1715 <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>
\r
1717 <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>
\r
1719 <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>
\r
1721 <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>
\r
1725 <para>Here are a couple of usage examples of the first form:</para>
\r
1727 <programlisting language="php">
\r
1728 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
\r
1729 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/xmlrpcserver?agent=007");
\r
1732 <para>The second syntax does not allow to express a username and
\r
1733 password to be used for basic HTTP authorization as in the second
\r
1734 example above, but instead it allows to choose whether xmlrpc calls
\r
1735 will be made using the HTTP 1.0 or 1.1 protocol.</para>
\r
1737 <para>Here's another example client set up to query Userland's XML-RPC
\r
1738 server at <emphasis>betty.userland.com</emphasis>:</para>
\r
1740 <programlisting language="php">
\r
1741 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
\r
1744 <para>The <parameter>server_port</parameter> parameter is optional,
\r
1745 and if omitted will default to 80 when using HTTP and 443 when using
\r
1746 HTTPS (see the <xref linkend="xmlrpc-client-send" /> method
\r
1749 <para>The <parameter>transport</parameter> parameter is optional, and
\r
1750 if omitted will default to 'http'. Allowed values are either
\r
1751 '<symbol>http'</symbol>, '<symbol>https</symbol>' or
\r
1752 '<symbol>http11'</symbol>. Its value can be overridden with every call
\r
1753 to the <methodname>send</methodname> method. See the
\r
1754 <methodname>send</methodname> method below for more details about the
\r
1755 meaning of the different values.</para>
\r
1759 <title>Methods</title>
\r
1761 <para>This class supports the following methods.</para>
\r
1763 <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client->send">
\r
1764 <title>send</title>
\r
1766 <para>This method takes the forms:</para>
\r
1770 <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
\r
1772 <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpc_message</parameter></paramdef>
\r
1774 <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
\r
1776 <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
\r
1780 <funcdef><type>array</type><function>send</function></funcdef>
\r
1782 <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>
\r
1784 <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
\r
1786 <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
\r
1790 <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
\r
1792 <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>
\r
1794 <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
\r
1796 <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
\r
1800 <para>Where <parameter>xmlrpc_message</parameter> is an instance of
\r
1801 <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),
\r
1802 and <parameter>response</parameter> is an instance of
\r
1803 <classname>xmlrpcresp</classname> (see <xref
\r
1804 linkend="xmlrpcresp" />).</para>
\r
1806 <para><parameter>If xmlrpc_messages</parameter> is an array of
\r
1807 message instances, <code>responses</code> will be an array of
\r
1808 response instances. The client will try to make use of a single
\r
1809 <code>system.multicall</code> xml-rpc method call to forward to the
\r
1810 server all the messages in a single HTTP round trip, unless
\r
1811 <code>$client->no_multicall</code> has been previously set to
\r
1812 <code>TRUE</code> (see the multicall method below), in which case
\r
1813 many consecutive xmlrpc requests will be sent.</para>
\r
1815 <para>The third syntax allows to build by hand (or any other means)
\r
1816 a complete xmlrpc request message, and send it to the server.
\r
1817 <parameter>xml_payload</parameter> should be a string containing the
\r
1818 complete xml representation of the request. It is e.g. useful when,
\r
1819 for maximal speed of execution, the request is serialized into a
\r
1820 string using the native php xmlrpc functions (see <ulink
\r
1821 url="http://www.php.net/xmlrpc">the php manual on
\r
1822 xmlrpc</ulink>).</para>
\r
1824 <para>The <parameter>timeout</parameter> is optional, and will be
\r
1825 set to <literal>0</literal> (wait for platform-specific predefined
\r
1826 timeout) if omitted. This timeout value is passed to
\r
1827 <function>fsockopen()</function>. It is also used for detecting
\r
1828 server timeouts during communication (i.e. if the server does not
\r
1829 send anything to the client for <parameter>timeout</parameter>
\r
1830 seconds, the connection will be closed).</para>
\r
1832 <para>The <parameter>transport</parameter> parameter is optional,
\r
1833 and if omitted will default to the transport set using instance
\r
1834 creator or 'http' if omitted. The only other valid values are
\r
1835 'https', which will use an SSL HTTP connection to connect to the
\r
1836 remote server, and 'http11'. Note that your PHP must have the "curl"
\r
1837 extension compiled in order to use both these features. Note that
\r
1838 when using SSL you should normally set your port number to 443,
\r
1839 unless the SSL server you are contacting runs at any other
\r
1843 <para>PHP 4.0.6 has a bug which prevents SSL working.</para>
\r
1846 <para>In addition to low-level errors, the XML-RPC server you were
\r
1847 querying may return an error in the
\r
1848 <classname>xmlrpcresp</classname> object. See <xref
\r
1849 linkend="xmlrpcresp" /> for details of how to handle these
\r
1853 <sect3 id="multicall" xreflabel="xmlrpc_client->multicall">
\r
1854 <title>multiCall</title>
\r
1856 <para>This method takes the form:</para>
\r
1860 <funcdef><type>array</type><function>multiCall</function></funcdef>
\r
1862 <paramdef><type>array</type><parameter>$messages</parameter></paramdef>
\r
1864 <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
\r
1866 <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
\r
1868 <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>
\r
1872 <para>This method is used to boxcar many method calls in a single
\r
1873 xml-rpc request. It will try first to make use of the
\r
1874 <code>system.multicall</code> xml-rpc method call, and fall back to
\r
1875 executing many separate requests if the server returns any
\r
1878 <para><parameter>msgs</parameter> is an array of
\r
1879 <classname>xmlrpcmsg</classname> objects (see <xref
\r
1880 linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an
\r
1881 array of <classname>xmlrpcresp</classname> objects (see <xref
\r
1882 linkend="xmlrpcresp" />).</para>
\r
1884 <para>The <parameter>timeout</parameter> and
\r
1885 <parameter>transport</parameter> parameters are optional, and behave
\r
1886 as in the <methodname>send</methodname> method above.</para>
\r
1888 <para>The <parameter>fallback</parameter> parameter is optional, and
\r
1889 defaults to <constant>TRUE</constant>. When set to
\r
1890 <constant>FALSE</constant> it will prevent the client to try using
\r
1891 many single method calls in case of failure of the first multicall
\r
1892 request. It should be set only when the server is known to support
\r
1893 the multicall extension.</para>
\r
1897 <title>setAcceptedCompression</title>
\r
1901 <funcdef><type>void</type><function>setAcceptedCompression</function></funcdef>
\r
1903 <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
\r
1907 <para>This method defines whether the client will accept compressed
\r
1908 xml payload forming the bodies of the xmlrpc responses received from
\r
1909 servers. Note that enabling reception of compressed responses merely
\r
1910 adds some standard http headers to xmlrpc requests. It is up to the
\r
1911 xmlrpc server to return compressed responses when receiving such
\r
1912 requests. Allowed values for
\r
1913 <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
\r
1914 'any' or null (with any meaning either gzip or deflate).</para>
\r
1916 <para>This requires the "zlib" extension to be enabled in your php
\r
1917 install. If it is, by default <classname>xmlrpc_client</classname>
\r
1918 instances will enable reception of compressed content.</para>
\r
1922 <title>setCaCertificate</title>
\r
1926 <funcdef><type>void</type><function>setCaCertificate</function></funcdef>
\r
1928 <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
\r
1930 <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>
\r
1934 <para>This method sets an optional certificate to be used in
\r
1935 SSL-enabled communication to validate a remote server with (when the
\r
1936 <parameter>server_method</parameter> is set to 'https' in the
\r
1937 client's construction or in the send method and
\r
1938 <methodname>SetSSLVerifypeer</methodname> has been set to
\r
1939 <constant>TRUE</constant>).</para>
\r
1941 <para>The <parameter>certificate</parameter> parameter must be the
\r
1942 filename of a PEM formatted certificate, or a directory containing
\r
1943 multiple certificate files. The <parameter>is_dir</parameter>
\r
1944 parameter defaults to <constant>FALSE</constant>, set it to
\r
1945 <constant>TRUE</constant> to specify that
\r
1946 <parameter>certificate</parameter> indicates a directory instead of
\r
1947 a single file.</para>
\r
1949 <para>This requires the "curl" extension to be compiled into your
\r
1950 installation of PHP. For more details see the man page for the
\r
1951 <function>curl_setopt</function> function.</para>
\r
1955 <title>setCertificate</title>
\r
1959 <funcdef><type>void</type><function>setCertificate</function></funcdef>
\r
1961 <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
\r
1963 <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>
\r
1967 <para>This method sets the optional certificate and passphrase used
\r
1968 in SSL-enabled communication with a remote server (when the
\r
1969 <parameter>server_method</parameter> is set to 'https' in the
\r
1970 client's construction or in the send method).</para>
\r
1972 <para>The <parameter>certificate</parameter> parameter must be the
\r
1973 filename of a PEM formatted certificate. The
\r
1974 <parameter>passphrase</parameter> parameter must contain the
\r
1975 password required to use the certificate.</para>
\r
1977 <para>This requires the "curl" extension to be compiled into your
\r
1978 installation of PHP. For more details see the man page for the
\r
1979 <function>curl_setopt</function> function.</para>
\r
1981 <para>Note: to retrieve information about the client certificate on
\r
1982 the server side, you will need to look into the environment
\r
1983 variables which are set up by the webserver. Different webservers
\r
1984 will typically set up different variables.</para>
\r
1988 <title>setCookie</title>
\r
1992 <funcdef><type>void</type><function>setCookie</function></funcdef>
\r
1994 <paramdef><type>string</type><parameter>$name</parameter></paramdef>
\r
1996 <paramdef><type>string</type><parameter>$value</parameter></paramdef>
\r
1998 <paramdef><type>string</type><parameter>$path</parameter></paramdef>
\r
2000 <paramdef><type>string</type><parameter>$domain</parameter></paramdef>
\r
2002 <paramdef><type>int</type><parameter>$port</parameter></paramdef>
\r
2006 <para>This method sets a cookie that will be sent to the xmlrpc
\r
2007 server along with every further request (useful e.g. for keeping
\r
2008 session info outside of the xml-rpc payload).</para>
\r
2010 <para><parameter>$value</parameter> is optional, and defaults to
\r
2013 <para><parameter>$path, $domain and $port</parameter> are optional,
\r
2014 and will be omitted from the cookie header if unspecified. Note that
\r
2015 setting any of these values will turn the cookie into a 'version 1'
\r
2016 cookie, that might not be fully supported by the server (see RFC2965
\r
2017 for more details).</para>
\r
2021 <title>setCredentials</title>
\r
2025 <funcdef><type>void</type><function>setCredentials</function></funcdef>
\r
2027 <paramdef><type>string</type><parameter>$username</parameter></paramdef>
\r
2029 <paramdef><type>string</type><parameter>$password</parameter></paramdef>
\r
2031 <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
\r
2035 <para>This method sets the username and password for authorizing the
\r
2036 client to a server. With the default (HTTP) transport, this
\r
2037 information is used for HTTP Basic authorization. Note that username
\r
2038 and password can also be set using the class constructor. With HTTP
\r
2039 1.1 and HTTPS transport, NTLM and Digest authentication protocols
\r
2040 are also supported. To enable them use the constants
\r
2041 <constant>CURLAUTH_DIGEST</constant> and
\r
2042 <constant>CURLAUTH_NTLM</constant> as values for the authtype
\r
2047 <title>setDebug</title>
\r
2051 <funcdef><type>void</type><function>setDebug</function></funcdef>
\r
2053 <paramdef><type>int</type><parameter>$debugLvl</parameter></paramdef>
\r
2057 <para><parameter>debugLvl</parameter> is either <literal>0,
\r
2058 1</literal> or 2 depending on whether you require the client to
\r
2059 print debugging information to the browser. The default is not to
\r
2060 output this information (0).</para>
\r
2062 <para>The debugging information at level 1includes the raw data
\r
2063 returned from the XML-RPC server it was querying (including bot HTTP
\r
2064 headers and the full XML payload), and the PHP value the client
\r
2065 attempts to create to represent the value returned by the server. At
\r
2066 level2, the complete payload of the xmlrpc request is also printed,
\r
2067 before being sent t the server.</para>
\r
2069 <para>This option can be very useful when debugging servers as it
\r
2070 allows you to see exactly what the client sends and the server
\r
2075 <title>setKey</title>
\r
2079 <funcdef><type>void</type><function>setKey</function></funcdef>
\r
2081 <paramdef><type>int</type><parameter>$key</parameter></paramdef>
\r
2083 <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>
\r
2087 <para>This method sets the optional certificate key and passphrase
\r
2088 used in SSL-enabled communication with a remote server (when the
\r
2089 <parameter>transport</parameter> is set to 'https' in the client's
\r
2090 construction or in the send method).</para>
\r
2092 <para>This requires the "curl" extension to be compiled into your
\r
2093 installation of PHP. For more details see the man page for the
\r
2094 <function>curl_setopt</function> function.</para>
\r
2098 <title>setProxy</title>
\r
2102 <funcdef><type>void</type><function>setProxy</function></funcdef>
\r
2104 <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>
\r
2106 <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>
\r
2108 <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>
\r
2110 <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>
\r
2112 <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
\r
2116 <para>This method enables calling servers via an HTTP proxy. The
\r
2117 <parameter>proxyusername</parameter>,<parameter>
\r
2118 proxypassword</parameter> and <parameter>authtype</parameter>
\r
2119 parameters are optional. <parameter>Authtype</parameter> defaults to
\r
2120 <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);
\r
2121 the only other valid value is the constant
\r
2122 <constant>CURLAUTH_NTLM</constant>, and has effect only when the
\r
2123 client uses the HTTP 1.1 protocol.</para>
\r
2125 <para>NB: CURL versions before 7.11.10 cannot use a proxy to
\r
2126 communicate with https servers.</para>
\r
2130 <title>setRequestCompression</title>
\r
2134 <funcdef><type>void</type><function>setRequestCompression</function></funcdef>
\r
2136 <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
\r
2140 <para>This method defines whether the xml payload forming the
\r
2141 request body will be sent to the server in compressed format, as per
\r
2142 the HTTP specification. This is particularly useful for large
\r
2143 request parameters and over slow network connections. Allowed values
\r
2144 for <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
\r
2145 'any' or null (with any meaning either gzip or deflate). Note that
\r
2146 there is no automatic fallback mechanism in place for errors due to
\r
2147 servers not supporting receiving compressed request bodies, so make
\r
2148 sure that the particular server you are querying does accept
\r
2149 compressed requests before turning it on.</para>
\r
2151 <para>This requires the "zlib" extension to be enabled in your php
\r
2156 <title>setSSLVerifyHost</title>
\r
2160 <funcdef><type>void</type><function>setSSLVerifyHost</function></funcdef>
\r
2162 <paramdef><type>int</type><parameter>$i</parameter></paramdef>
\r
2166 <para>This method defines whether connections made to XML-RPC
\r
2167 backends via HTTPS should verify the remote host's SSL certificate's
\r
2168 common name (CN). By default, only the existence of a CN is checked.
\r
2169 <parameter><parameter>$i</parameter></parameter> should be an
\r
2170 integer value; 0 to not check the CN at all, 1 to merely check for
\r
2171 its existence, and 2 to check that the CN on the certificate matches
\r
2172 the hostname that is being connected to.</para>
\r
2176 <title>setSSLVerifyPeer</title>
\r
2180 <funcdef><type>void</type><function>setSSLVerifyPeer</function></funcdef>
\r
2182 <paramdef><type>bool</type><parameter>$i</parameter></paramdef>
\r
2186 <para>This method defines whether connections made to XML-RPC
\r
2187 backends via HTTPS should verify the remote host's SSL certificate,
\r
2188 and cause the connection to fail if the cert verification fails.
\r
2189 <parameter><parameter>$i</parameter></parameter> should be a boolean
\r
2190 value. Default value: <constant>TRUE</constant>. To specify custom
\r
2191 SSL certificates to validate the server with, use the
\r
2192 <methodname>setCaCertificate</methodname> method.</para>
\r
2197 <title>Variables</title>
\r
2199 <para>NB: direct manipulation of these variables is only recommended
\r
2200 for advanced users.</para>
\r
2203 <title>no_multicall</title>
\r
2205 <para>This member variable determines whether the multicall() method
\r
2206 will try to take advantage of the system.multicall xmlrpc method to
\r
2207 dispatch to the server an array of requests in a single http
\r
2208 roundtrip or simply execute many consecutive http calls. Defaults to
\r
2209 FALSE, but it will be enabled automatically on the first failure of
\r
2210 execution of system.multicall.</para>
\r
2214 <title>request_charset_encoding</title>
\r
2216 <para>This is the charset encoding that will be used for serializing
\r
2217 request sent by the client.</para>
\r
2219 <para>If defaults to NULL, which means using US-ASCII and encoding
\r
2220 all characters outside of the ASCII range using their xml character
\r
2221 entity representation (this has the benefit that line end characters
\r
2222 will not be mangled in the transfer, a CR-LF will be preserved as
\r
2223 well as a singe LF).</para>
\r
2225 <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>
\r
2228 <sect3 id="return-type" xreflabel="return_type">
\r
2229 <title>return_type</title>
\r
2231 <para>This member variable determines whether the value returned
\r
2232 inside an xmlrpcresp object as results of calls to the send() and
\r
2233 multicall() methods will be an xmlrpcval object, a plain php value
\r
2234 or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
\r
2235 'phpvals' and 'xml'. To allow the user to differentiate between a
\r
2236 correct and a faulty response, fault responses will be returned as
\r
2237 xmlrpcresp objects in any case. Note that the 'phpvals' setting will
\r
2238 yield faster execution times, but some of the information from the
\r
2239 original response will be lost. It will be e.g. impossible to tell
\r
2240 whether a particular php string value was sent by the server as an
\r
2241 xmlrpc string or base64 value.</para>
\r
2243 <para>Example usage:</para>
\r
2245 <programlisting language="php">
\r
2246 $client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server");
\r
2247 $client->return_type = 'phpvals';
\r
2248 $message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
\r
2249 $resp = $client->send($message);
\r
2250 if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();
\r
2253 <para>For more details about usage of the 'xml' value, see Appendix
\r
2259 <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">
\r
2260 <title>xmlrpcresp</title>
\r
2262 <para>This class is used to contain responses to XML-RPC requests. A
\r
2263 server method handler will construct an
\r
2264 <classname>xmlrpcresp</classname> and pass it as a return value. This
\r
2265 same value will be returned by the result of an invocation of the
\r
2266 <function>send</function> method of the
\r
2267 <classname>xmlrpc_client</classname> class.</para>
\r
2270 <title>Creation</title>
\r
2274 <funcdef><type>xmlrpcresp</type>new
\r
2275 <function>xmlrpcresp</function></funcdef>
\r
2277 <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>
\r
2281 <funcdef><type>xmlrpcresp</type>new
\r
2282 <function>xmlrpcresp</function></funcdef>
\r
2284 <paramdef><parameter>0</parameter></paramdef>
\r
2286 <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>
\r
2288 <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>
\r
2292 <para>The first syntax is used when execution has happened without
\r
2293 difficulty: <parameter>$xmlrpcval</parameter> is an
\r
2294 <classname>xmlrpcval</classname> value with the result of the method
\r
2295 execution contained in it. Alternatively it can be a string containing
\r
2296 the xml serialization of the single xml-rpc value result of method
\r
2299 <para>The second type of constructor is used in case of failure.
\r
2300 <parameter>errcode</parameter> and <parameter>err_string</parameter>
\r
2301 are used to provide indication of what has gone wrong. See <xref
\r
2302 linkend="xmlrpc-server" /> for more information on passing error
\r
2307 <title>Methods</title>
\r
2310 <title>faultCode</title>
\r
2314 <funcdef><type>int</type><function>faultCode</function></funcdef>
\r
2320 <para>Returns the integer fault code return from the XML-RPC
\r
2321 response. A zero value indicates success, any other value indicates
\r
2322 a failure response.</para>
\r
2326 <title>faultString</title>
\r
2330 <funcdef><type>string</type><function>faultString</function></funcdef>
\r
2336 <para>Returns the human readable explanation of the fault indicated
\r
2337 by <function>$resp->faultCode</function>().</para>
\r
2341 <title>value</title>
\r
2345 <funcdef><type>xmlrpcval</type><function>value</function></funcdef>
\r
2351 <para>Returns an <classname>xmlrpcval</classname> object containing
\r
2352 the return value sent by the server. If the response's
\r
2353 <function>faultCode</function> is non-zero then the value returned
\r
2354 by this method should not be used (it may not even be an
\r
2357 <para>Note: if the xmlrpcresp instance in question has been created
\r
2358 by an <classname>xmlrpc_client</classname> object whose
\r
2359 <varname>return_type</varname> was set to 'phpvals', then a plain
\r
2360 php value will be returned instead of an
\r
2361 <classname>xmlrpcval</classname> object. If the
\r
2362 <varname>return_type</varname> was set to 'xml', an xml string will
\r
2363 be returned (see the return_type member var above for more
\r
2368 <title>serialize</title>
\r
2372 <funcdef><type>string</type><function>serialize</function></funcdef>
\r
2378 <para>Returns an XML string representation of the response (xml
\r
2379 prologue not included).</para>
\r
2384 <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">
\r
2385 <title>xmlrpc_server</title>
\r
2387 <para>The implementation of this class has been kept as simple to use as
\r
2388 possible. The constructor for the server basically does all the work.
\r
2389 Here's a minimal example:</para>
\r
2391 <programlisting language="php">
\r
2392 function foo ($xmlrpcmsg) {
\r
2394 return new xmlrpcresp($some_xmlrpc_val);
\r
2398 function foobar($xmlrpcmsg) {
\r
2400 return new xmlrpcresp($some_xmlrpc_val);
\r
2404 $s = new xmlrpc_server(
\r
2406 "examples.myFunc1" => array("function" => "foo"),
\r
2407 "examples.myFunc2" => array("function" => "bar::foobar"),
\r
2411 <para>This performs everything you need to do with a server. The single
\r
2412 constructor argument is an associative array from xmlrpc method names to
\r
2413 php function names. The incoming request is parsed and dispatched to the
\r
2414 relevant php function, which is responsible for returning a
\r
2415 <classname>xmlrpcresp</classname> object, that will be serialized back
\r
2416 to the caller.</para>
\r
2419 <title>Method handler functions</title>
\r
2421 <para>Both php functions and class methods can be registered as xmlrpc
\r
2422 method handlers.</para>
\r
2424 <para>The synopsis of a method handler function is:</para>
\r
2426 <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>
\r
2428 <para>No text should be echoed 'to screen' by the handler function, or
\r
2429 it will break the xml response sent back to the client. This applies
\r
2430 also to error and warning messages that PHP prints to screen unless
\r
2431 the appropriate parameters have been set in the php.in file. Another
\r
2432 way to prevent echoing of errors inside the response and facilitate
\r
2433 debugging is to use the server SetDebug method with debug level 3 (see
\r
2436 <para>Note that if you implement a method with a name prefixed by
\r
2437 <code>system.</code> the handler function will be invoked by the
\r
2438 server with two parameters, the first being the server itself and the
\r
2439 second being the <classname>xmlrpcmsg</classname> object.</para>
\r
2441 <para>The same php function can be registered as handler of multiple
\r
2442 xmlrpc methods.</para>
\r
2444 <para>Here is a more detailed example of what the handler function
\r
2445 <function>foo</function> may do:</para>
\r
2447 <programlisting language="php">
\r
2448 function foo ($xmlrpcmsg) {
\r
2449 global $xmlrpcerruser; // import user errcode base value
\r
2451 $meth = $xmlrpcmsg->method(); // retrieve method name
\r
2452 $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
\r
2453 $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value
\r
2458 // this is an error condition
\r
2459 return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
\r
2460 "There's a problem, Captain");
\r
2462 // this is a successful value being returned
\r
2463 return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
\r
2468 <para>See <filename>server.php</filename> in this distribution for
\r
2469 more examples of how to do this.</para>
\r
2471 <para>Since release 2.0RC3 there is a new, even simpler way of
\r
2472 registering php functions with the server. See section 5.7
\r
2477 <title>The dispatch map</title>
\r
2479 <para>The first argument to the <function>xmlrpc_server</function>
\r
2480 constructor is an array, called the <emphasis>dispatch map</emphasis>.
\r
2481 In this array is the information the server needs to service the
\r
2482 XML-RPC methods you define.</para>
\r
2484 <para>The dispatch map takes the form of an associative array of
\r
2485 associative arrays: the outer array has one entry for each method, the
\r
2486 key being the method name. The corresponding value is another
\r
2487 associative array, which can have the following members:</para>
\r
2491 <para><function><literal>function</literal></function> - this
\r
2492 entry is mandatory. It must be either a name of a function in the
\r
2493 global scope which services the XML-RPC method, or an array
\r
2494 containing an instance of an object and a static method name (for
\r
2495 static class methods the 'class::method' syntax is also
\r
2496 supported).</para>
\r
2500 <para><function><literal>signature</literal></function> - this
\r
2501 entry is an array containing the possible signatures (see <xref
\r
2502 linkend="signatures" />) for the method. If this entry is present
\r
2503 then the server will check that the correct number and type of
\r
2504 parameters have been sent for this method before dispatching
\r
2509 <para><function><literal>docstring</literal></function> - this
\r
2510 entry is a string containing documentation for the method. The
\r
2511 documentation may contain HTML markup.</para>
\r
2515 <para><literal>signature_docs</literal> - this entry can be used
\r
2516 to provide documentation for the single parameters. It must match
\r
2517 in structure the 'signature' member. By default, only the
\r
2518 <classname>documenting_xmlrpc_server</classname> class in the
\r
2519 extras package will take advantage of this, since the
\r
2520 "system.methodHelp" protocol does not support documenting method
\r
2521 parameters individually.</para>
\r
2525 <para>Look at the <filename>server.php</filename> example in the
\r
2526 distribution to see what a dispatch map looks like.</para>
\r
2529 <sect2 id="signatures" xreflabel="Signatures">
\r
2530 <title>Method signatures</title>
\r
2532 <para>A signature is a description of a method's return type and its
\r
2533 parameter types. A method may have more than one signature.</para>
\r
2535 <para>Within a server's dispatch map, each method has an array of
\r
2536 possible signatures. Each signature is an array of types. The first
\r
2537 entry is the return type. For instance, the method <programlisting
\r
2538 language="php">string examples.getStateName(int)
\r
2539 </programlisting> has the signature <programlisting language="php">array($xmlrpcString, $xmlrpcInt)
\r
2540 </programlisting> and, assuming that it is the only possible signature for the
\r
2541 method, it might be used like this in server creation: <programlisting
\r
2543 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
\r
2545 $findstate_doc = 'When passed an integer between 1 and 51 returns the
\r
2546 name of a US state, where the integer is the index of that state name
\r
2547 in an alphabetic order.';
\r
2549 $s = new xmlrpc_server( array(
\r
2550 "examples.getStateName" => array(
\r
2551 "function" => "findstate",
\r
2552 "signature" => $findstate_sig,
\r
2553 "docstring" => $findstate_doc
\r
2555 </programlisting></para>
\r
2557 <para>Note that method signatures do not allow to check nested
\r
2558 parameters, e.g. the number, names and types of the members of a
\r
2559 struct param cannot be validated.</para>
\r
2561 <para>If a method that you want to expose has a definite number of
\r
2562 parameters, but each of those parameters could reasonably be of
\r
2563 multiple types, the array of acceptable signatures will easily grow
\r
2564 into a combinatorial explosion. To avoid such a situation, the lib
\r
2565 defines the global var <varname>$xmlrpcValue</varname>, which can be
\r
2566 used in method signatures as a placeholder for 'any xmlrpc
\r
2569 <para><programlisting language="php">
\r
2570 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
\r
2572 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
\r
2574 $s = new xmlrpc_server( array(
\r
2575 "echoBack" => array(
\r
2576 "function" => "echoback",
\r
2577 "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
\r
2578 "docstring" => $echoback_doc
\r
2580 </programlisting></para>
\r
2582 <para>Methods <methodname>system.listMethods</methodname>,
\r
2583 <methodname>system.methodHelp</methodname>,
\r
2584 <methodname>system.methodSignature</methodname> and
\r
2585 <methodname>system.multicall</methodname> are already defined by the
\r
2586 server, and should not be reimplemented (see Reserved Methods
\r
2591 <title>Delaying the server response</title>
\r
2593 <para>You may want to construct the server, but for some reason not
\r
2594 fulfill the request immediately (security verification, for instance).
\r
2595 If you omit to pass to the constructor the dispatch map or pass it a
\r
2596 second argument of <literal>0</literal> this will have the desired
\r
2597 effect. You can then use the <function>service()</function> method of
\r
2598 the server class to service the request. For example:</para>
\r
2600 <programlisting language="php">
\r
2601 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
\r
2603 // ... some code that does other stuff here
\r
2608 <para>Note that the <methodname>service</methodname> method will print
\r
2609 the complete result payload to screen and send appropriate HTTP
\r
2610 headers back to the client, but also return the response object. This
\r
2611 permits further manipulation of the response.</para>
\r
2613 <para>To prevent the server from sending HTTP headers back to the
\r
2614 client, you can pass a second parameter with a value of
\r
2615 <literal>TRUE</literal> to the <methodname>service</methodname>
\r
2616 method. In this case, the response payload will be returned instead of
\r
2617 the response object.</para>
\r
2619 <para>Xmlrpc requests retrieved by other means than HTTP POST bodies
\r
2620 can also be processed. For example:</para>
\r
2622 <programlisting language="php">
\r
2623 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
\r
2625 // ... some code that does other stuff here, including setting dispatch map into server object
\r
2627 $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
\r
2629 // ... some code that does other stuff with xml response $resp here
\r
2634 <title>Modifying the server behaviour</title>
\r
2636 <para>A couple of methods / class variables are available to modify
\r
2637 the behaviour of the server. The only way to take advantage of their
\r
2638 existence is by usage of a delayed server response (see above)</para>
\r
2641 <title>setDebug()</title>
\r
2643 <para>This function controls weather the server is going to echo
\r
2644 debugging messages back to the client as comments in response body.
\r
2645 Valid values: 0,1,2,3, with 1 being the default. At level 0, no
\r
2646 debug info is returned to the client. At level 2, the complete
\r
2647 client request is added to the response, as part of the xml
\r
2648 comments. At level 3, a new PHP error handler is set when executing
\r
2649 user functions exposed as server methods, and all non-fatal errors
\r
2650 are trapped and added as comments into the response.</para>
\r
2654 <title>allow_system_funcs</title>
\r
2656 <para>Default_value: TRUE. When set to FALSE, disables support for
\r
2657 <methodname>System.xxx</methodname> functions in the server. It
\r
2658 might be useful e.g. if you do not wish the server to respond to
\r
2659 requests to <methodname>System.ListMethods</methodname>.</para>
\r
2663 <title>compress_response</title>
\r
2665 <para>When set to TRUE, enables the server to take advantage of HTTP
\r
2666 compression, otherwise disables it. Responses will be transparently
\r
2667 compressed, but only when an xmlrpc-client declares its support for
\r
2668 compression in the HTTP headers of the request.</para>
\r
2670 <para>Note that the ZLIB php extension must be installed for this to
\r
2671 work. If it is, <varname>compress_response</varname> will default to
\r
2676 <title>response_charset_encoding</title>
\r
2678 <para>Charset encoding to be used for response (only affects string
\r
2681 <para>If it can, the server will convert the generated response from
\r
2682 internal_encoding to the intended one.</para>
\r
2684 <para>Valid values are: a supported xml encoding (only UTF-8 and
\r
2685 ISO-8859-1 at present, unless mbstring is enabled), null (leave
\r
2686 charset unspecified in response and convert output stream to
\r
2687 US_ASCII), 'default' (use xmlrpc library default as specified in
\r
2688 xmlrpc.inc, convert output stream if needed), or 'auto' (use
\r
2689 client-specified charset encoding or same as request if request
\r
2690 headers do not specify it (unless request is US-ASCII: then use
\r
2691 library default anyway).</para>
\r
2696 <title>Fault reporting</title>
\r
2698 <para>Fault codes for your servers should start at the value indicated
\r
2699 by the global <literal>$xmlrpcerruser</literal> + 1.</para>
\r
2701 <para>Standard errors returned by the server include:</para>
\r
2705 <term><literal>1</literal> <phrase>Unknown method</phrase></term>
\r
2708 <para>Returned if the server was asked to dispatch a method it
\r
2709 didn't know about</para>
\r
2714 <term><literal>2</literal> <phrase>Invalid return
\r
2715 payload</phrase></term>
\r
2718 <para>This error is actually generated by the client, not
\r
2719 server, code, but signifies that a server returned something it
\r
2720 couldn't understand. A more detailed error report is sometimes
\r
2721 added onto the end of the phrase above.</para>
\r
2726 <term><literal>3</literal> <phrase>Incorrect
\r
2727 parameters</phrase></term>
\r
2730 <para>This error is generated when the server has signature(s)
\r
2731 defined for a method, and the parameters passed by the client do
\r
2732 not match any of signatures.</para>
\r
2737 <term><literal>4</literal> <phrase>Can't introspect: method
\r
2738 unknown</phrase></term>
\r
2741 <para>This error is generated by the builtin
\r
2742 <function>system.*</function> methods when any kind of
\r
2743 introspection is attempted on a method undefined by the
\r
2749 <term><literal>5</literal> <phrase>Didn't receive 200 OK from
\r
2750 remote server</phrase></term>
\r
2753 <para>This error is generated by the client when a remote server
\r
2754 doesn't return HTTP/1.1 200 OK in response to a request. A more
\r
2755 detailed error report is added onto the end of the phrase
\r
2761 <term><literal>6</literal> <phrase>No data received from
\r
2762 server</phrase></term>
\r
2765 <para>This error is generated by the client when a remote server
\r
2766 returns HTTP/1.1 200 OK in response to a request, but no
\r
2767 response body follows the HTTP headers.</para>
\r
2772 <term><literal>7</literal> <phrase>No SSL support compiled
\r
2773 in</phrase></term>
\r
2776 <para>This error is generated by the client when trying to send
\r
2777 a request with HTTPS and the CURL extension is not available to
\r
2783 <term><literal>8</literal> <phrase>CURL error</phrase></term>
\r
2786 <para>This error is generated by the client when trying to send
\r
2787 a request with HTTPS and the HTTPS communication fails.</para>
\r
2792 <term><literal>9-14</literal> <phrase>multicall
\r
2793 errors</phrase></term>
\r
2796 <para>These errors are generated by the server when something
\r
2797 fails inside a system.multicall request.</para>
\r
2802 <term><literal>100-</literal> <phrase>XML parse
\r
2803 errors</phrase></term>
\r
2806 <para>Returns 100 plus the XML parser error code for the fault
\r
2807 that occurred. The <function>faultString</function> returned
\r
2808 explains where the parse error was in the incoming XML
\r
2816 <title>'New style' servers</title>
\r
2818 <para>In the same spirit of simplification that inspired the
\r
2819 <varname>xmlrpc_client::return_type</varname> class variable, a new
\r
2820 class variable has been added to the server class:
\r
2821 <varname>functions_parameters_type</varname>. When set to 'phpvals',
\r
2822 the functions registered in the server dispatch map will be called
\r
2823 with plain php values as parameters, instead of a single xmlrpcmsg
\r
2824 instance parameter. The return value of those functions is expected to
\r
2825 be a plain php value, too. An example is worth a thousand
\r
2826 words:<programlisting language="php">
\r
2827 function foo($usr_id, $out_lang='en') {
\r
2828 global $xmlrpcerruser;
\r
2832 if ($someErrorCondition)
\r
2833 return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
\r
2836 'name' => 'Joe',
\r
2838 'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
\r
2842 $s = new xmlrpc_server(
\r
2844 "examples.myFunc" => array(
\r
2845 "function" => "bar::foobar",
\r
2846 "signature" => array(
\r
2847 array($xmlrpcString, $xmlrpcInt),
\r
2848 array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
\r
2852 $s->functions_parameters_type = 'phpvals';
\r
2854 </programlisting>There are a few things to keep in mind when using this
\r
2855 simplified syntax:</para>
\r
2857 <para>to return an xmlrpc error, the method handler function must
\r
2858 return an instance of xmlrpcresp. There is no other way for the server
\r
2859 to know when an error response should be served to the client;</para>
\r
2861 <para>to return a base64 value, the method handler function must
\r
2862 encode it on its own, creating an instance of an xmlrpcval
\r
2865 <para>the method handler function cannot determine the name of the
\r
2866 xmlrpc method it is serving, unlike standard handler functions that
\r
2867 can retrieve it from the message object;</para>
\r
2869 <para>when receiving nested parameters, the method handler function
\r
2870 has no way to distinguish a php string that was sent as base64 value
\r
2871 from one that was sent as a string value;</para>
\r
2873 <para>this has a direct consequence on the support of
\r
2874 system.multicall: a method whose signature contains datetime or base64
\r
2875 values will not be available to multicall calls;</para>
\r
2877 <para>last but not least, the direct parsing of xml to php values is
\r
2878 much faster than using xmlrpcvals, and allows the library to handle
\r
2879 much bigger messages without allocating all available server memory or
\r
2880 smashing PHP recursive call stack.</para>
\r
2885 <chapter id="globalvars">
\r
2886 <title>Global variables</title>
\r
2888 <para>Many global variables are defined in the xmlrpc.inc file. Some of
\r
2889 those are meant to be used as constants (and modifying their value might
\r
2890 cause unpredictable behaviour), while some others can be modified in your
\r
2891 php scripts to alter the behaviour of the xml-rpc client and
\r
2895 <title>"Constant" variables</title>
\r
2898 <title>$xmlrpcerruser</title>
\r
2900 <para><fieldsynopsis>
\r
2901 <varname>$xmlrpcerruser</varname>
\r
2903 <initializer>800</initializer>
\r
2904 </fieldsynopsis>The minimum value for errors reported by user
\r
2905 implemented XML-RPC servers. Error numbers lower than that are
\r
2906 reserved for library usage.</para>
\r
2910 <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
\r
2911 $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,
\r
2912 $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>
\r
2914 <para>For convenience the strings representing the XML-RPC types have
\r
2915 been encoded as global variables:<programlisting language="php">
\r
2918 $xmlrpcBoolean="boolean";
\r
2919 $xmlrpcDouble="double";
\r
2920 $xmlrpcString="string";
\r
2921 $xmlrpcDateTime="dateTime.iso8601";
\r
2922 $xmlrpcBase64="base64";
\r
2923 $xmlrpcArray="array";
\r
2924 $xmlrpcStruct="struct";
\r
2925 $xmlrpcValue="undefined";
\r
2926 $xmlrpcNull="null";
\r
2927 </programlisting></para>
\r
2931 <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
\r
2932 $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
\r
2933 $xmlEntities, $xmlrpcs_capabilities</title>
\r
2935 <para>Reserved for internal usage.</para>
\r
2940 <title>Variables whose value can be modified</title>
\r
2942 <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">
\r
2943 <title xreflabel="">xmlrpc_defencoding</title>
\r
2946 <varname>$xmlrpc_defencoding</varname>
\r
2948 <initializer>"UTF8"</initializer>
\r
2951 <para>This variable defines the character set encoding that will be
\r
2952 used by the xml-rpc client and server to decode the received messages,
\r
2953 when a specific charset declaration is not found (in the messages sent
\r
2954 non-ascii chars are always encoded using character references, so that
\r
2955 the produced xml is valid regardless of the charset encoding
\r
2958 <para>Allowed values: <literal>"UTF8"</literal>,
\r
2959 <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>
\r
2961 <para>Note that the appropriate RFC actually mandates that XML
\r
2962 received over HTTP without indication of charset encoding be treated
\r
2963 as US-ASCII, but many servers and clients 'in the wild' violate the
\r
2964 standard, and assume the default encoding is UTF-8.</para>
\r
2968 <title>xmlrpc_internalencoding</title>
\r
2970 <para><fieldsynopsis>
\r
2971 <varname>$xmlrpc_internalencoding</varname>
\r
2973 <initializer>"ISO-8859-1"</initializer>
\r
2974 </fieldsynopsis>This variable defines the character set encoding
\r
2975 that the library uses to transparently encode into valid XML the
\r
2976 xml-rpc values created by the user and to re-encode the received
\r
2977 xml-rpc values when it passes them to the PHP application. It only
\r
2978 affects xml-rpc values of string type. It is a separate value from
\r
2979 xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
\r
2980 on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
\r
2981 character set used internally by PHP (unless you are running an
\r
2982 MBString-enabled installation), so you should change it only in
\r
2983 special situations, if e.g. the string values exchanged in the xml-rpc
\r
2984 messages are directly inserted into / fetched from a database
\r
2985 configured to return UTF8 encoded strings to PHP. Example
\r
2988 <para><programlisting language="php">
\r
2991 include('xmlrpc.inc');
\r
2992 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
\r
2993 $v = new xmlrpcval('κόÏ
\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
\r
2994 </programlisting></para>
\r
2998 <title>xmlrpcName</title>
\r
3000 <para><fieldsynopsis>
\r
3001 <varname>$xmlrpcName</varname>
\r
3003 <initializer>"XML-RPC for PHP"</initializer>
\r
3004 </fieldsynopsis>The string representation of the name of the XML-RPC
\r
3005 for PHP library. It is used by the client for building the User-Agent
\r
3006 HTTP header that is sent with every request to the server. You can
\r
3007 change its value if you need to customize the User-Agent
\r
3012 <title>xmlrpcVersion</title>
\r
3014 <para><fieldsynopsis>
\r
3015 <varname>$xmlrpcVersion</varname>
\r
3017 <initializer>"2.2"</initializer>
\r
3018 </fieldsynopsis>The string representation of the version number of
\r
3019 the XML-RPC for PHP library in use. It is used by the client for
\r
3020 building the User-Agent HTTP header that is sent with every request to
\r
3021 the server. You can change its value if you need to customize the
\r
3022 User-Agent string.</para>
\r
3026 <title>xmlrpc_null_extension</title>
\r
3028 <para>When set to <constant>TRUE</constant>, the lib will enable
\r
3029 support for the <NIL/> xmlrpc value, as per the extension to the
\r
3030 standard proposed here. This means that <NIL/> tags will be
\r
3031 parsed as valid xmlrpc, and the corresponding xmlrpcvals will return
\r
3032 "null" for <methodname>scalarTyp()</methodname>.</para>
\r
3037 <chapter id="helpers">
\r
3038 <title>Helper functions</title>
\r
3040 <para>XML-RPC for PHP contains some helper functions which you can use to
\r
3041 make processing of XML-RPC requests easier.</para>
\r
3044 <title>Date functions</title>
\r
3046 <para>The XML-RPC specification has this to say on dates:</para>
\r
3049 <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be
\r
3050 specified by the server in its documentation what assumptions it makes
\r
3051 about timezones.</para>
\r
3054 <para>Unfortunately, this means that date processing isn't
\r
3055 straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
\r
3056 use the timezone specifier.</para>
\r
3058 <para>We strongly recommend that in every case where you pass dates in
\r
3059 XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
\r
3060 languages include routines for handling GMT times natively, and you
\r
3061 won't have to translate between timezones.</para>
\r
3063 <para>For more information about dates, see <ulink
\r
3064 url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right
\r
3065 Format for Dates</ulink>, which has a handy link to a PDF of the ISO
\r
3066 8601 specification. Note that XML-RPC uses exactly one of the available
\r
3067 representations: CCYYMMDDTHH:MM:SS.</para>
\r
3069 <sect2 id="iso8601encode" xreflabel="iso8601_encode()">
\r
3070 <title>iso8601_encode</title>
\r
3074 <funcdef><type>string</type><function>iso8601_encode</function></funcdef>
\r
3076 <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>
\r
3079 choice="opt"><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
\r
3083 <para>Returns an ISO 8601 formatted date generated from the UNIX
\r
3084 timestamp <parameter>$time_t</parameter>, as returned by the PHP
\r
3085 function <function>time()</function>.</para>
\r
3087 <para>The argument <parameter>$utc</parameter> can be omitted, in
\r
3088 which case it defaults to <literal>0</literal>. If it is set to
\r
3089 <literal>1</literal>, then the function corrects the time passed in
\r
3090 for UTC. Example: if you're in the GMT-6:00 timezone and set
\r
3091 <parameter>$utc</parameter>, you will receive a date representation
\r
3092 six hours ahead of your local time.</para>
\r
3094 <para>The included demo program <filename>vardemo.php</filename>
\r
3095 includes a demonstration of this function.</para>
\r
3098 <sect2 id="iso8601decode" xreflabel="iso8601_decode()">
\r
3099 <title>iso8601_decode</title>
\r
3103 <funcdef><type>int</type><function>iso8601_decode</function></funcdef>
\r
3105 <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>
\r
3107 <paramdef><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
\r
3111 <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date
\r
3112 string passed in. If <parameter>$utc</parameter> is
\r
3113 <literal>1</literal> then <parameter>$isoString</parameter> is assumed
\r
3114 to be in the UTC timezone, and thus the result is also UTC: otherwise,
\r
3115 the timezone is assumed to be your local timezone and you receive a
\r
3116 local timestamp.</para>
\r
3120 <sect1 id="arrayuse">
\r
3121 <title>Easy use with nested PHP values</title>
\r
3123 <para>Dan Libby was kind enough to contribute two helper functions that
\r
3124 make it easier to translate to and from PHP values. This makes it easier
\r
3125 to deal with complex structures. At the moment support is limited to
\r
3126 <type>int</type>, <type>double</type>, <type>string</type>,
\r
3127 <type>array</type>, <type>datetime</type> and <type>struct</type>
\r
3128 datatypes; note also that all PHP arrays are encoded as structs, except
\r
3129 arrays whose keys are integer numbers starting with 0 and incremented by
\r
3132 <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>
\r
3134 <sect2 id="phpxmlrpcdecode">
\r
3135 <title>php_xmlrpc_decode</title>
\r
3139 <funcdef><type>mixed</type><function>php_xmlrpc_decode</function></funcdef>
\r
3141 <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
\r
3143 <paramdef><type>array</type><parameter>$options</parameter></paramdef>
\r
3147 <funcdef><type>array</type><function>php_xmlrpc_decode</function></funcdef>
\r
3149 <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>
\r
3151 <paramdef><type>string</type><parameter>$options</parameter></paramdef>
\r
3155 <para>Returns a native PHP value corresponding to the values found in
\r
3156 the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,
\r
3157 translated into PHP types. Base-64 and datetime values are
\r
3158 automatically decoded to strings.</para>
\r
3160 <para>In the second form, returns an array containing the parameters
\r
3162 <parameter><classname>xmlrpcmsg</classname>_val</parameter>, decoded
\r
3163 to php types.</para>
\r
3165 <para>The <parameter>options</parameter> parameter is optional. If
\r
3166 specified, it must consist of an array of options to be enabled in the
\r
3167 decoding process. At the moment the only valid option is
\r
3168 <symbol>decode_php_objs</symbol>. When it is set, php objects that
\r
3169 have been converted to xml-rpc structs using the
\r
3170 <function>php_xmlrpc_encode</function> function and a corresponding
\r
3171 encoding option will be converted back into object values instead of
\r
3172 arrays (provided that the class definition is available at
\r
3173 reconstruction time).</para>
\r
3175 <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
\r
3176 extreme care before enabling the <symbol>decode_php_objs</symbol>
\r
3177 option: when php objects are rebuilt from the received xml, their
\r
3178 constructor function will be silently invoked. This means that you are
\r
3179 allowing the remote end to trigger execution of uncontrolled PHP code
\r
3180 on your server, opening the door to code injection exploits. Only
\r
3181 enable this option when you have complete trust of the remote
\r
3182 server/client.</para>
\r
3184 <para>Example:<programlisting language="php">
\r
3185 // wrapper to expose an existing php function as xmlrpc method handler
\r
3186 function foo_wrapper($m)
\r
3188 $params = php_xmlrpc_decode($m);
\r
3189 $retval = call_user_func_array('foo', $params);
\r
3190 return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
\r
3193 $s = new xmlrpc_server(array(
\r
3194 "examples.myFunc1" => array(
\r
3195 "function" => "foo_wrapper",
\r
3196 "signatures" => ...
\r
3198 </programlisting></para>
\r
3201 <sect2 id="phpxmlrpcencode">
\r
3202 <title>php_xmlrpc_encode</title>
\r
3206 <funcdef><type>xmlrpcval</type><function>php_xmlrpc_encode</function></funcdef>
\r
3208 <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
\r
3210 <paramdef><type>array</type><parameter>$options</parameter></paramdef>
\r
3214 <para>Returns an <type>xmlrpcval</type> object populated with the PHP
\r
3215 values in <parameter>$phpval</parameter>. Works recursively on arrays
\r
3216 and objects, encoding numerically indexed php arrays into array-type
\r
3217 xmlrpcval objects and non numerically indexed php arrays into
\r
3218 struct-type xmlrpcval objects. Php objects are encoded into
\r
3219 struct-type xmlrpcvals, excepted for php values that are already
\r
3220 instances of the xmlrpcval class or descendants thereof, which will
\r
3221 not be further encoded. Note that there's no support for encoding php
\r
3222 values into base-64 values. Encoding of date-times is optionally
\r
3223 carried on on php strings with the correct format.</para>
\r
3225 <para>The <parameter>options</parameter> parameter is optional. If
\r
3226 specified, it must consist of an array of options to be enabled in the
\r
3227 encoding process. At the moment the only valid options are
\r
3228 <symbol>encode_php_objs</symbol> and
\r
3229 <symbol>auto_dates</symbol>.</para>
\r
3231 <para>The first will enable the creation of 'particular' xmlrpcval
\r
3232 objects out of php objects, that add a "php_class" xml attribute to
\r
3233 their serialized representation. This attribute allows the function
\r
3234 php_xmlrpc_decode to rebuild the native php objects (provided that the
\r
3235 same class definition exists on both sides of the
\r
3236 communication)</para>
\r
3238 <para>Example:<programlisting language="php">
\r
3239 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
\r
3240 $val = php_xmlrpc_encode(array(
\r
3241 'first struct_element: an int' => 666,
\r
3242 'second: an array' => array ('apple', 'orange', 'banana'),
\r
3243 'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
\r
3244 'fourth: a datetime' => '20060107T01:53:00'
\r
3245 ), array('auto_dates'));
\r
3246 </programlisting></para>
\r
3250 <title>php_xmlrpc_decode_xml</title>
\r
3254 <funcdef><type>xmlrpcval | xmlrpcresp |
\r
3255 xmlrpcmsg</type><function>php_xmlrpc_decode_xml</function></funcdef>
\r
3257 <paramdef><type>string</type><parameter>$xml</parameter></paramdef>
\r
3259 <paramdef><type>array</type><parameter>$options</parameter></paramdef>
\r
3263 <para>Decodes the xml representation of either an xmlrpc request,
\r
3264 response or single value, returning the corresponding php-xmlrpc
\r
3265 object, or <literal>FALSE</literal> in case of an error.</para>
\r
3267 <para>The <parameter>options</parameter> parameter is optional. If
\r
3268 specified, it must consist of an array of options to be enabled in the
\r
3269 decoding process. At the moment, no option is supported.</para>
\r
3271 <para>Example:<programlisting language="php">
\r
3272 $text = '<value><array><data><value>Hello world</value></data></array></value>';
\r
3273 $val = php_xmlrpc_decode_xml($text);
\r
3274 if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';
\r
3275 </programlisting></para>
\r
3280 <title>Automatic conversion of php functions into xmlrpc methods (and
\r
3281 vice versa)</title>
\r
3283 <para>For the extremely lazy coder, helper functions have been added
\r
3284 that allow to convert a php function into an xmlrpc method, and a
\r
3285 remotely exposed xmlrpc method into a local php function - or a set of
\r
3286 methods into a php class. Note that these comes with many caveat.</para>
\r
3289 <title>wrap_xmlrpc_method</title>
\r
3293 <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
\r
3295 <paramdef>$client</paramdef>
\r
3297 <paramdef>$methodname</paramdef>
\r
3299 <paramdef>$extra_options</paramdef>
\r
3303 <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
\r
3305 <paramdef>$client</paramdef>
\r
3307 <paramdef>$methodname</paramdef>
\r
3309 <paramdef>$signum</paramdef>
\r
3311 <paramdef>$timeout</paramdef>
\r
3313 <paramdef>$protocol</paramdef>
\r
3315 <paramdef>$funcname</paramdef>
\r
3319 <para>Given an xmlrpc server and a method name, creates a php wrapper
\r
3320 function that will call the remote method and return results using
\r
3321 native php types for both params and results. The generated php
\r
3322 function will return an xmlrpcresp object for failed xmlrpc
\r
3325 <para>The second syntax is deprecated, and is listed here only for
\r
3326 backward compatibility.</para>
\r
3328 <para>The server must support the
\r
3329 <methodname>system.methodSignature</methodname> xmlrpc method call for
\r
3330 this function to work.</para>
\r
3332 <para>The <parameter>client</parameter> param must be a valid
\r
3333 xmlrpc_client object, previously created with the address of the
\r
3334 target xmlrpc server, and to which the preferred communication options
\r
3335 have been set.</para>
\r
3337 <para>The optional parameters can be passed as array key,value pairs
\r
3338 in the <parameter>extra_options</parameter> param.</para>
\r
3340 <para>The <parameter>signum</parameter> optional param has the purpose
\r
3341 of indicating which method signature to use, if the given server
\r
3342 method has multiple signatures (defaults to 0).</para>
\r
3344 <para>The <parameter>timeout</parameter> and
\r
3345 <parameter>protocol</parameter> optional params are the same as in the
\r
3346 <methodname>xmlrpc_client::send()</methodname> method.</para>
\r
3348 <para>If set, the optional <parameter>new_function_name</parameter>
\r
3349 parameter indicates which name should be used for the generated
\r
3350 function. In case it is not set the function name will be
\r
3351 auto-generated.</para>
\r
3353 <para>If the <literal>return_source</literal> optional parameter is
\r
3354 set, the function will return the php source code to build the wrapper
\r
3355 function, instead of evaluating it (useful to save the code and use it
\r
3356 later as stand-alone xmlrpc client).</para>
\r
3358 <para>If the <literal>encode_php_objs</literal> optional parameter is
\r
3359 set, instances of php objects later passed as parameters to the newly
\r
3360 created function will receive a 'special' treatment that allows the
\r
3361 server to rebuild them as php objects instead of simple arrays. Note
\r
3362 that this entails using a "slightly augmented" version of the xmlrpc
\r
3363 protocol (ie. using element attributes), which might not be understood
\r
3364 by xmlrpc servers implemented using other libraries.</para>
\r
3366 <para>If the <literal>decode_php_objs</literal> optional parameter is
\r
3367 set, instances of php objects that have been appropriately encoded by
\r
3368 the server using a coordinate option will be deserialized as php
\r
3369 objects instead of simple arrays (the same class definition should be
\r
3370 present server side and client side).</para>
\r
3372 <para><emphasis>Note that this might pose a security risk</emphasis>,
\r
3373 since in order to rebuild the object instances their constructor
\r
3374 method has to be invoked, and this means that the remote server can
\r
3375 trigger execution of unforeseen php code on the client: not really a
\r
3376 code injection, but almost. Please enable this option only when you
\r
3377 trust the remote server.</para>
\r
3379 <para>In case of an error during generation of the wrapper function,
\r
3380 FALSE is returned, otherwise the name (or source code) of the new
\r
3383 <para>Known limitations: server must support
\r
3384 <methodname>system.methodsignature</methodname> for the wanted xmlrpc
\r
3385 method; for methods that expose multiple signatures, only one can be
\r
3386 picked; for remote calls with nested xmlrpc params, the caller of the
\r
3387 generated php function has to encode on its own the params passed to
\r
3388 the php function if these are structs or arrays whose (sub)members
\r
3389 include values of type base64.</para>
\r
3391 <para>Note: calling the generated php function 'might' be slow: a new
\r
3392 xmlrpc client is created on every invocation and an xmlrpc-connection
\r
3393 opened+closed. An extra 'debug' param is appended to the parameter
\r
3394 list of the generated php function, useful for debugging
\r
3397 <para>Example usage:</para>
\r
3399 <programlisting language="php">
\r
3400 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
\r
3402 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
\r
3405 die('Cannot introspect remote method');
\r
3408 $statename = $function($a);
\r
3409 if (is_a($statename, 'xmlrpcresp')) // call failed
\r
3411 echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
\r
3412 $function($a, true);
\r
3415 echo "OK, state nr. $stateno is $statename";
\r
3420 <sect2 id="wrap_php_function">
\r
3421 <title>wrap_php_function</title>
\r
3425 <funcdef><type>array</type><function>wrap_php_function</function></funcdef>
\r
3427 <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>
\r
3429 <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>
\r
3431 <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>
\r
3435 <para>Given a user-defined PHP function, create a PHP 'wrapper'
\r
3436 function that can be exposed as xmlrpc method from an xmlrpc_server
\r
3437 object and called from remote clients, and return the appropriate
\r
3438 definition to be added to a server's dispatch map.</para>
\r
3440 <para>The optional <parameter>$wrapper_function_name</parameter>
\r
3441 specifies the name that will be used for the auto-generated
\r
3444 <para>Since php is a typeless language, to infer types of input and
\r
3445 output parameters, it relies on parsing the javadoc-style comment
\r
3446 block associated with the given function. Usage of xmlrpc native types
\r
3447 (such as datetime.dateTime.iso8601 and base64) in the docblock @param
\r
3448 tag is also allowed, if you need the php function to receive/send data
\r
3449 in that particular format (note that base64 encoding/decoding is
\r
3450 transparently carried out by the lib, while datetime vals are passed
\r
3451 around as strings).</para>
\r
3453 <para>Known limitations: requires PHP 5.0.3 +; only works for
\r
3454 user-defined functions, not for PHP internal functions (reflection
\r
3455 does not support retrieving number/type of params for those); the
\r
3456 wrapped php function will not be able to programmatically return an
\r
3457 xmlrpc error response.</para>
\r
3459 <para>If the <literal>return_source</literal> optional parameter is
\r
3460 set, the function will return the php source code to build the wrapper
\r
3461 function, instead of evaluating it (useful to save the code and use it
\r
3462 later in a stand-alone xmlrpc server). It will be in the stored in the
\r
3463 <literal>source</literal> member of the returned array.</para>
\r
3465 <para>If the <literal>suppress_warnings</literal> optional parameter
\r
3466 is set, any runtime warning generated while processing the
\r
3467 user-defined php function will be catched and not be printed in the
\r
3468 generated xml response.</para>
\r
3470 <para>If the <parameter>extra_options</parameter> array contains the
\r
3471 <literal>encode_php_objs</literal> value, wrapped functions returning
\r
3472 php objects will generate "special" xmlrpc responses: when the xmlrpc
\r
3473 decoding of those responses is carried out by this same lib, using the
\r
3474 appropriate param in php_xmlrpc_decode(), the objects will be
\r
3477 <para>In short: php objects can be serialized, too (except for their
\r
3478 resource members), using this function. Other libs might choke on the
\r
3479 very same xml that will be generated in this case (i.e. it has a
\r
3480 nonstandard attribute on struct element tags)</para>
\r
3482 <para>If the <literal>decode_php_objs</literal> optional parameter is
\r
3483 set, instances of php objects that have been appropriately encoded by
\r
3484 the client using a coordinate option will be deserialized and passed
\r
3485 to the user function as php objects instead of simple arrays (the same
\r
3486 class definition should be present server side and client
\r
3489 <para><emphasis>Note that this might pose a security risk</emphasis>,
\r
3490 since in order to rebuild the object instances their constructor
\r
3491 method has to be invoked, and this means that the remote client can
\r
3492 trigger execution of unforeseen php code on the server: not really a
\r
3493 code injection, but almost. Please enable this option only when you
\r
3494 trust the remote clients.</para>
\r
3496 <para>Example usage:</para>
\r
3498 <para><programlisting language="php">/**
\r
3499 * State name from state number decoder. NB: do NOT remove this comment block.
\r
3500 * @param integer $stateno the state number
\r
3501 * @return string the name of the state (or error description)
\r
3503 function findstate($stateno)
\r
3505 global $stateNames;
\r
3506 if (isset($stateNames[$stateno-1]))
\r
3508 return $stateNames[$stateno-1];
\r
3512 return "I don't have a state for the index '" . $stateno . "'";
\r
3516 // wrap php function, build xmlrpc server
\r
3517 $methods = array();
\r
3518 $findstate_sig = wrap_php_function('findstate');
\r
3519 if ($findstate_sig)
\r
3520 $methods['examples.getStateName'] = $findstate_sig;
\r
3521 $srv = new xmlrpc_server($methods);
\r
3522 </programlisting></para>
\r
3526 <sect1 id="deprecated">
\r
3527 <title>Functions removed from the library</title>
\r
3529 <para>The following two functions have been deprecated in version 1.1 of
\r
3530 the library, and removed in version 2, in order to avoid conflicts with
\r
3531 the EPI xml-rpc library, which also defines two functions with the same
\r
3534 <para>To ease the transition to the new naming scheme and avoid breaking
\r
3535 existing implementations, the following scheme has been adopted:
\r
3538 <para>If EPI-XMLRPC is not active in the current PHP installation,
\r
3539 the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
\r
3540 <literal>'0'</literal></para>
\r
3544 <para>If EPI-XMLRPC is active in the current PHP installation, the
\r
3545 constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
\r
3546 <literal>'1'</literal></para>
\r
3548 </itemizedlist></para>
\r
3550 <para>The following documentation is kept for historical
\r
3553 <sect2 id="xmlrpcdecode">
\r
3554 <title>xmlrpc_decode</title>
\r
3558 <funcdef><type>mixed</type><function>xmlrpc_decode</function></funcdef>
\r
3560 <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
\r
3564 <para>Alias for php_xmlrpc_decode.</para>
\r
3567 <sect2 id="xmlrpcencode">
\r
3568 <title>xmlrpc_encode</title>
\r
3572 <funcdef><type>xmlrpcval</type><function>xmlrpc_encode</function></funcdef>
\r
3574 <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
\r
3578 <para>Alias for php_xmlrpc_encode.</para>
\r
3582 <sect1 id="debugging">
\r
3583 <title>Debugging aids</title>
\r
3586 <title>xmlrpc_debugmsg</title>
\r
3590 <funcdef><type>void</type><function>xmlrpc_debugmsg</function></funcdef>
\r
3592 <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>
\r
3596 <para>Sends the contents of <parameter>$debugstring</parameter> in XML
\r
3597 comments in the server return payload. If a PHP client has debugging
\r
3598 turned on, the user will be able to see server debug
\r
3599 information.</para>
\r
3601 <para>Use this function in your methods so you can pass back
\r
3602 diagnostic information. It is only available from
\r
3603 <filename>xmlrpcs.inc</filename>.</para>
\r
3608 <chapter id="reserved" xreflabel="Reserved methods">
\r
3609 <title>Reserved methods</title>
\r
3611 <para>In order to extend the functionality offered by XML-RPC servers
\r
3612 without impacting on the protocol, reserved methods are supported in this
\r
3615 <para>All methods starting with <function>system.</function> are
\r
3616 considered reserved by the server. PHP for XML-RPC itself provides four
\r
3617 special methods, detailed in this chapter.</para>
\r
3619 <para>Note that all server objects will automatically respond to clients
\r
3620 querying these methods, unless the property
\r
3621 <property>allow_system_funcs</property> has been set to
\r
3622 <constant>false</constant> before calling the
\r
3623 <methodname>service()</methodname> method. This might pose a security risk
\r
3624 if the server is exposed to public access, e.g. on the internet.</para>
\r
3627 <title>system.getCapabilities</title>
\r
3633 <title>system.listMethods</title>
\r
3635 <para>This method may be used to enumerate the methods implemented by
\r
3636 the XML-RPC server.</para>
\r
3638 <para>The <function>system.listMethods</function> method requires no
\r
3639 parameters. It returns an array of strings, each of which is the name of
\r
3640 a method implemented by the server.</para>
\r
3643 <sect1 id="sysmethodsig">
\r
3644 <title>system.methodSignature</title>
\r
3646 <para>This method takes one parameter, the name of a method implemented
\r
3647 by the XML-RPC server.</para>
\r
3649 <para>It returns an array of possible signatures for this method. A
\r
3650 signature is an array of types. The first of these types is the return
\r
3651 type of the method, the rest are parameters.</para>
\r
3653 <para>Multiple signatures (i.e. overloading) are permitted: this is the
\r
3654 reason that an array of signatures are returned by this method.</para>
\r
3656 <para>Signatures themselves are restricted to the top level parameters
\r
3657 expected by a method. For instance if a method expects one array of
\r
3658 structs as a parameter, and it returns a string, its signature is simply
\r
3659 "string, array". If it expects three integers, its signature is "string,
\r
3660 int, int, int".</para>
\r
3662 <para>For parameters that can be of more than one type, the "undefined"
\r
3663 string is supported.</para>
\r
3665 <para>If no signature is defined for the method, a not-array value is
\r
3666 returned. Therefore this is the way to test for a non-signature, if
\r
3667 <parameter>$resp</parameter> below is the response object from a method
\r
3668 call to <function>system.methodSignature</function>:</para>
\r
3670 <programlisting language="php">
\r
3671 $v = $resp->value();
\r
3672 if ($v->kindOf() != "array") {
\r
3673 // then the method did not have a signature defined
\r
3677 <para>See the <filename>introspect.php</filename> demo included in this
\r
3678 distribution for an example of using this method.</para>
\r
3681 <sect1 id="sysmethhelp">
\r
3682 <title>system.methodHelp</title>
\r
3684 <para>This method takes one parameter, the name of a method implemented
\r
3685 by the XML-RPC server.</para>
\r
3687 <para>It returns a documentation string describing the use of that
\r
3688 method. If no such string is available, an empty string is
\r
3691 <para>The documentation string may contain HTML markup.</para>
\r
3695 <title>system.multicall</title>
\r
3697 <para>This method takes one parameter, an array of 'request' struct
\r
3698 types. Each request struct must contain a
\r
3699 <parameter>methodName</parameter> member of type string and a
\r
3700 <parameter>params</parameter> member of type array, and corresponds to
\r
3701 the invocation of the corresponding method.</para>
\r
3703 <para>It returns a response of type array, with each value of the array
\r
3704 being either an error struct (containing the faultCode and faultString
\r
3705 members) or the successful response value of the corresponding single
\r
3706 method call.</para>
\r
3710 <chapter id="examples" xreflabel="Examples">
\r
3711 <title>Examples</title>
\r
3713 <para>The best examples are to be found in the sample files included with
\r
3714 the distribution. Some are included here.</para>
\r
3716 <sect1 id="statename">
\r
3717 <title>XML-RPC client: state name query</title>
\r
3719 <para>Code to get the corresponding state name from a number (1-50) from
\r
3720 the demo server available on SourceForge</para>
\r
3722 <programlisting language="php">
\r
3723 $m = new xmlrpcmsg('examples.getStateName',
\r
3724 array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
\r
3725 $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
\r
3726 $r = $c->send($m);
\r
3727 if (!$r->faultCode()) {
\r
3728 $v = $r->value();
\r
3729 print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
\r
3730 htmlentities($v->scalarval()) . "<BR>";
\r
3731 print "<HR>I got this value back<BR><PRE>" .
\r
3732 htmlentities($r->serialize()) . "</PRE><HR>\n";
\r
3734 print "Fault <BR>";
\r
3735 print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
\r
3736 "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
\r
3742 <title>Executing a multicall call</title>
\r
3744 <para>To be documented...</para>
\r
3748 <chapter id="faq">
\r
3749 <title>Frequently Asked Questions</title>
\r
3752 <title>How to send custom XML as payload of a method call</title>
\r
3754 <para>Unfortunately, at the time the XML-RPC spec was designed, support
\r
3755 for namespaces in XML was not as ubiquitous as it is now. As a
\r
3756 consequence, no support was provided in the protocol for embedding XML
\r
3757 elements from other namespaces into an xmlrpc request.</para>
\r
3759 <para>To send an XML "chunk" as payload of a method call or response,
\r
3760 two options are available: either send the complete XML block as a
\r
3761 string xmlrpc value, or as a base64 value. Since the '<' character in
\r
3762 string values is encoded as '&lt;' in the xml payload of the method
\r
3763 call, the XML string will not break the surrounding xmlrpc, unless
\r
3764 characters outside of the assumed character set are used. The second
\r
3765 method has the added benefits of working independently of the charset
\r
3766 encoding used for the xml to be transmitted, and preserving exactly
\r
3767 whitespace, whilst incurring in some extra message length and cpu load
\r
3768 (for carrying out the base64 encoding/decoding).</para>
\r
3772 <title>Is there any limitation on the size of the requests / responses
\r
3773 that can be successfully sent?</title>
\r
3775 <para>Yes. But I have no hard figure to give; it most likely will depend
\r
3776 on the version of PHP in usage and its configuration.</para>
\r
3778 <para>Keep in mind that this library is not optimized for speed nor for
\r
3779 memory usage. Better alternatives exist when there are strict
\r
3780 requirements on throughput or resource usage, such as the php native
\r
3781 xmlrpc extension (see the PHP manual for more information).</para>
\r
3783 <para>Keep in mind also that HTTP is probably not the best choice in
\r
3784 such a situation, and XML is a deadly enemy. CSV formatted data over
\r
3785 socket would be much more efficient.</para>
\r
3787 <para>If you really need to move a massive amount of data around, and
\r
3788 you are crazy enough to do it using phpxmlrpc, your best bet is to
\r
3789 bypass usage of the xmlrpcval objects, at least in the decoding phase,
\r
3790 and have the server (or client) object return to the calling function
\r
3791 directly php values (see <varname>xmlrpc_client::return_type</varname>
\r
3792 and <varname>xmlrpc_server::functions_parameters_type</varname> for more
\r
3797 <title>My server (client) returns an error whenever the client (server)
\r
3798 returns accented characters</title>
\r
3800 <para>To be documented...</para>
\r
3804 <title>My php error log is getting full of "deprecated" errors on
\r
3805 different lines of xmlrpc.inc and xmlrpcs.inc</title>
\r
3807 <para>This happens when the PHP in usage is version 5, and the error
\r
3808 reporting level is set to include <constant>E_STRICT</constant> errors.
\r
3809 Since the main development platform of the library remains (for the time
\r
3810 being) PHP 4, there are no plans to fix this asap. The best workaround
\r
3811 is to set the error reporting level to <constant>E_ALL ^
\r
3812 E_STRICT</constant>.</para>
\r
3816 <title>How to enable long-lasting method calls</title>
\r
3818 <para>To be documented...</para>
\r
3822 <title>My client returns "XML-RPC Fault #2: Invalid return payload:
\r
3823 enable debugging to examine incoming payload": what should I do?</title>
\r
3825 <para>The response you are seeing is a default error response that the
\r
3826 client object returns to the php application when the server did not
\r
3827 respond to the call with a valid xmlrpc response.</para>
\r
3829 <para>The most likely cause is that you are not using the correct URL
\r
3830 when creating the client object, or you do not have appropriate access
\r
3831 rights to the web page you are requesting, or some other common http
\r
3832 misconfiguration.</para>
\r
3834 <para>To find out what the server is really returning to your client,
\r
3835 you have to enable the debug mode of the client, using
\r
3836 $client->setdebug(1);</para>
\r
3840 <title>How can I save to a file the xml of the xmlrpc responses received
\r
3841 from servers?</title>
\r
3843 <para>If what you need is to save the responses received from the server
\r
3844 as xml, you have two options:</para>
\r
3846 <para>1- use the serialize() method on the response object.</para>
\r
3848 <programlisting language="php">
\r
3849 $resp = $client->send($msg);
\r
3850 if (!$resp->faultCode())
\r
3851 $data_to_be_saved = $resp->serialize();
\r
3854 <para>Note that this will not be 100% accurate, since the xml generated
\r
3855 by the response object can be different from the xml received,
\r
3856 especially if there is some character set conversion involved, or such
\r
3857 (eg. if you receive an empty string tag as <string/>, serialize()
\r
3858 will output <string></string>), or if the server sent back
\r
3859 as response something invalid (in which case the xml generated client
\r
3860 side using serialize() will correspond to the error response generated
\r
3861 internally by the lib).</para>
\r
3863 <para>2 - set the client object to return the raw xml received instead
\r
3864 of the decoded objects:</para>
\r
3866 <programlisting language="php">
\r
3867 $client = new xmlrpc_client($url);
\r
3868 $client->return_type = 'xml';
\r
3869 $resp = $client->send($msg);
\r
3870 if (!$resp->faultCode())
\r
3871 $data_to_be_saved = $resp->value();
\r
3874 <para>Note that using this method the xml response response will not be
\r
3875 parsed at all by the library, only the http communication protocol will
\r
3876 be checked. This means that xmlrpc responses sent by the server that
\r
3877 would have generated an error response on the client (eg. malformed xml,
\r
3878 responses that have faultcode set, etc...) now will not be flagged as
\r
3879 invalid, and you might end up saving not valid xml but random
\r
3884 <title>Can I use the ms windows character set?</title>
\r
3886 <para>If the data your application is using comes from a Microsoft
\r
3887 application, there are some chances that the character set used to
\r
3888 encode it is CP1252 (the same might apply to data received from an
\r
3889 external xmlrpc server/client, but it is quite rare to find xmlrpc
\r
3890 toolkits that encode to CP1252 instead of UTF8). It is a character set
\r
3891 which is "almost" compatible with ISO 8859-1, but for a few extra
\r
3892 characters.</para>
\r
3894 <para>PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
\r
3895 The net result of this situation is that those extra characters will not
\r
3896 be properly encoded, and will be received at the other end of the
\r
3897 XML-RPC tranmission as "garbled data". Unfortunately the library cannot
\r
3898 provide real support for CP1252 because of limitations in the PHP 4 xml
\r
3899 parser. Luckily, we tried our best to support this character set anyway,
\r
3900 and, since version 2.2.1, there is some form of support, left commented
\r
3901 in the code.</para>
\r
3903 <para>To properly encode outgoing data that is natively in CP1252, you
\r
3904 will have to uncomment all relative code in the file
\r
3905 <filename>xmlrpc.inc</filename> (you can search for the string "1252"),
\r
3906 then set <code>$GLOBALS['xmlrpc_internalencoding']='CP1252';</code>
\r
3907 Please note that all incoming data will then be fed to your application
\r
3908 as UTF-8 to avoid any potentail data loss.</para>
\r
3912 <title>Does the library support using cookies / http sessions?</title>
\r
3914 <para>In short: yes, but a little coding is needed to make it
\r
3917 <para>The code below uses sessions to e.g. let the client store a value
\r
3918 on the server and retrieve it later.</para>
\r
3920 <para><programlisting>
\r
3921 $resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
\r
3922 if (!$resp->faultCode())
\r
3924 $cookies = $resp->cookies();
\r
3925 if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
\r
3927 $session_id = $cookies['PHPSESSID']['value'];
\r
3929 // do some other stuff here...
\r
3931 $client->setcookie('PHPSESSID', $session_id);
\r
3932 $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
\r
3935 </programlisting>Server-side sessions are handled normally like in any other
\r
3936 php application. Please see the php manual for more information about
\r
3939 <para>NB: unlike web browsers, not all xmlrpc clients support usage of
\r
3940 http cookies. If you have troubles with sessions and control only the
\r
3941 server side of the communication, please check with the makers of the
\r
3942 xmlrpc client in use.</para>
\r
3946 <appendix id="integration">
\r
3947 <title>Integration with the PHP xmlrpc extension</title>
\r
3949 <para>To be documented more...</para>
\r
3951 <para>In short: for the fastest execution possible, you can enable the php
\r
3952 native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
\r
3953 following code snippet gives an example of such integration</para>
\r
3955 <programlisting language="php">
\r
3956 /*** client side ***/
\r
3957 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
\r
3959 // tell the client to return raw xml as response value
\r
3960 $c->return_type = 'xml';
\r
3962 // let the native xmlrpc extension take care of encoding request parameters
\r
3963 $r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
\r
3965 if ($r->faultCode())
\r
3966 // HTTP transport error
\r
3967 echo 'Got error '.$r->faultCode();
\r
3970 // HTTP request OK, but XML returned from server not parsed yet
\r
3971 $v = xmlrpc_decode($r->value());
\r
3972 // check if we got a valid xmlrpc response from server
\r
3974 echo 'Got invalid response';
\r
3976 // check if server sent a fault response
\r
3977 if (xmlrpc_is_fault($v))
\r
3978 echo 'Got xmlrpc fault '.$v['faultCode'];
\r
3980 echo'Got response: '.htmlentities($v);
\r
3985 <appendix id="substitution">
\r
3986 <title>Substitution of the PHP xmlrpc extension</title>
\r
3988 <para>Yet another interesting situation is when you are using a ready-made
\r
3989 php application, that provides support for the XMLRPC protocol via the
\r
3990 native php xmlrpc extension, but the extension is not available on your
\r
3991 php install (e.g. because of shared hosting constraints).</para>
\r
3993 <para>Since version 2.1, the PHP-XMLRPC library provides a compatibility
\r
3994 layer that aims to be 100% compliant with the xmlrpc extension API. This
\r
3995 means that any code written to run on the extension should obtain the
\r
3996 exact same results, albeit using more resources and a longer processing
\r
3997 time, using the PHP-XMLRPC library and the extension compatibility module.
\r
3998 The module is part of the EXTRAS package, available as a separate download
\r
3999 from the sourceforge.net website, since version 0.2</para>
\r
4002 <appendix id="enough">
\r
4003 <title>'Enough of xmlrpcvals!': new style library usage</title>
\r
4005 <para>To be documented...</para>
\r
4007 <para>In the meantime, see docs about xmlrpc_client::return_type and
\r
4008 xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
\r
4009 php_xmlrpc_decode and php_xmlrpc_decode_xml</para>
\r
4012 <appendix id="debugger">
\r
4013 <title>Usage of the debugger</title>
\r
4015 <para>A webservice debugger is included in the library to help during
\r
4016 development and testing.</para>
\r
4018 <para>The interface should be self-explicative enough to need little
\r
4019 documentation.</para>
\r
4021 <para><graphic align="center" fileref="debugger.gif"
\r
4022 format="GIF" /></para>
\r
4024 <para>The most useful feature of the debugger is without doubt the "Show
\r
4025 debug info" option. It allows to have a screen dump of the complete http
\r
4026 communication between client and server, including the http headers as
\r
4027 well as the request and response payloads, and is invaluable when
\r
4028 troubleshooting problems with charset encoding, authentication or http
\r
4029 compression.</para>
\r
4031 <para>The debugger can take advantage of the JSONRPC library extension, to
\r
4032 allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
\r
4033 visual editor to allow easy mouse-driven construction of the payload for
\r
4034 remote methods. Both components have to be downloaded separately from the
\r
4035 sourceforge.net web pages and copied to the debugger directory to enable
\r
4036 the extra functionality:</para>
\r
4038 <para><itemizedlist>
\r
4040 <para>to enable jsonrpc functionality, download the PHP-XMLRPC
\r
4041 EXTRAS package, and copy the file <filename>jsonrpc.inc</filename>
\r
4042 either to the same directory as the debugger or somewhere in your
\r
4043 php include path</para>
\r
4045 </itemizedlist><itemizedlist>
\r
4047 <para>to enable the visual value editing dialog, download the
\r
4048 JS-XMLRPC library, and copy somewhere in the web root files
\r
4049 <filename>visualeditor.php</filename>,
\r
4050 <filename>visualeditor.css</filename> and the folders
\r
4051 <filename>yui</filename> and <filename>img</filename>. Then edit the
\r
4052 debugger file <filename>controller.php</filename> and set
\r
4053 appropriately the variable <varname>$editorpath</varname>.</para>
\r
4055 </itemizedlist></para>
\r
4058 <!-- Keep this comment at the end of the file
\r
4063 sgml-minimize-attributes:nil
\r
4064 sgml-always-quote-attributes:t
\r
4065 sgml-indent-step:2
\r
4066 sgml-indent-data:t
\r
4067 sgml-parent-document:nil
\r
4068 sgml-exposed-tags:nil
\r
4069 sgml-local-catalogs:nil
\r
4070 sgml-local-ecat-files:nil
\r
4071 sgml-namecase-general:t
\r
4072 sgml-general-insert-case:lower
\r
git://git.onelab.eu / plcapi.git / blob