doc/xmlrpc_php.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
   3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   5 <!--
   6 PHP-XMLRPC User manual
   7 -->
   8 <book lang="en">
   9   <title>XML-RPC for PHP</title>
  10
  11   <subtitle>version 3.0.0</subtitle>
  12
  13   <bookinfo>
  14     <date>June 15, 2014</date>
  15
  16     <authorgroup>
  17       <author>
  18         <firstname>Edd</firstname>
  19
  20         <surname>Dumbill</surname>
  21       </author>
  22
  23       <author>
  24         <firstname>Gaetano</firstname>
  25
  26         <surname>Giunta</surname>
  27       </author>
  28
  29       <author>
  30         <firstname>Miles</firstname>
  31
  32         <surname>Lott</surname>
  33       </author>
  34
  35       <author>
  36         <firstname>Justin R.</firstname>
  37
  38         <surname>Miller</surname>
  39       </author>
  40
  41       <author>
  42         <firstname>Andres</firstname>
  43
  44         <surname>Salomon</surname>
  45       </author>
  46     </authorgroup>
  47
  48     <copyright>
  49       <year>1999,2000,2001</year>
  50
  51       <holder>Edd Dumbill, Useful Information Company</holder>
  52     </copyright>
  53
  54     <legalnotice>
  55       <para>All rights reserved.</para>
  56
  57       <para>Redistribution and use in source and binary forms, with or without
  58       modification, are permitted provided that the following conditions are
  59       met:</para>
  60
  61       <para><itemizedlist>
  62           <listitem>
  63             <para>Redistributions of source code must retain the above
  64             copyright notice, this list of conditions and the following
  65             disclaimer.</para>
  66           </listitem>
  67
  68           <listitem>
  69             <para>Redistributions in binary form must reproduce the above
  70             copyright notice, this list of conditions and the following
  71             disclaimer in the documentation and/or other materials provided
  72             with the distribution.</para>
  73           </listitem>
  74
  75           <listitem>
  76             <para>Neither the name of the "XML-RPC for PHP" nor the names of
  77             its contributors may be used to endorse or promote products
  78             derived from this software without specific prior written
  79             permission.</para>
  80           </listitem>
  81         </itemizedlist></para>
  82
  83       <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  84       CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
  85       BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  86       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  87       REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  88       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  89       TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  90       PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  91       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  92       NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  93       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
  94     </legalnotice>
  95   </bookinfo>
  96
  97   <chapter id="introduction">
  98     <title>Introduction</title>
  99
 100     <para>XML-RPC is a format devised by <ulink
 101     url="http://www.userland.com/">Userland Software</ulink> for achieving
 102     remote procedure call via XML using HTTP as the transport. XML-RPC has its
 103     own web site, <ulink
 104     url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>
 105
 106     <para>This collection of PHP classes provides a framework for writing
 107     XML-RPC clients and servers in PHP.</para>
 108
 109     <para>Main goals of the project are ease of use, flexibility and
 110     completeness.</para>
 111
 112     <para>The original author is Edd Dumbill of <ulink
 113     url="http://usefulinc.com/">Useful Information Company</ulink>. As of the
 114     1.0 stable release, the project was opened to wider involvement and moved
 115     to <ulink
 116     url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>; later, to <ulink
 117     url="https://github.com/">Github</ulink></para>
 118
 119     <para>A list of XML-RPC implementations for other languages such as Perl
 120     and Python can be found on the <ulink
 121     url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>
 122
 123     <sect1>
 124       <title>Acknowledgements</title>
 125
 126       <para>Daniel E. Baumann</para>
 127
 128       <para>James Bercegay</para>
 129
 130       <para>Leon Blackwell</para>
 131
 132       <para>Stephane Bortzmeyer</para>
 133
 134       <para>Daniel Convissor</para>
 135
 136       <para>Geoffrey T. Dairiki</para>
 137
 138       <para>Stefan Esser</para>
 139
 140       <para>James Flemer</para>
 141
 142       <para>Ernst de Haan</para>
 143
 144       <para>Tom Knight</para>
 145
 146       <para>Axel Kollmorgen</para>
 147
 148       <para>Peter Kocks</para>
 149
 150       <para>Daniel Krippner</para>
 151
 152       <para>S. Kuip</para>
 153
 154       <para>A. Lambert</para>
 155
 156       <para>Frederic Lecointre</para>
 157
 158       <para>Dan Libby</para>
 159
 160       <para>Arnaud Limbourg</para>
 161
 162       <para>Ernest MacDougal Campbell III</para>
 163
 164       <para>Lukasz Mach</para>
 165
 166       <para>Kjartan Mannes</para>
 167
 168       <para>Ben Margolin</para>
 169
 170       <para>Nicolay Mausz</para>
 171
 172       <para>Justin Miller</para>
 173
 174       <para>Jan Pfeifer</para>
 175
 176       <para>Giancarlo Pinerolo</para>
 177
 178       <para>Peter Russel</para>
 179
 180       <para>Jean-Jacques Sarton</para>
 181
 182       <para>Viliam Simko</para>
 183
 184       <para>Idan Sofer</para>
 185
 186       <para>Douglas Squirrel</para>
 187
 188       <para>Heiko Stübner</para>
 189
 190       <para>Anatoly Techtonik</para>
 191
 192       <para>Tommaso Trani</para>
 193
 194       <para>Eric van der Vlist</para>
 195
 196       <para>Christian Wenz</para>
 197
 198       <para>Jim Winstead</para>
 199
 200       <para>Przemyslaw Wroblewski</para>
 201
 202       <para>Bruno Zanetti Melotti</para>
 203     </sect1>
 204   </chapter>
 205
 206   <chapter id="news">
 207     <title>What's new</title>
 208
 209     <para><emphasis>Note:</emphasis> not all items the following list have
 210     (yet) been fully documented, and some might not be present in any other
 211     chapter in the manual. To find a more detailed description of new
 212     functions and methods please take a look at the source code of the
 213     library, which is quite thoroughly commented in javadoc-like form.</para>
 214
 215     <sect1>
 216       <title>3.0.0</title>
 217
 218       <para><emphasis>Note:</emphasis> this is the last release of the library that will support PHP 5.1 and up.
 219       Future releases will target php 5.3 as minimum supported version.</para>
 220
 221       <para><itemizedlist>
 222       <listitem>
 223         <para>when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)</para>
 224       </listitem>
 225
 226       <listitem>
 227         <para>omit port on http 'Host' header if it is 80</para>
 228       </listitem>
 229
 230       <listitem>
 231         <para>test suite allows interrogating https servers ignoring their certs</para>
 232       </listitem>
 233
 234       <listitem>
 235         <para>method setAcceptedCompression was failing to disable reception of compressed responses if the
 236          client supported them</para>
 237       </listitem>
 238
 239       </itemizedlist></para>
 240     </sect1>
 241
 242     <sect1>
 243       <title>3.0.0 beta</title>
 244
 245       <para>This is the first release of the library to only support PHP 5.
 246       Some legacy code has been removed, and support for features such as
 247       exceptions and dateTime objects introduced.</para>
 248
 249       <para>The "beta" tag is meant to indicate the fact that the refactoring
 250       has been more widespread than in precedent releases and that more
 251       changes are likely to be introduced with time - the library is still
 252       considered to be production quality.</para>
 253
 254       <para><itemizedlist>
 255           <listitem>
 256             <para>improved: removed all usage of php functions deprecated in
 257             php 5.3, usage of assign-by-ref when creating new objects
 258             etc...</para>
 259           </listitem>
 260
 261           <listitem>
 262             <para>improved: add support for the &lt;ex:nil/&gt; tag used by
 263             the apache library, both in input and output</para>
 264           </listitem>
 265
 266           <listitem>
 267             <para>improved: add support for <classname>dateTime</classname>
 268             objects in both in <function>php_xmlrpc_encode</function> and as
 269             parameter for constructor of
 270             <classname>xmlrpcval</classname></para>
 271           </listitem>
 272
 273           <listitem>
 274             <para>improved: add support for timestamps as parameter for
 275             constructor of <classname>xmlrpcval</classname></para>
 276           </listitem>
 277
 278           <listitem>
 279             <para>improved: add option 'dates_as_objects' to
 280             <function>php_xmlrpc_decode</function> to return
 281             <classname>dateTime</classname> objects for xmlrpc
 282             datetimes</para>
 283           </listitem>
 284
 285           <listitem>
 286             <para>improved: add new method
 287             <methodname>SetCurlOptions</methodname> to
 288             <classname>xmrlpc_client</classname> to allow extra flexibility in
 289             tweaking http config, such as explicitly binding to an ip
 290             address</para>
 291           </listitem>
 292
 293           <listitem>
 294             <para>improved: add new method
 295             <methodname>SetUserAgent</methodname> to
 296             <classname>xmrlpc_client</classname> to to allow having different
 297             user-agent http headers</para>
 298           </listitem>
 299
 300           <listitem>
 301             <para>improved: add a new member variable in server class to allow
 302             fine-tuning of the encoding of returned values when the server is
 303             in 'phpvals' mode</para>
 304           </listitem>
 305
 306           <listitem>
 307             <para>improved: allow servers in 'xmlrpcvals' mode to also
 308             register plain php functions by defining them in the dispatch map
 309             with an added option</para>
 310           </listitem>
 311
 312           <listitem>
 313             <para>improved: catch exceptions thrown during execution of php
 314             functions exposed as methods by the server</para>
 315           </listitem>
 316
 317           <listitem>
 318             <para>fixed: bad encoding if same object is encoded twice using
 319             php_xmlrpc_encode</para>
 320           </listitem>
 321         </itemizedlist></para>
 322     </sect1>
 323
 324     <sect1>
 325       <title>2.2.2</title>
 326
 327       <para><emphasis>Note:</emphasis> this might the last release of the
 328       library that will support PHP 4. Future releases (if any) should target
 329       php 5.0 as minimum supported version.</para>
 330
 331       <para><itemizedlist>
 332           <listitem>
 333             <para>fixed: encoding of utf-8 characters outside of the BMP
 334             plane</para>
 335           </listitem>
 336
 337           <listitem>
 338             <para>fixed: character set declarations surrounded by double
 339             quotes were not recognized in http headers</para>
 340           </listitem>
 341
 342           <listitem>
 343             <para>fixed: be more tolerant in detection of charset in http
 344             headers</para>
 345           </listitem>
 346
 347           <listitem>
 348             <para>fixed: fix detection of zlib.output_compression</para>
 349           </listitem>
 350
 351           <listitem>
 352             <para>fixed: use feof() to test if socket connections are to be
 353             closed instead of the number of bytes read (rare bug when
 354             communicating with some servers)</para>
 355           </listitem>
 356
 357           <listitem>
 358             <para>fixed: format floating point values using the correct
 359             decimal separator even when php locale is set to one that uses
 360             comma</para>
 361           </listitem>
 362
 363           <listitem>
 364             <para>fixed: improve robustness of the debugger when parsing weird
 365             results from non-compliant servers</para>
 366           </listitem>
 367
 368           <listitem>
 369             <para>php warning when receiving 'false' in a bool value</para>
 370           </listitem>
 371
 372           <listitem>
 373             <para>improved: allow the add_to_map server method to add docs for
 374             single params too</para>
 375           </listitem>
 376
 377           <listitem>
 378             <para>improved: added the possibility to wrap for exposure as
 379             xmlrpc methods plain php class methods, object methods and even
 380             whole classes</para>
 381           </listitem>
 382         </itemizedlist></para>
 383     </sect1>
 384
 385     <sect1>
 386       <title>2.2.1</title>
 387
 388       <itemizedlist>
 389         <listitem>
 390           <para>fixed: work aroung bug in php 5.2.2 which broke support of
 391           HTTP_RAW_POST_DATA</para>
 392         </listitem>
 393
 394         <listitem>
 395           <para>fixed: is_dir parameter of setCaCertificate() method is
 396           reversed</para>
 397         </listitem>
 398
 399         <listitem>
 400           <para>fixed: a php warning in xmlrpc_client creator method</para>
 401         </listitem>
 402
 403         <listitem>
 404           <para>fixed: parsing of '1e+1' as valid float</para>
 405         </listitem>
 406
 407         <listitem>
 408           <para>fixed: allow errorlevel 3 to work when prev. error handler was
 409           a static method</para>
 410         </listitem>
 411
 412         <listitem>
 413           <para>fixed: usage of client::setcookie() for multiple cookies in
 414           non-ssl mode</para>
 415         </listitem>
 416
 417         <listitem>
 418           <para>improved: support for CP1252 charset is not part or the
 419           library but almost possible</para>
 420         </listitem>
 421
 422         <listitem>
 423           <para>improved: more info when curl is enabled and debug mode is
 424           on</para>
 425         </listitem>
 426       </itemizedlist>
 427     </sect1>
 428
 429     <sect1>
 430       <title>2.2</title>
 431
 432       <itemizedlist>
 433         <listitem>
 434           <para>fixed: debugger errors on php installs with magic_quotes_gpc
 435           on</para>
 436         </listitem>
 437
 438         <listitem>
 439           <para>fixed: support for https connections via proxy</para>
 440         </listitem>
 441
 442         <listitem>
 443           <para>fixed: wrap_xmlrpc_method() generated code failed to properly
 444           encode php objects</para>
 445         </listitem>
 446
 447         <listitem>
 448           <para>improved: slightly faster encoding of data which is internally
 449           UTF-8</para>
 450         </listitem>
 451
 452         <listitem>
 453           <para>improved: debugger always generates a 'null' id for jsonrpc if
 454           user omits it</para>
 455         </listitem>
 456
 457         <listitem>
 458           <para>new: debugger can take advantage of a graphical value builder
 459           (it has to be downloaded separately, as part of jsxmlrpc package.
 460           See Appendix D for more details)</para>
 461         </listitem>
 462
 463         <listitem>
 464           <para>new: support for the &lt;NIL/&gt; xmlrpc extension. see below
 465           for more details</para>
 466         </listitem>
 467
 468         <listitem>
 469           <para>new: server support for the system.getCapabilities xmlrpc
 470           extension</para>
 471         </listitem>
 472
 473         <listitem>
 474           <para>new: <function><link
 475           linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>
 476           accepts two new options: debug and return_on_fault</para>
 477         </listitem>
 478       </itemizedlist>
 479     </sect1>
 480
 481     <sect1>
 482       <title>2.1</title>
 483
 484       <para><itemizedlist>
 485           <listitem>
 486             <para>The <function>wrap_php_function</function> and
 487             <function>wrap_xmlrpc_method</function> functions have been moved
 488             out of the base library file <filename>xmlrpc.inc</filename> into
 489             a file of their own: <filename>xmlrpc_wrappers.inc</filename>. You
 490             will have to include() / require() it in your scripts if you have
 491             been using those functions. For increased security, the automatic
 492             rebuilding of php object instances out of received xmlrpc structs
 493             in <function>wrap_xmlrpc_method()</function> has been disabled
 494             (but it can be optionally re-enabled). Both
 495             <function>wrap_php_function()</function> and
 496             <function>wrap_xmlrpc_method()</function> functions accept many
 497             more options to fine tune their behaviour, including one to return
 498             the php code to be saved and later used as standalone php
 499             script</para>
 500           </listitem>
 501
 502           <listitem>
 503             <para>The constructor of xmlrpcval() values has seen some internal
 504             changes, and it will not throw a php warning anymore when invoked
 505             using an unknown xmlrpc type: the error will only be written to
 506             php error log. Also <code>new xmlrpcval('true', 'boolean')</code>
 507             is not supported anymore</para>
 508           </listitem>
 509
 510           <listitem>
 511             <para>The new function
 512             <function>php_xmlrpc_decode_xml()</function> will take the xml
 513             representation of either an xmlrpc request, response or single
 514             value and return the corresponding php-xmlrpc object
 515             instance</para>
 516           </listitem>
 517
 518           <listitem>
 519             <para>A new function <function>wrap_xmlrpc_server()</function>has
 520             been added, to wrap all (or some) of the methods exposed by a
 521             remote xmlrpc server into a php class</para>
 522           </listitem>
 523
 524           <listitem>
 525             <para>A new file has been added:
 526             <filename>verify_compat.php</filename>, to help users diagnose the
 527             level of compliance of their php installation with the
 528             library</para>
 529           </listitem>
 530
 531           <listitem>
 532             <para>Restored compatibility with php 4.0.5 (for those poor souls
 533             still stuck on it)</para>
 534           </listitem>
 535
 536           <listitem>
 537             <para>Method <methodname>xmlrpc_server-&gt;service()</methodname>
 538             now returns a value: either the response payload or xmlrpcresp
 539             object instance</para>
 540           </listitem>
 541
 542           <listitem>
 543             <para>Method
 544             <methodname>xmlrpc_server-&gt;add_to_map()</methodname> now
 545             accepts xmlrpc methods with no param definitions</para>
 546           </listitem>
 547
 548           <listitem>
 549             <para>Documentation for single parameters of exposed methods can
 550             be added to the dispatch map (and turned into html docs in
 551             conjunction with a future release of the 'extras' package)</para>
 552           </listitem>
 553
 554           <listitem>
 555             <para>Full response payload is saved into xmlrpcresp object for
 556             further debugging</para>
 557           </listitem>
 558
 559           <listitem>
 560             <para>The debugger can now generate code that wraps a remote
 561             method into a php function (works for jsonrpc, too); it also has
 562             better support for being activated via a single GET call (e.g. for
 563             integration into other tools)</para>
 564           </listitem>
 565
 566           <listitem>
 567             <para>Stricter parsing of incoming xmlrpc messages: two more
 568             invalid cases are now detected (double <literal>data</literal>
 569             element inside <literal>array</literal> and
 570             <literal>struct</literal>/<literal>array</literal> after scalar
 571             inside <literal>value</literal> element)</para>
 572           </listitem>
 573
 574           <listitem>
 575             <para>More logging of errors in a lot of situations</para>
 576           </listitem>
 577
 578           <listitem>
 579             <para>Javadoc documentation of lib files (almost) complete</para>
 580           </listitem>
 581
 582           <listitem>
 583             <para>Many performance tweaks and code cleanups, plus the usual
 584             crop of bugs fixed (see NEWS file for complete list of
 585             bugs)</para>
 586           </listitem>
 587
 588           <listitem>
 589             <para>Lib internals have been modified to provide better support
 590             for grafting extra functionality on top of it. Stay tuned for
 591             future releases of the EXTRAS package (or go read Appendix
 592             B)...</para>
 593           </listitem>
 594         </itemizedlist></para>
 595     </sect1>
 596
 597     <sect1>
 598       <title>2.0 final</title>
 599
 600       <para><itemizedlist>
 601           <listitem>
 602             <para>Added to the client class the possibility to use Digest and
 603             NTLM authentication methods (when using the CURL library) for
 604             connecting to servers and NTLM for connecting to proxies</para>
 605           </listitem>
 606
 607           <listitem>
 608             <para>Added to the client class the possibility to specify
 609             alternate certificate files/directories for authenticating the
 610             peer with when using HTTPS communication</para>
 611           </listitem>
 612
 613           <listitem>
 614             <para>Reviewed all examples and added a new demo file, containing
 615             a proxy to forward xmlrpc requests to other servers (useful e.g.
 616             for ajax coding)</para>
 617           </listitem>
 618
 619           <listitem>
 620             <para>The debugger has been upgraded to reflect the new client
 621             capabilities</para>
 622           </listitem>
 623
 624           <listitem>
 625             <para>All known bugs have been squashed, and the lib is more
 626             tolerant than ever of commonly-found mistakes</para>
 627           </listitem>
 628         </itemizedlist></para>
 629     </sect1>
 630
 631     <sect1>
 632       <title>2.0 Release candidate 3</title>
 633
 634       <para><itemizedlist>
 635           <listitem>
 636             <para>Added to server class the property
 637             <property>functions_parameters_type</property>, that allows the
 638             server to register plain php functions as xmlrpc methods (i.e.
 639             functions that do not take an xmlrpcmsg object as unique
 640             param)</para>
 641           </listitem>
 642
 643           <listitem>
 644             <para>let server and client objects serialize calls using a
 645             specified character set encoding for the produced xml instead of
 646             US-ASCII (ISO-8859-1 and UTF-8 supported)</para>
 647           </listitem>
 648
 649           <listitem>
 650             <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid
 651             input</para>
 652           </listitem>
 653
 654           <listitem>
 655             <para>'class::method' syntax is now accepted in the server
 656             dispatch map</para>
 657           </listitem>
 658
 659           <listitem>
 660             <para><function>xmlrpc_clent::SetDebug()</function> accepts
 661             integer values instead of a boolean value, with debugging level 2
 662             adding to the information printed to screen the complete client
 663             request</para>
 664           </listitem>
 665         </itemizedlist></para>
 666     </sect1>
 667
 668     <sect1>
 669       <title>2.0 Release candidate 2</title>
 670
 671       <para><itemizedlist>
 672           <listitem>
 673             <para>Added a new property of the client object:
 674             <code>xmlrpc_client-&gt;return_type</code>, indicating whether
 675             calls to the send() method will return xmlrpcresp objects whose
 676             value() is an xmlrpcval object, a php value (automatically
 677             decoded) or the raw xml received from the server.</para>
 678           </listitem>
 679
 680           <listitem>
 681             <para>Added in the extras dir. two new library file:
 682             <filename>jsonrpc.inc</filename> and
 683             <filename>jsonrpcs.inc</filename> containing new classes that
 684             implement support for the json-rpc protocol (alpha quality
 685             code)</para>
 686           </listitem>
 687
 688           <listitem>
 689             <para>Added a new client method: <code>setKey($key,
 690             $keypass)</code> to be used in HTTPS connections</para>
 691           </listitem>
 692
 693           <listitem>
 694             <para>Added a new file containing some benchmarks in the testsuite
 695             directory</para>
 696           </listitem>
 697         </itemizedlist></para>
 698     </sect1>
 699
 700     <sect1>
 701       <title>2.0 Release candidate 1</title>
 702
 703       <itemizedlist>
 704         <listitem>
 705           <para>Support for HTTP proxies (new method:
 706           <code>xmlrpc_client::setProxy()</code>)</para>
 707         </listitem>
 708
 709         <listitem>
 710           <para>Support HTTP compression of both requests and responses.
 711           Clients can specify what kind of compression they accept for
 712           responses between deflate/gzip/any, and whether to compress the
 713           requests. Servers by default compress responses to clients that
 714           explicitly declare support for compression (new methods:
 715           <code>xmlrpc_client::setAcceptedCompression()</code>,
 716           <code>xmlrpc_client::setRequestCompression()</code>). Note that the
 717           ZLIB php extension needs to be enabled in PHP to support
 718           compression.</para>
 719         </listitem>
 720
 721         <listitem>
 722           <para>Implement HTTP 1.1 connections, but only if CURL is enabled
 723           (added an extra parameter to
 724           <code>xmlrpc_client::xmlrpc_client</code> to set the desired HTTP
 725           protocol at creation time and a new supported value for the last
 726           parameter of <code>xmlrpc_client::send</code>, which now can be
 727           safely omitted if it has been specified at creation time)</para>
 728
 729           <para>With PHP versions greater than 4.3.8 keep-alives are enabled
 730           by default for HTTP 1.1 connections. This should yield faster
 731           execution times when making multiple calls in sequence to the same
 732           xml-rpc server from a single client.</para>
 733         </listitem>
 734
 735         <listitem>
 736           <para>Introduce support for cookies. Cookies to be sent to the
 737           server with a request can be set using
 738           <code>xmlrpc_client::setCookie()</code>, while cookies received from
 739           the server are found in <code>xmlrpcresp::cookies()</code>. It is
 740           left to the user to check for validity of received cookies and
 741           decide whether they apply to successive calls or not.</para>
 742         </listitem>
 743
 744         <listitem>
 745           <para>Better support for detecting different character set encodings
 746           of xml-rpc requests and responses: both client and server objects
 747           will correctly detect the charset encoding of received xml, and use
 748           an appropriate xml parser.</para>
 749
 750           <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>
 751         </listitem>
 752
 753         <listitem>
 754           <para>Added one new xmlrpcmsg constructor syntax, allowing usage of
 755           a single string with the complete URL of the target server</para>
 756         </listitem>
 757
 758         <listitem>
 759           <para>Convert xml-rpc boolean values into native php values instead
 760           of 0 and 1</para>
 761         </listitem>
 762
 763         <listitem>
 764           <para>Force the <code>php_xmlrpc_encode</code> function to properly
 765           encode numerically indexed php arrays into xml-rpc arrays
 766           (numerically indexed php arrays always start with a key of 0 and
 767           increment keys by values of 1)</para>
 768         </listitem>
 769
 770         <listitem>
 771           <para>Prevent the <code>php_xmlrpc_encode</code> function from
 772           further re-encoding any objects of class <code>xmlrpcval</code> that
 773           are passed to it. This allows to call the function with arguments
 774           consisting of mixed php values / xmlrpcval objects.</para>
 775         </listitem>
 776
 777         <listitem>
 778           <para>Allow a server to NOT respond to system.* method calls
 779           (setting the <code>$server-&gt;allow_system_funcs</code>
 780           property).</para>
 781         </listitem>
 782
 783         <listitem>
 784           <para>Implement a new xmlrpcval method to determine if a value of
 785           type struct has a member of a given name without having to loop
 786           trough all members: <code>xmlrpcval::structMemExists()</code></para>
 787         </listitem>
 788
 789         <listitem>
 790           <para>Expand methods <code>xmlrpcval::addArray</code>,
 791           <code>addScalar</code> and <code>addStruct</code> allowing extra php
 792           values to be added to xmlrpcval objects already formed.</para>
 793         </listitem>
 794
 795         <listitem>
 796           <para>Let the <code>xmlrpc_client::send</code> method accept an XML
 797           string for sending instead of an xmlrpcmsg object, to facilitate
 798           debugging and integration with the php native xmlrpc
 799           extension</para>
 800         </listitem>
 801
 802         <listitem>
 803           <para>Extend the <code>php_xmlrpc_encode</code> and
 804           <code>php_xmlrpc_decode</code> functions to allow serialization and
 805           rebuilding of PHP objects. To successfully rebuild a serialized
 806           object, the object class must be defined in the deserializing end of
 807           the transfer. Note that object members of type resource will be
 808           deserialized as NULL values.</para>
 809
 810           <para>Note that his has been implemented adding a "php_class"
 811           attribute to xml representation of xmlrpcval of STRUCT type, which,
 812           strictly speaking, breaks the xml-rpc spec. Other xmlrpc
 813           implementations are supposed to ignore such an attribute (unless
 814           they implement a brain-dead custom xml parser...), so it should be
 815           safe enabling it in heterogeneous environments. The activation of
 816           this feature is done by usage of an option passed as second
 817           parameter to both <code>php_xmlrpc_encode</code> and
 818           <code>php_xmlrpc_decode</code>.</para>
 819         </listitem>
 820
 821         <listitem>
 822           <para>Extend the <code>php_xmlrpc_encode</code> function to allow
 823           automatic serialization of iso8601-conforming php strings as
 824           datetime.iso8601 xmlrpcvals, by usage of an optional
 825           parameter</para>
 826         </listitem>
 827
 828         <listitem>
 829           <para>Added an automatic stub code generator for converting xmlrpc
 830           methods to php functions and vice-versa.</para>
 831
 832           <para>This is done via two new functions:
 833           <code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,
 834           and has many caveats, with php being a typeless language and
 835           all...</para>
 836
 837           <para>With PHP versions lesser than 5.0.3 wrapping of php functions
 838           into xmlrpc methods is not supported yet.</para>
 839         </listitem>
 840
 841         <listitem>
 842           <para>Allow object methods to be used in server dispatch map</para>
 843         </listitem>
 844
 845         <listitem>
 846           <para>Added a complete debugger solution, in the
 847           <filename>debugger</filename> folder</para>
 848         </listitem>
 849
 850         <listitem>
 851           <para>Added configurable server-side debug messages, controlled by
 852           the new method <code>xmlrpc_server::SetDebug()</code>. At level 0,
 853           no debug messages are sent to the client; level 1 is the same as the
 854           old behaviour; at level 2 a lot more info is echoed back to the
 855           client, regarding the received call; at level 3 all warnings raised
 856           during server processing are trapped (this prevents breaking the xml
 857           to be echoed back to the client) and added to the debug info sent
 858           back to the client</para>
 859         </listitem>
 860
 861         <listitem>
 862           <para>New XML parsing code, yields smaller memory footprint and
 863           faster execution times, not to mention complete elimination of the
 864           dreaded <filename>eval()</filename> construct, so prone to code
 865           injection exploits</para>
 866         </listitem>
 867
 868         <listitem>
 869           <para>Rewritten most of the error messages, making text more
 870           explicative</para>
 871         </listitem>
 872       </itemizedlist>
 873     </sect1>
 874   </chapter>
 875
 876   <chapter id="requirements">
 877     <title>System Requirements</title>
 878
 879     <para>The library has been designed with goals of scalability and backward
 880     compatibility. As such, it supports a wide range of PHP installs. Note
 881     that not all features of the lib are available in every
 882     configuration.</para>
 883
 884     <para>The <emphasis>minimum supported</emphasis> PHP version is
 885     5.1.</para>
 886
 887     <para>If you wish to use SSL or HTTP 1.1 to communicate with remote
 888     servers, you need the "curl" extension compiled into your PHP
 889     installation.</para>
 890
 891     <para>The "xmlrpc" native extension is not required to be compiled into
 892     your PHP installation, but if it is, there will be no interference with
 893     the operation of this library.</para>
 894   </chapter>
 895
 896   <chapter id="manifest">
 897     <title>Files in the distribution</title>
 898
 899     <glosslist>
 900       <glossentry>
 901         <glossterm>lib/xmlrpc.inc</glossterm>
 902
 903         <glossdef>
 904           <para>the XML-RPC classes. <function>include()</function> this in
 905           your PHP files to use the classes.</para>
 906         </glossdef>
 907       </glossentry>
 908
 909       <glossentry>
 910         <glossterm>lib/xmlrpcs.inc</glossterm>
 911
 912         <glossdef>
 913           <para>the XML-RPC server class. <function>include()</function> this
 914           in addition to xmlrpc.inc to get server functionality</para>
 915         </glossdef>
 916       </glossentry>
 917
 918       <glossentry>
 919         <glossterm>lib/xmlrpc_wrappers.inc</glossterm>
 920
 921         <glossdef>
 922           <para>helper functions to "automagically" convert plain php
 923           functions to xmlrpc services and vice versa</para>
 924         </glossdef>
 925       </glossentry>
 926
 927       <glossentry>
 928         <glossterm>demo/server/proxy.php</glossterm>
 929
 930         <glossdef>
 931           <para>a sample server implementing xmlrpc proxy
 932           functionality.</para>
 933         </glossdef>
 934       </glossentry>
 935
 936       <glossentry>
 937         <glossterm>demo/server/server.php</glossterm>
 938
 939         <glossdef>
 940           <para>a sample server hosting various demo functions, as well as a
 941           full suite of functions used for interoperability testing. It is
 942           used by testsuite.php (see below) for unit testing the library, and
 943           is not to be copied literally into your production servers</para>
 944         </glossdef>
 945       </glossentry>
 946
 947       <glossentry>
 948         <glossterm>demo/client/client.php, demo/client/agesort.php,
 949         demo/client/which.php</glossterm>
 950
 951         <glossdef>
 952           <para>client code to exercise some of the functions in server.php,
 953           including the <function>interopEchoTests.whichToolkit</function>
 954           method.</para>
 955         </glossdef>
 956       </glossentry>
 957
 958       <glossentry>
 959         <glossterm>demo/client/wrap.php</glossterm>
 960
 961         <glossdef>
 962           <para>client code to illustrate 'wrapping' of remote methods into
 963           php functions.</para>
 964         </glossdef>
 965       </glossentry>
 966
 967       <glossentry>
 968         <glossterm>demo/client/introspect.php</glossterm>
 969
 970         <glossdef>
 971           <para>client code to illustrate usage of introspection capabilities
 972           offered by server.php.</para>
 973         </glossdef>
 974       </glossentry>
 975
 976       <glossentry>
 977         <glossterm>demo/client/mail.php</glossterm>
 978
 979         <glossdef>
 980           <para>client code to illustrate usage of an xmlrpc-to-email gateway
 981           using Dave Winer's XML-RPC server at userland.com.</para>
 982         </glossdef>
 983       </glossentry>
 984
 985       <glossentry>
 986         <glossterm>demo/client/zopetest.php</glossterm>
 987
 988         <glossdef>
 989           <para>example client code that queries an xmlrpc server built in
 990           Zope.</para>
 991         </glossdef>
 992       </glossentry>
 993
 994       <glossentry>
 995         <glossterm>demo/vardemo.php</glossterm>
 996
 997         <glossdef>
 998           <para>examples of how to construct xmlrpcval types</para>
 999         </glossdef>
1000       </glossentry>
1001
1002       <glossentry>
1003         <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>
1004
1005         <glossdef>
1006           <para>XML-RPC responses captured in a file for testing purposes (you
1007           can use these to test the
1008           <function>xmlrpcmsg-&gt;parseResponse()</function> method).</para>
1009         </glossdef>
1010       </glossentry>
1011
1012       <glossentry>
1013         <glossterm>demo/server/discuss.php,
1014         demo/client/comment.php</glossterm>
1015
1016         <glossdef>
1017           <para>Software used in the PHP chapter of <xref
1018           linkend="jellyfish" /> to provide a comment server and allow the
1019           attachment of comments to stories from Meerkat's data store.</para>
1020         </glossdef>
1021       </glossentry>
1022
1023       <glossentry>
1024         <glossterm>test/testsuite.php, test/parse_args.php</glossterm>
1025
1026         <glossdef>
1027           <para>A unit test suite for this software package. If you do
1028           development on this software, please consider submitting tests for
1029           this suite.</para>
1030         </glossdef>
1031       </glossentry>
1032
1033       <glossentry>
1034         <glossterm>test/benchmark.php</glossterm>
1035
1036         <glossdef>
1037           <para>A (very limited) benchmarking suite for this software package.
1038           If you do development on this software, please consider submitting
1039           benchmarks for this suite.</para>
1040         </glossdef>
1041       </glossentry>
1042
1043       <glossentry>
1044         <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>
1045
1046         <glossdef>
1047           <para>An (incomplete) version PEAR's unit test framework for PHP.
1048           The complete package can be found at <ulink
1049           url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>
1050         </glossdef>
1051       </glossentry>
1052
1053       <glossentry>
1054         <glossterm>test/verify_compat.php</glossterm>
1055
1056         <glossdef>
1057           <para>Script designed to help the user to verify the level of
1058           compatibility of the library with the current php install</para>
1059         </glossdef>
1060       </glossentry>
1061
1062       <glossentry>
1063         <glossterm>extras/test.pl, extras/test.py</glossterm>
1064
1065         <glossdef>
1066           <para>Perl and Python programs to exercise server.php to test that
1067           some of the methods work.</para>
1068         </glossdef>
1069       </glossentry>
1070
1071       <glossentry>
1072         <glossterm>extras/workspace.testPhpServer.fttb</glossterm>
1073
1074         <glossdef>
1075           <para>Frontier scripts to exercise the demo server. Thanks to Dave
1076           Winer for permission to include these. See <ulink
1077           url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's
1078           announcement of these.</ulink></para>
1079         </glossdef>
1080       </glossentry>
1081
1082       <glossentry>
1083         <glossterm>extras/rsakey.pem</glossterm>
1084
1085         <glossdef>
1086           <para>A test certificate key for the SSL support, which can be used
1087           to generate dummy certificates. It has the passphrase "test."</para>
1088         </glossdef>
1089       </glossentry>
1090     </glosslist>
1091   </chapter>
1092
1093   <chapter id="bugs">
1094     <title>Known bugs and limitations</title>
1095
1096     <para>This started out as a bare framework. Many "nice" bits haven't been
1097     put in yet. Specifically, very little type validation or coercion has been
1098     put in. PHP being a loosely-typed language, this is going to have to be
1099     done explicitly (in other words: you can call a lot of library functions
1100     passing them arguments of the wrong type and receive an error message only
1101     much further down the code, where it will be difficult to
1102     understand).</para>
1103
1104     <para>dateTime.iso8601 is supported opaquely. It can't be done natively as
1105     the XML-RPC specification explicitly forbids passing of timezone
1106     specifiers in ISO8601 format dates. You can, however, use the <xref
1107     linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions
1108     to do the encoding and decoding for you.</para>
1109
1110     <para>Very little HTTP response checking is performed (e.g. HTTP redirects
1111     are not followed and the Content-Length HTTP header, mandated by the
1112     xml-rpc spec, is not validated); cookie support still involves quite a bit
1113     of coding on the part of the user.</para>
1114
1115     <para>If a specific character set encoding other than US-ASCII, ISO-8859-1
1116     or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
1117     or response messages then it will be ignored for the moment, and the
1118     content will be parsed as if it had been encoded using the charset defined
1119     by <xref linkend="xmlrpc-defencoding" /></para>
1120
1121     <para>Support for receiving from servers version 1 cookies (i.e.
1122     conforming to RFC 2965) is quite incomplete, and might cause unforeseen
1123     errors.</para>
1124   </chapter>
1125
1126   <chapter id="support">
1127     <title>Support</title>
1128
1129     <sect1>
1130       <title>Online Support</title>
1131
1132       <para>XML-RPC for PHP is offered "as-is" without any warranty or
1133       commitment to support. However, informal advice and help is available
1134       via the XML-RPC for PHP website and mailing list and from
1135       XML-RPC.com.</para>
1136
1137       <itemizedlist>
1138         <listitem>
1139           <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
1140           on <ulink
1141           url="https://github.com/gggeek/phpxmlrpc">github.com/gggeek/phpxmlrpc</ulink>.
1142           Bugs, feature requests and patches can be posted to the <ulink
1143           url="https://github.com/gggeek/phpxmlrpc/issues">project's
1144           website</ulink>.</para>
1145         </listitem>
1146
1147         <listitem>
1148           <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is
1149           run by the author. More details <ulink
1150           url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be
1151           found here</ulink>.</para>
1152         </listitem>
1153
1154         <listitem>
1155           <para>For more general XML-RPC questions, there is a Yahoo! Groups
1156           <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing
1157           list</ulink>.</para>
1158         </listitem>
1159
1160         <listitem>
1161           <para>The <ulink
1162           url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion
1163           group is a useful place to get help with using XML-RPC. This group
1164           is also gatewayed into the Yahoo! Groups mailing list.</para>
1165         </listitem>
1166       </itemizedlist>
1167     </sect1>
1168
1169     <sect1 id="jellyfish" xreflabel="The Jellyfish Book">
1170       <title>The Jellyfish Book</title>
1171
1172       <para><graphic align="right" depth="190" fileref="progxmlrpc.s.gif"
1173       format="GIF" width="145" />Together with Simon St.Laurent and Joe
1174       Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and
1175       Associates on XML-RPC. It features a rather fetching jellyfish on the
1176       cover.</para>
1177
1178       <para>Complete details of the book are <ulink
1179       url="http://www.oreilly.com/catalog/progxmlrpc/">available from
1180       O'Reilly's web site.</ulink></para>
1181
1182       <para>Edd is responsible for the chapter on PHP, which includes a worked
1183       example of creating a forum server, and hooking it up the O'Reilly's
1184       <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in
1185       order to allow commenting on news stories from around the Web.</para>
1186
1187       <para>If you've benefited from the effort that has been put into writing
1188       this software, then please consider buying the book!</para>
1189     </sect1>
1190   </chapter>
1191
1192   <chapter id="apidocs">
1193     <title>Class documentation</title>
1194
1195     <sect1 id="xmlrpcval" xreflabel="xmlrpcval">
1196       <title>xmlrpcval</title>
1197
1198       <para>This is where a lot of the hard work gets done. This class enables
1199       the creation and encapsulation of values for XML-RPC.</para>
1200
1201       <para>Ensure you've read the XML-RPC spec at <ulink
1202       url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>
1203       before reading on as it will make things clearer.</para>
1204
1205       <para>The <classname>xmlrpcval</classname> class can store arbitrarily
1206       complicated values using the following types: <literal>i4 int boolean
1207       string double dateTime.iso8601 base64 array struct</literal>
1208       <literal>null</literal>. You should refer to the <ulink
1209       url="http://www.xmlrpc.com/spec">spec</ulink> for more information on
1210       what each of these types mean.</para>
1211
1212       <sect2>
1213         <title>Notes on types</title>
1214
1215         <sect3>
1216           <title>int</title>
1217
1218           <para>The type <classname>i4</classname> is accepted as a synonym
1219           for <classname>int</classname> when creating xmlrpcval objects. The
1220           xml parsing code will always convert <classname>i4</classname> to
1221           <classname>int</classname>: <classname>int</classname> is regarded
1222           by this implementation as the canonical name for this type.</para>
1223         </sect3>
1224
1225         <sect3>
1226           <title>base64</title>
1227
1228           <para>Base 64 encoding is performed transparently to the caller when
1229           using this type. Decoding is also transparent. Therefore you ought
1230           to consider it as a "binary" data type, for use when you want to
1231           pass data that is not 7-bit clean.</para>
1232         </sect3>
1233
1234         <sect3>
1235           <title>boolean</title>
1236
1237           <para>The php values <literal>true</literal> and
1238           <literal>1</literal> map to <literal>true</literal>. All other
1239           values (including the empty string) are converted to
1240           <literal>false</literal>.</para>
1241         </sect3>
1242
1243         <sect3>
1244           <title>string</title>
1245
1246           <para>Characters &lt;, &gt;, ', ", &amp;, are encoded using their
1247           entity reference as &amp;lt; &amp;gt; &amp;apos; &amp;quot; and
1248           &amp;amp; All other characters outside of the ASCII range are
1249           encoded using their character reference representation (e.g.
1250           &amp;#200 for é). The XML-RPC spec recommends only encoding
1251           <literal>&lt; &amp;</literal> but this implementation goes further,
1252           for reasons explained by <ulink
1253           url="http://www.w3.org/TR/REC-xml#syntax">the XML 1.0
1254           recommendation</ulink>. In particular, using character reference
1255           representation has the advantage of producing XML that is valid
1256           independently of the charset encoding assumed.</para>
1257         </sect3>
1258
1259         <sect3>
1260           <title>null</title>
1261
1262           <para>There is no support for encoding <literal>null</literal>
1263           values in the XML-RPC spec, but at least a couple of extensions (and
1264           many toolkits) do support it. Before using <literal>null</literal>
1265           values in your messages, make sure that the responding party accepts
1266           them, and uses the same encoding convention (see ...).</para>
1267         </sect3>
1268       </sect2>
1269
1270       <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
1271         <title>Creation</title>
1272
1273         <para>The constructor is the normal way to create an
1274         <classname>xmlrpcval</classname>. The constructor can take these
1275         forms:</para>
1276
1277         <funcsynopsis>
1278           <funcprototype>
1279             <funcdef><type>xmlrpcval</type>new
1280             <function>xmlrpcval</function></funcdef>
1281
1282             <void />
1283           </funcprototype>
1284
1285           <funcprototype>
1286             <funcdef><type>xmlrpcval</type>new
1287             <function>xmlrpcval</function></funcdef>
1288
1289             <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
1290           </funcprototype>
1291
1292           <funcprototype>
1293             <funcdef><type>xmlrpcval</type>new
1294             <function>xmlrpcval</function></funcdef>
1295
1296             <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
1297
1298             <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
1299           </funcprototype>
1300
1301           <funcprototype>
1302             <funcdef><type>xmlrpcval</type>new
1303             <function>xmlrpcval</function></funcdef>
1304
1305             <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
1306
1307             <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>
1308           </funcprototype>
1309         </funcsynopsis>
1310
1311         <para>The first constructor creates an empty value, which must be
1312         altered using the methods <function>addScalar</function>,
1313         <function>addArray</function> or <function>addStruct</function> before
1314         it can be used.</para>
1315
1316         <para>The second constructor creates a simple string value.</para>
1317
1318         <para>The third constructor is used to create a scalar value. The
1319         second parameter must be a name of an XML-RPC type. Valid types are:
1320         "<literal>int</literal>", "<literal>boolean</literal>",
1321         "<literal>string</literal>", "<literal>double</literal>",
1322         "<literal>dateTime.iso8601</literal>", "<literal>base64</literal>" or
1323         "null".</para>
1324
1325         <para>Examples:</para>
1326
1327         <programlisting language="php">
1328 $myInt = new xmlrpcvalue(1267, "int");
1329 $myString = new xmlrpcvalue("Hello, World!", "string");
1330 $myBool = new xmlrpcvalue(1, "boolean");
1331 $myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
1332 </programlisting>
1333
1334         <para>The fourth constructor form can be used to compose complex
1335         XML-RPC values. The first argument is either a simple array in the
1336         case of an XML-RPC <classname>array</classname> or an associative
1337         array in the case of a <classname>struct</classname>. The elements of
1338         the array <emphasis>must be <classname>xmlrpcval</classname> objects
1339         themselves</emphasis>.</para>
1340
1341         <para>The second parameter must be either "<literal>array</literal>"
1342         or "<literal>struct</literal>".</para>
1343
1344         <para>Examples:</para>
1345
1346         <programlisting language="php">
1347 $myArray = new xmlrpcval(
1348   array(
1349     new xmlrpcval("Tom"),
1350     new xmlrpcval("Dick"),
1351     new xmlrpcval("Harry")
1352   ),
1353   "array");
1354
1355 // recursive struct
1356 $myStruct = new xmlrpcval(
1357   array(
1358     "name" =&gt; new xmlrpcval("Tom", "string"),
1359     "age" =&gt; new xmlrpcval(34, "int"),
1360     "address" =&gt; new xmlrpcval(
1361       array(
1362         "street" =&gt; new xmlrpcval("Fifht Ave", "string"),
1363         "city" =&gt; new xmlrpcval("NY", "string")
1364       ),
1365       "struct")
1366   ),
1367   "struct");
1368 </programlisting>
1369
1370         <para>See the file <literal>vardemo.php</literal> in this distribution
1371         for more examples.</para>
1372       </sect2>
1373
1374       <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">
1375         <title>Methods</title>
1376
1377         <sect3>
1378           <title>addScalar</title>
1379
1380           <funcsynopsis>
1381             <funcprototype>
1382               <funcdef><type>int</type><function>addScalar</function></funcdef>
1383
1384               <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
1385             </funcprototype>
1386
1387             <funcprototype>
1388               <funcdef><type>int</type><function>addScalar</function></funcdef>
1389
1390               <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
1391
1392               <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
1393             </funcprototype>
1394           </funcsynopsis>
1395
1396           <para>If <parameter>$val</parameter> is an empty
1397           <classname>xmlrpcval</classname> this method makes it a scalar
1398           value, and sets that value.</para>
1399
1400           <para>If <parameter>$val</parameter> is already a scalar value, then
1401           no more scalars can be added and <literal>0</literal> is
1402           returned.</para>
1403
1404           <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
1405           the php value <parameter>$scalarval</parameter> is added as its last
1406           element.</para>
1407
1408           <para>If all went OK, <literal>1</literal> is returned, otherwise
1409           <literal>0</literal>.</para>
1410         </sect3>
1411
1412         <sect3>
1413           <title>addArray</title>
1414
1415           <funcsynopsis>
1416             <funcprototype>
1417               <funcdef><type>int</type><function>addArray</function></funcdef>
1418
1419               <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
1420             </funcprototype>
1421           </funcsynopsis>
1422
1423           <para>The argument is a simple (numerically indexed) array. The
1424           elements of the array <emphasis>must be
1425           <classname>xmlrpcval</classname> objects
1426           themselves</emphasis>.</para>
1427
1428           <para>Turns an empty <classname>xmlrpcval</classname> into an
1429           <classname>array</classname> with contents as specified by
1430           <parameter>$arrayVal</parameter>.</para>
1431
1432           <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
1433           the elements of <parameter>$arrayVal</parameter> are appended to the
1434           existing ones.</para>
1435
1436           <para>See the fourth constructor form for more information.</para>
1437
1438           <para>If all went OK, <literal>1</literal> is returned, otherwise
1439           <literal>0</literal>.</para>
1440         </sect3>
1441
1442         <sect3>
1443           <title>addStruct</title>
1444
1445           <funcsynopsis>
1446             <funcprototype>
1447               <funcdef><type>int</type><function>addStruct</function></funcdef>
1448
1449               <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>
1450             </funcprototype>
1451           </funcsynopsis>
1452
1453           <para>The argument is an associative array. The elements of the
1454           array <emphasis>must be <classname>xmlrpcval</classname> objects
1455           themselves</emphasis>.</para>
1456
1457           <para>Turns an empty <classname>xmlrpcval</classname> into a
1458           <classname>struct</classname> with contents as specified by
1459           <parameter>$assocArrayVal</parameter>.</para>
1460
1461           <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,
1462           the elements of <parameter>$arrayVal</parameter> are merged with the
1463           existing ones.</para>
1464
1465           <para>See the fourth constructor form for more information.</para>
1466
1467           <para>If all went OK, <literal>1</literal> is returned, otherwise
1468           <literal>0</literal>.</para>
1469         </sect3>
1470
1471         <sect3>
1472           <title>kindOf</title>
1473
1474           <funcsynopsis>
1475             <funcprototype>
1476               <funcdef><type>string</type><function>kindOf</function></funcdef>
1477
1478               <void />
1479             </funcprototype>
1480           </funcsynopsis>
1481
1482           <para>Returns a string containing "struct", "array" or "scalar"
1483           describing the base type of the value. If it returns "undef" it
1484           means that the value hasn't been initialised.</para>
1485         </sect3>
1486
1487         <sect3>
1488           <title>serialize</title>
1489
1490           <funcsynopsis>
1491             <funcprototype>
1492               <funcdef><type>string</type><function>serialize</function></funcdef>
1493
1494               <void />
1495             </funcprototype>
1496           </funcsynopsis>
1497
1498           <para>Returns a string containing the XML-RPC representation of this
1499           value.</para>
1500         </sect3>
1501
1502         <sect3>
1503           <title>scalarVal</title>
1504
1505           <funcsynopsis>
1506             <funcprototype>
1507               <funcdef><type>mixed</type><function>scalarVal</function></funcdef>
1508
1509               <void />
1510             </funcprototype>
1511           </funcsynopsis>
1512
1513           <para>If <function>$val-&gt;kindOf() == "scalar"</function>, this
1514           method returns the actual PHP-language value of the scalar (base 64
1515           decoding is automatically handled here).</para>
1516         </sect3>
1517
1518         <sect3>
1519           <title>scalarTyp</title>
1520
1521           <funcsynopsis>
1522             <funcprototype>
1523               <funcdef><type>string</type><function>scalarTyp</function></funcdef>
1524
1525               <void />
1526             </funcprototype>
1527           </funcsynopsis>
1528
1529           <para>If <function>$val-&gt;kindOf() == "scalar"</function>, this
1530           method returns a string denoting the type of the scalar. As
1531           mentioned before, <literal>i4</literal> is always coerced to
1532           <literal>int</literal>.</para>
1533         </sect3>
1534
1535         <sect3>
1536           <title>arrayMem</title>
1537
1538           <funcsynopsis>
1539             <funcprototype>
1540               <funcdef><type>xmlrpcval</type><function>arrayMem</function></funcdef>
1541
1542               <paramdef><type>int</type><parameter>$n</parameter></paramdef>
1543             </funcprototype>
1544           </funcsynopsis>
1545
1546           <para>If <function>$val-&gt;kindOf() == "array"</function>, returns
1547           the <parameter>$n</parameter>th element in the array represented by
1548           the value <parameter>$val</parameter>. The value returned is an
1549           <classname>xmlrpcval</classname> object.</para>
1550
1551           <para><programlisting language="php">
1552 // iterating over values of an array object
1553 for ($i = 0; $i &lt; $val-&gt;arraySize(); $i++)
1554 {
1555   $v = $val-&gt;arrayMem($i);
1556   echo "Element $i of the array is of type ".$v-&gt;kindOf();
1557 }
1558 </programlisting></para>
1559         </sect3>
1560
1561         <sect3>
1562           <title>arraySize</title>
1563
1564           <funcsynopsis>
1565             <funcprototype>
1566               <funcdef><type>int</type><function>arraySize</function></funcdef>
1567
1568               <void />
1569             </funcprototype>
1570           </funcsynopsis>
1571
1572           <para>If <parameter>$val</parameter> is an
1573           <classname>array</classname>, returns the number of elements in that
1574           array.</para>
1575         </sect3>
1576
1577         <sect3>
1578           <title>structMem</title>
1579
1580           <funcsynopsis>
1581             <funcprototype>
1582               <funcdef><type>xmlrpcval</type><function>structMem</function></funcdef>
1583
1584               <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
1585             </funcprototype>
1586           </funcsynopsis>
1587
1588           <para>If <function>$val-&gt;kindOf() == "struct"</function>, returns
1589           the element called <parameter>$memberName</parameter> from the
1590           struct represented by the value <parameter>$val</parameter>. The
1591           value returned is an <classname>xmlrpcval</classname> object.</para>
1592         </sect3>
1593
1594         <sect3>
1595           <title>structEach</title>
1596
1597           <funcsynopsis>
1598             <funcprototype>
1599               <funcdef><type>array</type><function>structEach</function></funcdef>
1600
1601               <void />
1602             </funcprototype>
1603           </funcsynopsis>
1604
1605           <para>Returns the next (key, value) pair from the struct, when
1606           <parameter>$val</parameter> is a struct.
1607           <parameter>$value</parameter> is an xmlrpcval itself. See also <xref
1608           linkend="structreset" />.</para>
1609
1610           <para><programlisting language="php">
1611 // iterating over all values of a struct object
1612 $val-&gt;structreset();
1613 while (list($key, $v) = $val-&gt;structEach())
1614 {
1615   echo "Element $key of the struct is of type ".$v-&gt;kindOf();
1616 }
1617 </programlisting></para>
1618         </sect3>
1619
1620         <sect3 id="structreset" xreflabel="structreset()">
1621           <title>structReset</title>
1622
1623           <funcsynopsis>
1624             <funcprototype>
1625               <funcdef><type>void</type><function>structReset</function></funcdef>
1626
1627               <void />
1628             </funcprototype>
1629           </funcsynopsis>
1630
1631           <para>Resets the internal pointer for
1632           <function>structEach()</function> to the beginning of the struct,
1633           where <parameter>$val</parameter> is a struct.</para>
1634         </sect3>
1635
1636         <sect3 id="structmemexists" xreflabel="structmemexists()">
1637           <title>structMemExists</title>
1638
1639           <funcsynopsis>
1640             <funcprototype>
1641               <funcdef><type>bool</type><function>structMemExsists</function></funcdef>
1642
1643               <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
1644             </funcprototype>
1645           </funcsynopsis>
1646
1647           <para>Returns <constant>TRUE</constant> or
1648           <constant>FALSE</constant> depending on whether a member of the
1649           given name exists in the struct.</para>
1650         </sect3>
1651       </sect2>
1652     </sect1>
1653
1654     <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">
1655       <title>xmlrpcmsg</title>
1656
1657       <para>This class provides a representation for a request to an XML-RPC
1658       server. A client sends an <classname>xmlrpcmsg</classname> to a server,
1659       and receives back an <classname>xmlrpcresp</classname> (see <xref
1660       linkend="xmlrpc-client-send" />).</para>
1661
1662       <sect2>
1663         <title>Creation</title>
1664
1665         <para>The constructor takes the following forms:</para>
1666
1667         <funcsynopsis>
1668           <funcprototype>
1669             <funcdef><type>xmlrpcmsg</type>new
1670             <function>xmlrpcmsg</function></funcdef>
1671
1672             <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>
1673
1674             <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>
1675           </funcprototype>
1676         </funcsynopsis>
1677
1678         <para>Where <parameter>methodName</parameter> is a string indicating
1679         the name of the method you wish to invoke, and
1680         <parameter>parameterArray</parameter> is a simple php
1681         <classname>Array</classname> of <classname>xmlrpcval</classname>
1682         objects. Here's an example message to the <emphasis>US state
1683         name</emphasis> server:</para>
1684
1685         <programlisting language="php">
1686 $msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
1687 </programlisting>
1688
1689         <para>This example requests the name of state number 23. For more
1690         information on <classname>xmlrpcval</classname> objects, see <xref
1691         linkend="xmlrpcval" />.</para>
1692
1693         <para>Note that the <parameter>parameterArray</parameter> parameter is
1694         optional and can be omitted for methods that take no input parameters
1695         or if you plan to add parameters one by one.</para>
1696       </sect2>
1697
1698       <sect2>
1699         <title>Methods</title>
1700
1701         <sect3>
1702           <title>addParam</title>
1703
1704           <funcsynopsis>
1705             <funcprototype>
1706               <funcdef><type>bool</type><function>addParam</function></funcdef>
1707
1708               <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>
1709             </funcprototype>
1710           </funcsynopsis>
1711
1712           <para>Adds the <classname>xmlrpcval</classname>
1713           <parameter>xmlrpcVal</parameter> to the parameter list for this
1714           method call. Returns TRUE or FALSE on error.</para>
1715         </sect3>
1716
1717         <sect3>
1718           <title>getNumParams</title>
1719
1720           <funcsynopsis>
1721             <funcprototype>
1722               <funcdef><type>int</type><function>getNumParams</function></funcdef>
1723
1724               <void />
1725             </funcprototype>
1726           </funcsynopsis>
1727
1728           <para>Returns the number of parameters attached to this
1729           message.</para>
1730         </sect3>
1731
1732         <sect3>
1733           <title>getParam</title>
1734
1735           <funcsynopsis>
1736             <funcprototype>
1737               <funcdef><type>xmlrpcval</type><function>getParam</function></funcdef>
1738
1739               <paramdef><type>int</type><parameter>$n</parameter></paramdef>
1740             </funcprototype>
1741           </funcsynopsis>
1742
1743           <para>Gets the <parameter>n</parameter>th parameter in the message
1744           (with the index zero-based). Use this method in server
1745           implementations to retrieve the values sent by the client.</para>
1746         </sect3>
1747
1748         <sect3>
1749           <title>method</title>
1750
1751           <funcsynopsis>
1752             <funcprototype>
1753               <funcdef><type>string</type><function>method</function></funcdef>
1754
1755               <void />
1756             </funcprototype>
1757
1758             <funcprototype>
1759               <funcdef><type>string</type><function>method</function></funcdef>
1760
1761               <paramdef><type>string</type><parameter>$methName</parameter></paramdef>
1762             </funcprototype>
1763           </funcsynopsis>
1764
1765           <para>Gets or sets the method contained in the XML-RPC
1766           message.</para>
1767         </sect3>
1768
1769         <sect3>
1770           <title>parseResponse</title>
1771
1772           <funcsynopsis>
1773             <funcprototype>
1774               <funcdef><type>xmlrpcresp</type><function>parseResponse</function></funcdef>
1775
1776               <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>
1777             </funcprototype>
1778           </funcsynopsis>
1779
1780           <para>Given an incoming XML-RPC server response contained in the
1781           string <parameter>$xmlString</parameter>, this method constructs an
1782           <classname>xmlrpcresp</classname> response object and returns it,
1783           setting error codes as appropriate (see <xref
1784           linkend="xmlrpc-client-send" />).</para>
1785
1786           <para>This method processes any HTTP/MIME headers it finds.</para>
1787         </sect3>
1788
1789         <sect3>
1790           <title>parseResponseFile</title>
1791
1792           <funcsynopsis>
1793             <funcprototype>
1794               <funcdef><type>xmlrpcresp</type><function>parseResponseFile</function></funcdef>
1795
1796               <paramdef><type>file handle
1797               resource</type><parameter>$fileHandle</parameter></paramdef>
1798             </funcprototype>
1799           </funcsynopsis>
1800
1801           <para>Given an incoming XML-RPC server response on the open file
1802           handle <parameter>fileHandle</parameter>, this method reads all the
1803           data it finds and passes it to
1804           <function>parseResponse.</function></para>
1805
1806           <para>This method is useful to construct responses from pre-prepared
1807           files (see files <literal>demo1.txt, demo2.txt, demo3.txt</literal>
1808           in this distribution). It processes any HTTP headers it finds, and
1809           does not close the file handle.</para>
1810         </sect3>
1811
1812         <sect3>
1813           <title>serialize</title>
1814
1815           <funcsynopsis>
1816             <funcprototype>
1817               <funcdef><type>string
1818               </type><function>serialize</function></funcdef>
1819
1820               <void />
1821             </funcprototype>
1822           </funcsynopsis>
1823
1824           <para>Returns the an XML string representing the XML-RPC
1825           message.</para>
1826         </sect3>
1827       </sect2>
1828     </sect1>
1829
1830     <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">
1831       <title>xmlrpc_client</title>
1832
1833       <para>This is the basic class used to represent a client of an XML-RPC
1834       server.</para>
1835
1836       <sect2>
1837         <title>Creation</title>
1838
1839         <para>The constructor accepts one of two possible syntaxes:</para>
1840
1841         <funcsynopsis>
1842           <funcprototype>
1843             <funcdef><type>xmlrpc_client</type>new
1844             <function>xmlrpc_client</function></funcdef>
1845
1846             <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>
1847           </funcprototype>
1848
1849           <funcprototype>
1850             <funcdef><type>xmlrpc_client</type>new
1851             <function>xmlrpc_client</function></funcdef>
1852
1853             <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>
1854
1855             <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>
1856
1857             <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>
1858
1859             <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>
1860           </funcprototype>
1861         </funcsynopsis>
1862
1863         <para>Here are a couple of usage examples of the first form:</para>
1864
1865         <programlisting language="php">
1866 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
1867 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");
1868 </programlisting>
1869
1870         <para>The second syntax does not allow to express a username and
1871         password to be used for basic HTTP authorization as in the second
1872         example above, but instead it allows to choose whether xmlrpc calls
1873         will be made using the HTTP 1.0 or 1.1 protocol.</para>
1874
1875         <para>Here's another example client set up to query Userland's XML-RPC
1876         server at <emphasis>betty.userland.com</emphasis>:</para>
1877
1878         <programlisting language="php">
1879 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
1880 </programlisting>
1881
1882         <para>The <parameter>server_port</parameter> parameter is optional,
1883         and if omitted will default to 80 when using HTTP and 443 when using
1884         HTTPS (see the <xref linkend="xmlrpc-client-send" /> method
1885         below).</para>
1886
1887         <para>The <parameter>transport</parameter> parameter is optional, and
1888         if omitted will default to 'http'. Allowed values are either
1889         '<symbol>http'</symbol>, '<symbol>https</symbol>' or
1890         '<symbol>http11'</symbol>. Its value can be overridden with every call
1891         to the <methodname>send</methodname> method. See the
1892         <methodname>send</methodname> method below for more details about the
1893         meaning of the different values.</para>
1894       </sect2>
1895
1896       <sect2>
1897         <title>Methods</title>
1898
1899         <para>This class supports the following methods.</para>
1900
1901         <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client-&gt;send">
1902           <title>send</title>
1903
1904           <para>This method takes the forms:</para>
1905
1906           <funcsynopsis>
1907             <funcprototype>
1908               <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
1909
1910               <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpc_message</parameter></paramdef>
1911
1912               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1913
1914               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1915             </funcprototype>
1916
1917             <funcprototype>
1918               <funcdef><type>array</type><function>send</function></funcdef>
1919
1920               <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>
1921
1922               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1923
1924               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1925             </funcprototype>
1926
1927             <funcprototype>
1928               <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
1929
1930               <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>
1931
1932               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1933
1934               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1935             </funcprototype>
1936           </funcsynopsis>
1937
1938           <para>Where <parameter>xmlrpc_message</parameter> is an instance of
1939           <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),
1940           and <parameter>response</parameter> is an instance of
1941           <classname>xmlrpcresp</classname> (see <xref
1942           linkend="xmlrpcresp" />).</para>
1943
1944           <para><parameter>If xmlrpc_messages</parameter> is an array of
1945           message instances, <code>responses</code> will be an array of
1946           response instances. The client will try to make use of a single
1947           <code>system.multicall</code> xml-rpc method call to forward to the
1948           server all the messages in a single HTTP round trip, unless
1949           <code>$client-&gt;no_multicall</code> has been previously set to
1950           <code>TRUE</code> (see the multicall method below), in which case
1951           many consecutive xmlrpc requests will be sent.</para>
1952
1953           <para>The third syntax allows to build by hand (or any other means)
1954           a complete xmlrpc request message, and send it to the server.
1955           <parameter>xml_payload</parameter> should be a string containing the
1956           complete xml representation of the request. It is e.g. useful when,
1957           for maximal speed of execution, the request is serialized into a
1958           string using the native php xmlrpc functions (see <ulink
1959           url="http://www.php.net/xmlrpc">the php manual on
1960           xmlrpc</ulink>).</para>
1961
1962           <para>The <parameter>timeout</parameter> is optional, and will be
1963           set to <literal>0</literal> (wait for platform-specific predefined
1964           timeout) if omitted. This timeout value is passed to
1965           <function>fsockopen()</function>. It is also used for detecting
1966           server timeouts during communication (i.e. if the server does not
1967           send anything to the client for <parameter>timeout</parameter>
1968           seconds, the connection will be closed).</para>
1969
1970           <para>The <parameter>transport</parameter> parameter is optional,
1971           and if omitted will default to the transport set using instance
1972           creator or 'http' if omitted. The only other valid values are
1973           'https', which will use an SSL HTTP connection to connect to the
1974           remote server, and 'http11'. Note that your PHP must have the "curl"
1975           extension compiled in order to use both these features. Note that
1976           when using SSL you should normally set your port number to 443,
1977           unless the SSL server you are contacting runs at any other
1978           port.</para>
1979
1980           <warning>
1981             <para>PHP 4.0.6 has a bug which prevents SSL working.</para>
1982           </warning>
1983
1984           <para>In addition to low-level errors, the XML-RPC server you were
1985           querying may return an error in the
1986           <classname>xmlrpcresp</classname> object. See <xref
1987           linkend="xmlrpcresp" /> for details of how to handle these
1988           errors.</para>
1989         </sect3>
1990
1991         <sect3 id="multicall" xreflabel="xmlrpc_client-&gt;multicall">
1992           <title>multiCall</title>
1993
1994           <para>This method takes the form:</para>
1995
1996           <funcsynopsis>
1997             <funcprototype>
1998               <funcdef><type>array</type><function>multiCall</function></funcdef>
1999
2000               <paramdef><type>array</type><parameter>$messages</parameter></paramdef>
2001
2002               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
2003
2004               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
2005
2006               <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>
2007             </funcprototype>
2008           </funcsynopsis>
2009
2010           <para>This method is used to boxcar many method calls in a single
2011           xml-rpc request. It will try first to make use of the
2012           <code>system.multicall</code> xml-rpc method call, and fall back to
2013           executing many separate requests if the server returns any
2014           error.</para>
2015
2016           <para><parameter>msgs</parameter> is an array of
2017           <classname>xmlrpcmsg</classname> objects (see <xref
2018           linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an
2019           array of <classname>xmlrpcresp</classname> objects (see <xref
2020           linkend="xmlrpcresp" />).</para>
2021
2022           <para>The <parameter>timeout</parameter> and
2023           <parameter>transport</parameter> parameters are optional, and behave
2024           as in the <methodname>send</methodname> method above.</para>
2025
2026           <para>The <parameter>fallback</parameter> parameter is optional, and
2027           defaults to <constant>TRUE</constant>. When set to
2028           <constant>FALSE</constant> it will prevent the client to try using
2029           many single method calls in case of failure of the first multicall
2030           request. It should be set only when the server is known to support
2031           the multicall extension.</para>
2032         </sect3>
2033
2034         <sect3>
2035           <title>setAcceptedCompression</title>
2036
2037           <funcsynopsis>
2038             <funcprototype>
2039               <funcdef><type>void</type><function>setAcceptedCompression</function></funcdef>
2040
2041               <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
2042             </funcprototype>
2043           </funcsynopsis>
2044
2045           <para>This method defines whether the client will accept compressed
2046           xml payload forming the bodies of the xmlrpc responses received from
2047           servers. Note that enabling reception of compressed responses merely
2048           adds some standard http headers to xmlrpc requests. It is up to the
2049           xmlrpc server to return compressed responses when receiving such
2050           requests. Allowed values for
2051           <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
2052           'any' or null (with any meaning either gzip or deflate).</para>
2053
2054           <para>This requires the "zlib" extension to be enabled in your php
2055           install. If it is, by default <classname>xmlrpc_client</classname>
2056           instances will enable reception of compressed content.</para>
2057         </sect3>
2058
2059         <sect3>
2060           <title>setCaCertificate</title>
2061
2062           <funcsynopsis>
2063             <funcprototype>
2064               <funcdef><type>void</type><function>setCaCertificate</function></funcdef>
2065
2066               <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
2067
2068               <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>
2069             </funcprototype>
2070           </funcsynopsis>
2071
2072           <para>This method sets an optional certificate to be used in
2073           SSL-enabled communication to validate a remote server with (when the
2074           <parameter>server_method</parameter> is set to 'https' in the
2075           client's construction or in the send method and
2076           <methodname>SetSSLVerifypeer</methodname> has been set to
2077           <constant>TRUE</constant>).</para>
2078
2079           <para>The <parameter>certificate</parameter> parameter must be the
2080           filename of a PEM formatted certificate, or a directory containing
2081           multiple certificate files. The <parameter>is_dir</parameter>
2082           parameter defaults to <constant>FALSE</constant>, set it to
2083           <constant>TRUE</constant> to specify that
2084           <parameter>certificate</parameter> indicates a directory instead of
2085           a single file.</para>
2086
2087           <para>This requires the "curl" extension to be compiled into your
2088           installation of PHP. For more details see the man page for the
2089           <function>curl_setopt</function> function.</para>
2090         </sect3>
2091
2092         <sect3>
2093           <title>setCertificate</title>
2094
2095           <funcsynopsis>
2096             <funcprototype>
2097               <funcdef><type>void</type><function>setCertificate</function></funcdef>
2098
2099               <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
2100
2101               <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>
2102             </funcprototype>
2103           </funcsynopsis>
2104
2105           <para>This method sets the optional certificate and passphrase used
2106           in SSL-enabled communication with a remote server (when the
2107           <parameter>server_method</parameter> is set to 'https' in the
2108           client's construction or in the send method).</para>
2109
2110           <para>The <parameter>certificate</parameter> parameter must be the
2111           filename of a PEM formatted certificate. The
2112           <parameter>passphrase</parameter> parameter must contain the
2113           password required to use the certificate.</para>
2114
2115           <para>This requires the "curl" extension to be compiled into your
2116           installation of PHP. For more details see the man page for the
2117           <function>curl_setopt</function> function.</para>
2118
2119           <para>Note: to retrieve information about the client certificate on
2120           the server side, you will need to look into the environment
2121           variables which are set up by the webserver. Different webservers
2122           will typically set up different variables.</para>
2123         </sect3>
2124
2125         <sect3>
2126           <title>setCookie</title>
2127
2128           <funcsynopsis>
2129             <funcprototype>
2130               <funcdef><type>void</type><function>setCookie</function></funcdef>
2131
2132               <paramdef><type>string</type><parameter>$name</parameter></paramdef>
2133
2134               <paramdef><type>string</type><parameter>$value</parameter></paramdef>
2135
2136               <paramdef><type>string</type><parameter>$path</parameter></paramdef>
2137
2138               <paramdef><type>string</type><parameter>$domain</parameter></paramdef>
2139
2140               <paramdef><type>int</type><parameter>$port</parameter></paramdef>
2141             </funcprototype>
2142           </funcsynopsis>
2143
2144           <para>This method sets a cookie that will be sent to the xmlrpc
2145           server along with every further request (useful e.g. for keeping
2146           session info outside of the xml-rpc payload).</para>
2147
2148           <para><parameter>$value</parameter> is optional, and defaults to
2149           null.</para>
2150
2151           <para><parameter>$path, $domain and $port</parameter> are optional,
2152           and will be omitted from the cookie header if unspecified. Note that
2153           setting any of these values will turn the cookie into a 'version 1'
2154           cookie, that might not be fully supported by the server (see RFC2965
2155           for more details).</para>
2156         </sect3>
2157
2158         <sect3>
2159           <title>setCredentials</title>
2160
2161           <funcsynopsis>
2162             <funcprototype>
2163               <funcdef><type>void</type><function>setCredentials</function></funcdef>
2164
2165               <paramdef><type>string</type><parameter>$username</parameter></paramdef>
2166
2167               <paramdef><type>string</type><parameter>$password</parameter></paramdef>
2168
2169               <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
2170             </funcprototype>
2171           </funcsynopsis>
2172
2173           <para>This method sets the username and password for authorizing the
2174           client to a server. With the default (HTTP) transport, this
2175           information is used for HTTP Basic authorization. Note that username
2176           and password can also be set using the class constructor. With HTTP
2177           1.1 and HTTPS transport, NTLM and Digest authentication protocols
2178           are also supported. To enable them use the constants
2179           <constant>CURLAUTH_DIGEST</constant> and
2180           <constant>CURLAUTH_NTLM</constant> as values for the authtype
2181           parameter.</para>
2182         </sect3>
2183
2184         <sect3>
2185           <title>setCurlOptions</title>
2186
2187           <para><funcsynopsis>
2188               <funcprototype>
2189                 <funcdef><type>void</type><function>setCurlOptions</function></funcdef>
2190
2191                 <paramdef><type>array</type><parameter>$options</parameter></paramdef>
2192               </funcprototype>
2193             </funcsynopsis>This method allows to directly set any desired
2194           option to manipulate the usage of the cURL client (when in cURL
2195           mode). It can be used eg. to explicitly bind to an outgoing ip
2196           address when the server is multihomed</para>
2197         </sect3>
2198
2199         <sect3>
2200           <title>setDebug</title>
2201
2202           <funcsynopsis>
2203             <funcprototype>
2204               <funcdef><type>void</type><function>setDebug</function></funcdef>
2205
2206               <paramdef><type>int</type><parameter>$debugLvl</parameter></paramdef>
2207             </funcprototype>
2208           </funcsynopsis>
2209
2210           <para><parameter>debugLvl</parameter> is either <literal>0,
2211           1</literal> or 2 depending on whether you require the client to
2212           print debugging information to the browser. The default is not to
2213           output this information (0).</para>
2214
2215           <para>The debugging information at level 1includes the raw data
2216           returned from the XML-RPC server it was querying (including bot HTTP
2217           headers and the full XML payload), and the PHP value the client
2218           attempts to create to represent the value returned by the server. At
2219           level2, the complete payload of the xmlrpc request is also printed,
2220           before being sent t the server.</para>
2221
2222           <para>This option can be very useful when debugging servers as it
2223           allows you to see exactly what the client sends and the server
2224           returns.</para>
2225         </sect3>
2226
2227         <sect3>
2228           <title>setKey</title>
2229
2230           <funcsynopsis>
2231             <funcprototype>
2232               <funcdef><type>void</type><function>setKey</function></funcdef>
2233
2234               <paramdef><type>int</type><parameter>$key</parameter></paramdef>
2235
2236               <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>
2237             </funcprototype>
2238           </funcsynopsis>
2239
2240           <para>This method sets the optional certificate key and passphrase
2241           used in SSL-enabled communication with a remote server (when the
2242           <parameter>transport</parameter> is set to 'https' in the client's
2243           construction or in the send method).</para>
2244
2245           <para>This requires the "curl" extension to be compiled into your
2246           installation of PHP. For more details see the man page for the
2247           <function>curl_setopt</function> function.</para>
2248         </sect3>
2249
2250         <sect3>
2251           <title>setProxy</title>
2252
2253           <funcsynopsis>
2254             <funcprototype>
2255               <funcdef><type>void</type><function>setProxy</function></funcdef>
2256
2257               <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>
2258
2259               <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>
2260
2261               <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>
2262
2263               <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>
2264
2265               <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
2266             </funcprototype>
2267           </funcsynopsis>
2268
2269           <para>This method enables calling servers via an HTTP proxy. The
2270           <parameter>proxyusername</parameter>,<parameter>
2271           proxypassword</parameter> and <parameter>authtype</parameter>
2272           parameters are optional. <parameter>Authtype</parameter> defaults to
2273           <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);
2274           the only other valid value is the constant
2275           <constant>CURLAUTH_NTLM</constant>, and has effect only when the
2276           client uses the HTTP 1.1 protocol.</para>
2277
2278           <para>NB: CURL versions before 7.11.10 cannot use a proxy to
2279           communicate with https servers.</para>
2280         </sect3>
2281
2282         <sect3>
2283           <title>setRequestCompression</title>
2284
2285           <funcsynopsis>
2286             <funcprototype>
2287               <funcdef><type>void</type><function>setRequestCompression</function></funcdef>
2288
2289               <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
2290             </funcprototype>
2291           </funcsynopsis>
2292
2293           <para>This method defines whether the xml payload forming the
2294           request body will be sent to the server in compressed format, as per
2295           the HTTP specification. This is particularly useful for large
2296           request parameters and over slow network connections. Allowed values
2297           for <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
2298           'any' or null (with any meaning either gzip or deflate). Note that
2299           there is no automatic fallback mechanism in place for errors due to
2300           servers not supporting receiving compressed request bodies, so make
2301           sure that the particular server you are querying does accept
2302           compressed requests before turning it on.</para>
2303
2304           <para>This requires the "zlib" extension to be enabled in your php
2305           install.</para>
2306         </sect3>
2307
2308         <sect3>
2309           <title>setSSLVerifyHost</title>
2310
2311           <funcsynopsis>
2312             <funcprototype>
2313               <funcdef><type>void</type><function>setSSLVerifyHost</function></funcdef>
2314
2315               <paramdef><type>int</type><parameter>$i</parameter></paramdef>
2316             </funcprototype>
2317           </funcsynopsis>
2318
2319           <para>This method defines whether connections made to XML-RPC
2320           backends via HTTPS should verify the remote host's SSL certificate's
2321           common name (CN). By default, only the existence of a CN is checked.
2322           <parameter><parameter>$i</parameter></parameter> should be an
2323           integer value; 0 to not check the CN at all, 1 to merely check for
2324           its existence, and 2 to check that the CN on the certificate matches
2325           the hostname that is being connected to.</para>
2326         </sect3>
2327
2328         <sect3>
2329           <title>setSSLVerifyPeer</title>
2330
2331           <funcsynopsis>
2332             <funcprototype>
2333               <funcdef><type>void</type><function>setSSLVerifyPeer</function></funcdef>
2334
2335               <paramdef><type>bool</type><parameter>$i</parameter></paramdef>
2336             </funcprototype>
2337           </funcsynopsis>
2338
2339           <para>This method defines whether connections made to XML-RPC
2340           backends via HTTPS should verify the remote host's SSL certificate,
2341           and cause the connection to fail if the cert verification fails.
2342           <parameter><parameter>$i</parameter></parameter> should be a boolean
2343           value. Default value: <constant>TRUE</constant>. To specify custom
2344           SSL certificates to validate the server with, use the
2345           <methodname>setCaCertificate</methodname> method.</para>
2346         </sect3>
2347
2348         <sect3>
2349           <title>setUserAgent</title>
2350
2351           <para><funcsynopsis>
2352               <funcprototype>
2353                 <funcdef><type>void</type><function>Useragent</function></funcdef>
2354
2355                 <paramdef><type>string</type><parameter>$useragent</parameter></paramdef>
2356               </funcprototype>
2357             </funcsynopsis>This method sets a custom user-agent that will be
2358           used by the client in the http headers sent with the request. The
2359           default value is built using the library name and version
2360           constants.</para>
2361         </sect3>
2362       </sect2>
2363
2364       <sect2>
2365         <title>Variables</title>
2366
2367         <para>NB: direct manipulation of these variables is only recommended
2368         for advanced users.</para>
2369
2370         <sect3>
2371           <title>no_multicall</title>
2372
2373           <para>This member variable determines whether the multicall() method
2374           will try to take advantage of the system.multicall xmlrpc method to
2375           dispatch to the server an array of requests in a single http
2376           roundtrip or simply execute many consecutive http calls. Defaults to
2377           FALSE, but it will be enabled automatically on the first failure of
2378           execution of system.multicall.</para>
2379         </sect3>
2380
2381         <sect3>
2382           <title>request_charset_encoding</title>
2383
2384           <para>This is the charset encoding that will be used for serializing
2385           request sent by the client.</para>
2386
2387           <para>If defaults to NULL, which means using US-ASCII and encoding
2388           all characters outside of the ASCII range using their xml character
2389           entity representation (this has the benefit that line end characters
2390           will not be mangled in the transfer, a CR-LF will be preserved as
2391           well as a singe LF).</para>
2392
2393           <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>
2394         </sect3>
2395
2396         <sect3 id="return-type" xreflabel="return_type">
2397           <title>return_type</title>
2398
2399           <para>This member variable determines whether the value returned
2400           inside an xmlrpcresp object as results of calls to the send() and
2401           multicall() methods will be an xmlrpcval object, a plain php value
2402           or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
2403           'phpvals' and 'xml'. To allow the user to differentiate between a
2404           correct and a faulty response, fault responses will be returned as
2405           xmlrpcresp objects in any case. Note that the 'phpvals' setting will
2406           yield faster execution times, but some of the information from the
2407           original response will be lost. It will be e.g. impossible to tell
2408           whether a particular php string value was sent by the server as an
2409           xmlrpc string or base64 value.</para>
2410
2411           <para>Example usage:</para>
2412
2413           <programlisting language="php">
2414 $client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
2415 $client-&gt;return_type = 'phpvals';
2416 $message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
2417 $resp = $client-&gt;send($message);
2418 if ($resp-&gt;faultCode()) echo 'KO. Error: '.$resp-&gt;faultString(); else echo 'OK: got '.$resp-&gt;value();
2419 </programlisting>
2420
2421           <para>For more details about usage of the 'xml' value, see Appendix
2422           A.</para>
2423         </sect3>
2424       </sect2>
2425     </sect1>
2426
2427     <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">
2428       <title>xmlrpcresp</title>
2429
2430       <para>This class is used to contain responses to XML-RPC requests. A
2431       server method handler will construct an
2432       <classname>xmlrpcresp</classname> and pass it as a return value. This
2433       same value will be returned by the result of an invocation of the
2434       <function>send</function> method of the
2435       <classname>xmlrpc_client</classname> class.</para>
2436
2437       <sect2>
2438         <title>Creation</title>
2439
2440         <funcsynopsis>
2441           <funcprototype>
2442             <funcdef><type>xmlrpcresp</type>new
2443             <function>xmlrpcresp</function></funcdef>
2444
2445             <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>
2446           </funcprototype>
2447
2448           <funcprototype>
2449             <funcdef><type>xmlrpcresp</type>new
2450             <function>xmlrpcresp</function></funcdef>
2451
2452             <paramdef><parameter>0</parameter></paramdef>
2453
2454             <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>
2455
2456             <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>
2457           </funcprototype>
2458         </funcsynopsis>
2459
2460         <para>The first syntax is used when execution has happened without
2461         difficulty: <parameter>$xmlrpcval</parameter> is an
2462         <classname>xmlrpcval</classname> value with the result of the method
2463         execution contained in it. Alternatively it can be a string containing
2464         the xml serialization of the single xml-rpc value result of method
2465         execution.</para>
2466
2467         <para>The second type of constructor is used in case of failure.
2468         <parameter>errcode</parameter> and <parameter>err_string</parameter>
2469         are used to provide indication of what has gone wrong. See <xref
2470         linkend="xmlrpc-server" /> for more information on passing error
2471         codes.</para>
2472       </sect2>
2473
2474       <sect2>
2475         <title>Methods</title>
2476
2477         <sect3>
2478           <title>faultCode</title>
2479
2480           <funcsynopsis>
2481             <funcprototype>
2482               <funcdef><type>int</type><function>faultCode</function></funcdef>
2483
2484               <void />
2485             </funcprototype>
2486           </funcsynopsis>
2487
2488           <para>Returns the integer fault code return from the XML-RPC
2489           response. A zero value indicates success, any other value indicates
2490           a failure response.</para>
2491         </sect3>
2492
2493         <sect3>
2494           <title>faultString</title>
2495
2496           <funcsynopsis>
2497             <funcprototype>
2498               <funcdef><type>string</type><function>faultString</function></funcdef>
2499
2500               <void />
2501             </funcprototype>
2502           </funcsynopsis>
2503
2504           <para>Returns the human readable explanation of the fault indicated
2505           by <function>$resp-&gt;faultCode</function>().</para>
2506         </sect3>
2507
2508         <sect3>
2509           <title>value</title>
2510
2511           <funcsynopsis>
2512             <funcprototype>
2513               <funcdef><type>xmlrpcval</type><function>value</function></funcdef>
2514
2515               <void />
2516             </funcprototype>
2517           </funcsynopsis>
2518
2519           <para>Returns an <classname>xmlrpcval</classname> object containing
2520           the return value sent by the server. If the response's
2521           <function>faultCode</function> is non-zero then the value returned
2522           by this method should not be used (it may not even be an
2523           object).</para>
2524
2525           <para>Note: if the xmlrpcresp instance in question has been created
2526           by an <classname>xmlrpc_client</classname> object whose
2527           <varname>return_type</varname> was set to 'phpvals', then a plain
2528           php value will be returned instead of an
2529           <classname>xmlrpcval</classname> object. If the
2530           <varname>return_type</varname> was set to 'xml', an xml string will
2531           be returned (see the return_type member var above for more
2532           details).</para>
2533         </sect3>
2534
2535         <sect3>
2536           <title>serialize</title>
2537
2538           <funcsynopsis>
2539             <funcprototype>
2540               <funcdef><type>string</type><function>serialize</function></funcdef>
2541
2542               <void />
2543             </funcprototype>
2544           </funcsynopsis>
2545
2546           <para>Returns an XML string representation of the response (xml
2547           prologue not included).</para>
2548         </sect3>
2549       </sect2>
2550     </sect1>
2551
2552     <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">
2553       <title>xmlrpc_server</title>
2554
2555       <para>The implementation of this class has been kept as simple to use as
2556       possible. The constructor for the server basically does all the work.
2557       Here's a minimal example:</para>
2558
2559       <programlisting language="php">
2560   function foo ($xmlrpcmsg) {
2561     ...
2562     return new xmlrpcresp($some_xmlrpc_val);
2563   }
2564
2565   class bar {
2566     function foobar($xmlrpcmsg) {
2567       ...
2568       return new xmlrpcresp($some_xmlrpc_val);
2569     }
2570   }
2571
2572   $s = new xmlrpc_server(
2573     array(
2574       "examples.myFunc1" =&gt; array("function" =&gt; "foo"),
2575       "examples.myFunc2" =&gt; array("function" =&gt; "bar::foobar"),
2576     ));
2577 </programlisting>
2578
2579       <para>This performs everything you need to do with a server. The single
2580       constructor argument is an associative array from xmlrpc method names to
2581       php function names. The incoming request is parsed and dispatched to the
2582       relevant php function, which is responsible for returning a
2583       <classname>xmlrpcresp</classname> object, that will be serialized back
2584       to the caller.</para>
2585
2586       <sect2>
2587         <title>Method handler functions</title>
2588
2589         <para>Both php functions and class methods can be registered as xmlrpc
2590         method handlers.</para>
2591
2592         <para>The synopsis of a method handler function is:</para>
2593
2594         <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>
2595
2596         <para>No text should be echoed 'to screen' by the handler function, or
2597         it will break the xml response sent back to the client. This applies
2598         also to error and warning messages that PHP prints to screen unless
2599         the appropriate parameters have been set in the php.in file. Another
2600         way to prevent echoing of errors inside the response and facilitate
2601         debugging is to use the server SetDebug method with debug level 3 (see
2602         ...). Exceptions thrown duting execution of handler functions are
2603         caught by default and a XML-RPC error reponse is generated instead.
2604         This behaviour can be finetuned by usage of the
2605         <varname>exception_handling</varname> member variable (see
2606         ...).</para>
2607
2608         <para>Note that if you implement a method with a name prefixed by
2609         <code>system.</code> the handler function will be invoked by the
2610         server with two parameters, the first being the server itself and the
2611         second being the <classname>xmlrpcmsg</classname> object.</para>
2612
2613         <para>The same php function can be registered as handler of multiple
2614         xmlrpc methods.</para>
2615
2616         <para>Here is a more detailed example of what the handler function
2617         <function>foo</function> may do:</para>
2618
2619         <programlisting language="php">
2620   function foo ($xmlrpcmsg) {
2621     global $xmlrpcerruser; // import user errcode base value
2622
2623     $meth = $xmlrpcmsg-&gt;method(); // retrieve method name
2624     $par = $xmlrpcmsg-&gt;getParam(0); // retrieve value of first parameter - assumes at least one param received
2625     $val = $par-&gt;scalarval(); // decode value of first parameter - assumes it is a scalar value
2626
2627     ...
2628
2629     if ($err) {
2630       // this is an error condition
2631       return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
2632         "There's a problem, Captain");
2633     } else {
2634       // this is a successful value being returned
2635       return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
2636     }
2637   }
2638 </programlisting>
2639
2640         <para>See <filename>server.php</filename> in this distribution for
2641         more examples of how to do this.</para>
2642
2643         <para>Since release 2.0RC3 there is a new, even simpler way of
2644         registering php functions with the server. See section 5.7
2645         below</para>
2646       </sect2>
2647
2648       <sect2>
2649         <title>The dispatch map</title>
2650
2651         <para>The first argument to the <function>xmlrpc_server</function>
2652         constructor is an array, called the <emphasis>dispatch map</emphasis>.
2653         In this array is the information the server needs to service the
2654         XML-RPC methods you define.</para>
2655
2656         <para>The dispatch map takes the form of an associative array of
2657         associative arrays: the outer array has one entry for each method, the
2658         key being the method name. The corresponding value is another
2659         associative array, which can have the following members:</para>
2660
2661         <itemizedlist>
2662           <listitem>
2663             <para><function><literal>function</literal></function> - this
2664             entry is mandatory. It must be either a name of a function in the
2665             global scope which services the XML-RPC method, or an array
2666             containing an instance of an object and a static method name (for
2667             static class methods the 'class::method' syntax is also
2668             supported).</para>
2669           </listitem>
2670
2671           <listitem>
2672             <para><function><literal>signature</literal></function> - this
2673             entry is an array containing the possible signatures (see <xref
2674             linkend="signatures" />) for the method. If this entry is present
2675             then the server will check that the correct number and type of
2676             parameters have been sent for this method before dispatching
2677             it.</para>
2678           </listitem>
2679
2680           <listitem>
2681             <para><function><literal>docstring</literal></function> - this
2682             entry is a string containing documentation for the method. The
2683             documentation may contain HTML markup.</para>
2684           </listitem>
2685
2686           <listitem>
2687             <para><literal>signature_docs</literal> - this entry can be used
2688             to provide documentation for the single parameters. It must match
2689             in structure the 'signature' member. By default, only the
2690             <classname>documenting_xmlrpc_server</classname> class in the
2691             extras package will take advantage of this, since the
2692             "system.methodHelp" protocol does not support documenting method
2693             parameters individually.</para>
2694           </listitem>
2695
2696           <listitem>
2697             <para><literal>parameters_type</literal> - this entry can be used
2698             when the server is working in 'xmlrpcvals' mode (see ...) to
2699             define one or more entries in the dispatch map as being functions
2700             that follow the 'phpvals' calling convention. The only useful
2701             value is currently the string <literal>phpvals</literal>.</para>
2702           </listitem>
2703         </itemizedlist>
2704
2705         <para>Look at the <filename>server.php</filename> example in the
2706         distribution to see what a dispatch map looks like.</para>
2707       </sect2>
2708
2709       <sect2 id="signatures" xreflabel="Signatures">
2710         <title>Method signatures</title>
2711
2712         <para>A signature is a description of a method's return type and its
2713         parameter types. A method may have more than one signature.</para>
2714
2715         <para>Within a server's dispatch map, each method has an array of
2716         possible signatures. Each signature is an array of types. The first
2717         entry is the return type. For instance, the method <programlisting
2718         language="php">string examples.getStateName(int)
2719 </programlisting> has the signature <programlisting language="php">array($xmlrpcString, $xmlrpcInt)
2720 </programlisting> and, assuming that it is the only possible signature for the
2721         method, it might be used like this in server creation: <programlisting
2722         language="php">
2723 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
2724
2725 $findstate_doc = 'When passed an integer between 1 and 51 returns the
2726 name of a US state, where the integer is the index of that state name
2727 in an alphabetic order.';
2728
2729 $s = new xmlrpc_server( array(
2730   "examples.getStateName" =&gt; array(
2731     "function" =&gt; "findstate",
2732     "signature" =&gt; $findstate_sig,
2733     "docstring" =&gt; $findstate_doc
2734   )));
2735 </programlisting></para>
2736
2737         <para>Note that method signatures do not allow to check nested
2738         parameters, e.g. the number, names and types of the members of a
2739         struct param cannot be validated.</para>
2740
2741         <para>If a method that you want to expose has a definite number of
2742         parameters, but each of those parameters could reasonably be of
2743         multiple types, the array of acceptable signatures will easily grow
2744         into a combinatorial explosion. To avoid such a situation, the lib
2745         defines the global var <varname>$xmlrpcValue</varname>, which can be
2746         used in method signatures as a placeholder for 'any xmlrpc
2747         type':</para>
2748
2749         <para><programlisting language="php">
2750 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
2751
2752 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
2753
2754 $s = new xmlrpc_server( array(
2755   "echoBack" =&gt; array(
2756     "function" =&gt; "echoback",
2757     "signature" =&gt; $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
2758     "docstring" =&gt; $echoback_doc
2759   )));
2760 </programlisting></para>
2761
2762         <para>Methods <methodname>system.listMethods</methodname>,
2763         <methodname>system.methodHelp</methodname>,
2764         <methodname>system.methodSignature</methodname> and
2765         <methodname>system.multicall</methodname> are already defined by the
2766         server, and should not be reimplemented (see Reserved Methods
2767         below).</para>
2768       </sect2>
2769
2770       <sect2>
2771         <title>Delaying the server response</title>
2772
2773         <para>You may want to construct the server, but for some reason not
2774         fulfill the request immediately (security verification, for instance).
2775         If you omit to pass to the constructor the dispatch map or pass it a
2776         second argument of <literal>0</literal> this will have the desired
2777         effect. You can then use the <function>service()</function> method of
2778         the server class to service the request. For example:</para>
2779
2780         <programlisting language="php">
2781 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
2782
2783 // ... some code that does other stuff here
2784
2785 $s-&gt;service();
2786 </programlisting>
2787
2788         <para>Note that the <methodname>service</methodname> method will print
2789         the complete result payload to screen and send appropriate HTTP
2790         headers back to the client, but also return the response object. This
2791         permits further manipulation of the response, possibly in combination
2792         with output buffering.</para>
2793
2794         <para>To prevent the server from sending HTTP headers back to the
2795         client, you can pass a second parameter with a value of
2796         <literal>TRUE</literal> to the <methodname>service</methodname>
2797         method. In this case, the response payload will be returned instead of
2798         the response object.</para>
2799
2800         <para>Xmlrpc requests retrieved by other means than HTTP POST bodies
2801         can also be processed. For example:</para>
2802
2803         <programlisting language="php">
2804 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
2805
2806 // ... some code that does other stuff here, including setting dispatch map into server object
2807
2808 $resp = $s-&gt;service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
2809
2810 // ... some code that does other stuff with xml response $resp here
2811 </programlisting>
2812       </sect2>
2813
2814       <sect2>
2815         <title>Modifying the server behaviour</title>
2816
2817         <para>A couple of methods / class variables are available to modify
2818         the behaviour of the server. The only way to take advantage of their
2819         existence is by usage of a delayed server response (see above)</para>
2820
2821         <sect3>
2822           <title>setDebug()</title>
2823
2824           <para>This function controls weather the server is going to echo
2825           debugging messages back to the client as comments in response body.
2826           Valid values: 0,1,2,3, with 1 being the default. At level 0, no
2827           debug info is returned to the client. At level 2, the complete
2828           client request is added to the response, as part of the xml
2829           comments. At level 3, a new PHP error handler is set when executing
2830           user functions exposed as server methods, and all non-fatal errors
2831           are trapped and added as comments into the response.</para>
2832         </sect3>
2833
2834         <sect3>
2835           <title>allow_system_funcs</title>
2836
2837           <para>Default_value: TRUE. When set to FALSE, disables support for
2838           <methodname>System.xxx</methodname> functions in the server. It
2839           might be useful e.g. if you do not wish the server to respond to
2840           requests to <methodname>System.ListMethods</methodname>.</para>
2841         </sect3>
2842
2843         <sect3>
2844           <title>compress_response</title>
2845
2846           <para>When set to TRUE, enables the server to take advantage of HTTP
2847           compression, otherwise disables it. Responses will be transparently
2848           compressed, but only when an xmlrpc-client declares its support for
2849           compression in the HTTP headers of the request.</para>
2850
2851           <para>Note that the ZLIB php extension must be installed for this to
2852           work. If it is, <varname>compress_response</varname> will default to
2853           TRUE.</para>
2854         </sect3>
2855
2856         <sect3>
2857           <title>exception_handling</title>
2858
2859           <para>This variable controls the behaviour of the server when an
2860           exception is thrown by a method handler php function. Valid values:
2861           0,1,2, with 0 being the default. At level 0, the server catches the
2862           exception and return an 'internal error' xmlrpc response; at 1 it
2863           catches the exceptions and return an xmlrpc response with the error
2864           code and error message corresponding to the exception that was
2865           thron; at 2 = the exception is floated to the upper layers in the
2866           code</para>
2867         </sect3>
2868
2869         <sect3>
2870           <title>response_charset_encoding</title>
2871
2872           <para>Charset encoding to be used for response (only affects string
2873           values).</para>
2874
2875           <para>If it can, the server will convert the generated response from
2876           internal_encoding to the intended one.</para>
2877
2878           <para>Valid values are: a supported xml encoding (only UTF-8 and
2879           ISO-8859-1 at present, unless mbstring is enabled), null (leave
2880           charset unspecified in response and convert output stream to
2881           US_ASCII), 'default' (use xmlrpc library default as specified in
2882           xmlrpc.inc, convert output stream if needed), or 'auto' (use
2883           client-specified charset encoding or same as request if request
2884           headers do not specify it (unless request is US-ASCII: then use
2885           library default anyway).</para>
2886         </sect3>
2887       </sect2>
2888
2889       <sect2>
2890         <title>Fault reporting</title>
2891
2892         <para>Fault codes for your servers should start at the value indicated
2893         by the global <literal>$xmlrpcerruser</literal> + 1.</para>
2894
2895         <para>Standard errors returned by the server include:</para>
2896
2897         <variablelist>
2898           <varlistentry>
2899             <term><literal>1</literal> <phrase>Unknown method</phrase></term>
2900
2901             <listitem>
2902               <para>Returned if the server was asked to dispatch a method it
2903               didn't know about</para>
2904             </listitem>
2905           </varlistentry>
2906
2907           <varlistentry>
2908             <term><literal>2</literal> <phrase>Invalid return
2909             payload</phrase></term>
2910
2911             <listitem>
2912               <para>This error is actually generated by the client, not
2913               server, code, but signifies that a server returned something it
2914               couldn't understand. A more detailed error report is sometimes
2915               added onto the end of the phrase above.</para>
2916             </listitem>
2917           </varlistentry>
2918
2919           <varlistentry>
2920             <term><literal>3</literal> <phrase>Incorrect
2921             parameters</phrase></term>
2922
2923             <listitem>
2924               <para>This error is generated when the server has signature(s)
2925               defined for a method, and the parameters passed by the client do
2926               not match any of signatures.</para>
2927             </listitem>
2928           </varlistentry>
2929
2930           <varlistentry>
2931             <term><literal>4</literal> <phrase>Can't introspect: method
2932             unknown</phrase></term>
2933
2934             <listitem>
2935               <para>This error is generated by the builtin
2936               <function>system.*</function> methods when any kind of
2937               introspection is attempted on a method undefined by the
2938               server.</para>
2939             </listitem>
2940           </varlistentry>
2941
2942           <varlistentry>
2943             <term><literal>5</literal> <phrase>Didn't receive 200 OK from
2944             remote server</phrase></term>
2945
2946             <listitem>
2947               <para>This error is generated by the client when a remote server
2948               doesn't return HTTP/1.1 200 OK in response to a request. A more
2949               detailed error report is added onto the end of the phrase
2950               above.</para>
2951             </listitem>
2952           </varlistentry>
2953
2954           <varlistentry>
2955             <term><literal>6</literal> <phrase>No data received from
2956             server</phrase></term>
2957
2958             <listitem>
2959               <para>This error is generated by the client when a remote server
2960               returns HTTP/1.1 200 OK in response to a request, but no
2961               response body follows the HTTP headers.</para>
2962             </listitem>
2963           </varlistentry>
2964
2965           <varlistentry>
2966             <term><literal>7</literal> <phrase>No SSL support compiled
2967             in</phrase></term>
2968
2969             <listitem>
2970               <para>This error is generated by the client when trying to send
2971               a request with HTTPS and the CURL extension is not available to
2972               PHP.</para>
2973             </listitem>
2974           </varlistentry>
2975
2976           <varlistentry>
2977             <term><literal>8</literal> <phrase>CURL error</phrase></term>
2978
2979             <listitem>
2980               <para>This error is generated by the client when trying to send
2981               a request with HTTPS and the HTTPS communication fails.</para>
2982             </listitem>
2983           </varlistentry>
2984
2985           <varlistentry>
2986             <term><literal>9-14</literal> <phrase>multicall
2987             errors</phrase></term>
2988
2989             <listitem>
2990               <para>These errors are generated by the server when something
2991               fails inside a system.multicall request.</para>
2992             </listitem>
2993           </varlistentry>
2994
2995           <varlistentry>
2996             <term><literal>100-</literal> <phrase>XML parse
2997             errors</phrase></term>
2998
2999             <listitem>
3000               <para>Returns 100 plus the XML parser error code for the fault
3001               that occurred. The <function>faultString</function> returned
3002               explains where the parse error was in the incoming XML
3003               stream.</para>
3004             </listitem>
3005           </varlistentry>
3006         </variablelist>
3007       </sect2>
3008
3009       <sect2>
3010         <title>'New style' servers</title>
3011
3012         <para>In the same spirit of simplification that inspired the
3013         <varname>xmlrpc_client::return_type</varname> class variable, a new
3014         class variable has been added to the server class:
3015         <varname>functions_parameters_type</varname>. When set to 'phpvals',
3016         the functions registered in the server dispatch map will be called
3017         with plain php values as parameters, instead of a single xmlrpcmsg
3018         instance parameter. The return value of those functions is expected to
3019         be a plain php value, too. An example is worth a thousand
3020         words:<programlisting language="php">
3021   function foo($usr_id, $out_lang='en') {
3022     global $xmlrpcerruser;
3023
3024     ...
3025
3026     if ($someErrorCondition)
3027       return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
3028     else
3029       return array(
3030         'name' =&gt; 'Joe',
3031         'age' =&gt; 27,
3032         'picture' =&gt; new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
3033       );
3034   }
3035
3036   $s = new xmlrpc_server(
3037     array(
3038       "examples.myFunc" =&gt; array(
3039         "function" =&gt; "bar::foobar",
3040         "signature" =&gt; array(
3041           array($xmlrpcString, $xmlrpcInt),
3042           array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
3043         )
3044       )
3045     ), false);
3046   $s-&gt;functions_parameters_type = 'phpvals';
3047   $s-&gt;service();
3048 </programlisting>There are a few things to keep in mind when using this
3049         simplified syntax:</para>
3050
3051         <para>to return an xmlrpc error, the method handler function must
3052         return an instance of <classname>xmlrpcresp</classname>. The only
3053         other way for the server to know when an error response should be
3054         served to the client is to throw an exception and set the server's
3055         <varname>exception_handling</varname> memeber var to 1;</para>
3056
3057         <para>to return a base64 value, the method handler function must
3058         encode it on its own, creating an instance of an xmlrpcval
3059         object;</para>
3060
3061         <para>the method handler function cannot determine the name of the
3062         xmlrpc method it is serving, unlike standard handler functions that
3063         can retrieve it from the message object;</para>
3064
3065         <para>when receiving nested parameters, the method handler function
3066         has no way to distinguish a php string that was sent as base64 value
3067         from one that was sent as a string value;</para>
3068
3069         <para>this has a direct consequence on the support of
3070         system.multicall: a method whose signature contains datetime or base64
3071         values will not be available to multicall calls;</para>
3072
3073         <para>last but not least, the direct parsing of xml to php values is
3074         much faster than using xmlrpcvals, and allows the library to handle
3075         much bigger messages without allocating all available server memory or
3076         smashing PHP recursive call stack.</para>
3077       </sect2>
3078     </sect1>
3079   </chapter>
3080
3081   <chapter id="globalvars">
3082     <title>Global variables</title>
3083
3084     <para>Many global variables are defined in the xmlrpc.inc file. Some of
3085     those are meant to be used as constants (and modifying their value might
3086     cause unpredictable behaviour), while some others can be modified in your
3087     php scripts to alter the behaviour of the xml-rpc client and
3088     server.</para>
3089
3090     <sect1>
3091       <title>"Constant" variables</title>
3092
3093       <sect2>
3094         <title>$xmlrpcerruser</title>
3095
3096         <para><fieldsynopsis>
3097             <varname>$xmlrpcerruser</varname>
3098
3099             <initializer>800</initializer>
3100           </fieldsynopsis>The minimum value for errors reported by user
3101         implemented XML-RPC servers. Error numbers lower than that are
3102         reserved for library usage.</para>
3103       </sect2>
3104
3105       <sect2>
3106         <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
3107         $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,
3108         $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>
3109
3110         <para>For convenience the strings representing the XML-RPC types have
3111         been encoded as global variables:<programlisting language="php">
3112 $xmlrpcI4="i4";
3113 $xmlrpcInt="int";
3114 $xmlrpcBoolean="boolean";
3115 $xmlrpcDouble="double";
3116 $xmlrpcString="string";
3117 $xmlrpcDateTime="dateTime.iso8601";
3118 $xmlrpcBase64="base64";
3119 $xmlrpcArray="array";
3120 $xmlrpcStruct="struct";
3121 $xmlrpcValue="undefined";
3122 $xmlrpcNull="null";
3123 </programlisting></para>
3124       </sect2>
3125
3126       <sect2>
3127         <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
3128         $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
3129         $xmlEntities, $xmlrpcs_capabilities</title>
3130
3131         <para>Reserved for internal usage.</para>
3132       </sect2>
3133     </sect1>
3134
3135     <sect1>
3136       <title>Variables whose value can be modified</title>
3137
3138       <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">
3139         <title xreflabel="">xmlrpc_defencoding</title>
3140
3141         <fieldsynopsis>
3142           <varname>$xmlrpc_defencoding</varname>
3143
3144           <initializer>"UTF8"</initializer>
3145         </fieldsynopsis>
3146
3147         <para>This variable defines the character set encoding that will be
3148         used by the xml-rpc client and server to decode the received messages,
3149         when a specific charset declaration is not found (in the messages sent
3150         non-ascii chars are always encoded using character references, so that
3151         the produced xml is valid regardless of the charset encoding
3152         assumed).</para>
3153
3154         <para>Allowed values: <literal>"UTF8"</literal>,
3155         <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>
3156
3157         <para>Note that the appropriate RFC actually mandates that XML
3158         received over HTTP without indication of charset encoding be treated
3159         as US-ASCII, but many servers and clients 'in the wild' violate the
3160         standard, and assume the default encoding is UTF-8.</para>
3161       </sect2>
3162
3163       <sect2>
3164         <title>xmlrpc_internalencoding</title>
3165
3166         <para><fieldsynopsis>
3167             <varname>$xmlrpc_internalencoding</varname>
3168
3169             <initializer>"ISO-8859-1"</initializer>
3170           </fieldsynopsis>This variable defines the character set encoding
3171         that the library uses to transparently encode into valid XML the
3172         xml-rpc values created by the user and to re-encode the received
3173         xml-rpc values when it passes them to the PHP application. It only
3174         affects xml-rpc values of string type. It is a separate value from
3175         xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
3176         on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
3177         character set used internally by PHP (unless you are running an
3178         MBString-enabled installation), so you should change it only in
3179         special situations, if e.g. the string values exchanged in the xml-rpc
3180         messages are directly inserted into / fetched from a database
3181         configured to return UTF8 encoded strings to PHP. Example
3182         usage:</para>
3183
3184         <para><programlisting language="php">
3185 &lt;?php
3186
3187 include('xmlrpc.inc');
3188 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
3189 $v = new xmlrpcval('Îºá½¹Ï\83Î¼Îµ'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
3190 </programlisting></para>
3191       </sect2>
3192
3193       <sect2>
3194         <title>xmlrpcName</title>
3195
3196         <para><fieldsynopsis>
3197             <varname>$xmlrpcName</varname>
3198
3199             <initializer>"XML-RPC for PHP"</initializer>
3200           </fieldsynopsis>The string representation of the name of the XML-RPC
3201         for PHP library. It is used by the client for building the User-Agent
3202         HTTP header that is sent with every request to the server. You can
3203         change its value if you need to customize the User-Agent
3204         string.</para>
3205       </sect2>
3206
3207       <sect2>
3208         <title>xmlrpcVersion</title>
3209
3210         <para><fieldsynopsis>
3211             <varname>$xmlrpcVersion</varname>
3212
3213             <initializer>"2.2"</initializer>
3214           </fieldsynopsis>The string representation of the version number of
3215         the XML-RPC for PHP library in use. It is used by the client for
3216         building the User-Agent HTTP header that is sent with every request to
3217         the server. You can change its value if you need to customize the
3218         User-Agent string.</para>
3219       </sect2>
3220
3221       <sect2>
3222         <title>xmlrpc_null_extension</title>
3223
3224         <para>When set to <constant>TRUE</constant>, the lib will enable
3225         support for the &lt;NIL/&gt; (and &lt;EX:NIL/&gt;) xmlrpc value, as
3226         per the extension to the standard proposed here. This means that
3227         &lt;NIL/&gt; and &lt;EX:NIL/&gt; tags received will be parsed as valid
3228         xmlrpc, and the corresponding xmlrpcvals will return "null" for
3229         <methodname>scalarTyp()</methodname>.</para>
3230       </sect2>
3231
3232       <sect2>
3233         <title>xmlrpc_null_apache_encoding</title>
3234
3235         <para>When set to <literal>TRUE</literal>, php NULL values encoded
3236         into <classname>xmlrpcval</classname> objects get serialized using the
3237         <literal>&lt;EX:NIL/&gt;</literal> tag instead of
3238         <literal>&lt;NIL/&gt;</literal>. Please note that both forms are
3239         always accepted as input regardless of the value of this
3240         variable.</para>
3241       </sect2>
3242     </sect1>
3243   </chapter>
3244
3245   <chapter id="helpers">
3246     <title>Helper functions</title>
3247
3248     <para>XML-RPC for PHP contains some helper functions which you can use to
3249     make processing of XML-RPC requests easier.</para>
3250
3251     <sect1>
3252       <title>Date functions</title>
3253
3254       <para>The XML-RPC specification has this to say on dates:</para>
3255
3256       <blockquote>
3257         <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be
3258         specified by the server in its documentation what assumptions it makes
3259         about timezones.</para>
3260       </blockquote>
3261
3262       <para>Unfortunately, this means that date processing isn't
3263       straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
3264       use the timezone specifier.</para>
3265
3266       <para>We strongly recommend that in every case where you pass dates in
3267       XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
3268       languages include routines for handling GMT times natively, and you
3269       won't have to translate between timezones.</para>
3270
3271       <para>For more information about dates, see <ulink
3272       url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right
3273       Format for Dates</ulink>, which has a handy link to a PDF of the ISO
3274       8601 specification. Note that XML-RPC uses exactly one of the available
3275       representations: CCYYMMDDTHH:MM:SS.</para>
3276
3277       <sect2 id="iso8601encode" xreflabel="iso8601_encode()">
3278         <title>iso8601_encode</title>
3279
3280         <funcsynopsis>
3281           <funcprototype>
3282             <funcdef><type>string</type><function>iso8601_encode</function></funcdef>
3283
3284             <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>
3285
3286             <paramdef
3287             choice="opt"><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
3288           </funcprototype>
3289         </funcsynopsis>
3290
3291         <para>Returns an ISO 8601 formatted date generated from the UNIX
3292         timestamp <parameter>$time_t</parameter>, as returned by the PHP
3293         function <function>time()</function>.</para>
3294
3295         <para>The argument <parameter>$utc</parameter> can be omitted, in
3296         which case it defaults to <literal>0</literal>. If it is set to
3297         <literal>1</literal>, then the function corrects the time passed in
3298         for UTC. Example: if you're in the GMT-6:00 timezone and set
3299         <parameter>$utc</parameter>, you will receive a date representation
3300         six hours ahead of your local time.</para>
3301
3302         <para>The included demo program <filename>vardemo.php</filename>
3303         includes a demonstration of this function.</para>
3304       </sect2>
3305
3306       <sect2 id="iso8601decode" xreflabel="iso8601_decode()">
3307         <title>iso8601_decode</title>
3308
3309         <funcsynopsis>
3310           <funcprototype>
3311             <funcdef><type>int</type><function>iso8601_decode</function></funcdef>
3312
3313             <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>
3314
3315             <paramdef><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
3316           </funcprototype>
3317         </funcsynopsis>
3318
3319         <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date
3320         string passed in. If <parameter>$utc</parameter> is
3321         <literal>1</literal> then <parameter>$isoString</parameter> is assumed
3322         to be in the UTC timezone, and thus the result is also UTC: otherwise,
3323         the timezone is assumed to be your local timezone and you receive a
3324         local timestamp.</para>
3325       </sect2>
3326     </sect1>
3327
3328     <sect1 id="arrayuse">
3329       <title>Easy use with nested PHP values</title>
3330
3331       <para>Dan Libby was kind enough to contribute two helper functions that
3332       make it easier to translate to and from PHP values. This makes it easier
3333       to deal with complex structures. At the moment support is limited to
3334       <type>int</type>, <type>double</type>, <type>string</type>,
3335       <type>array</type>, <type>datetime</type> and <type>struct</type>
3336       datatypes; note also that all PHP arrays are encoded as structs, except
3337       arrays whose keys are integer numbers starting with 0 and incremented by
3338       1.</para>
3339
3340       <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>
3341
3342       <sect2 id="phpxmlrpcdecode">
3343         <title>php_xmlrpc_decode</title>
3344
3345         <funcsynopsis>
3346           <funcprototype>
3347             <funcdef><type>mixed</type><function>php_xmlrpc_decode</function></funcdef>
3348
3349             <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
3350
3351             <paramdef><type>array</type><parameter>$options</parameter></paramdef>
3352           </funcprototype>
3353
3354           <funcprototype>
3355             <funcdef><type>array</type><function>php_xmlrpc_decode</function></funcdef>
3356
3357             <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>
3358
3359             <paramdef><type>string</type><parameter>$options</parameter></paramdef>
3360           </funcprototype>
3361         </funcsynopsis>
3362
3363         <para>Returns a native PHP value corresponding to the values found in
3364         the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,
3365         translated into PHP types. Base-64 and datetime values are
3366         automatically decoded to strings.</para>
3367
3368         <para>In the second form, returns an array containing the parameters
3369         of the given
3370         <parameter><classname>xmlrpcmsg</classname>_val</parameter>, decoded
3371         to php types.</para>
3372
3373         <para>The <parameter>options</parameter> parameter is optional. If
3374         specified, it must consist of an array of options to be enabled in the
3375         decoding process. At the moment the only valid option are
3376         <symbol>decode_php_objs</symbol> and
3377         <literal>dates_as_objects</literal>. When the first is set, php
3378         objects that have been converted to xml-rpc structs using the
3379         <function>php_xmlrpc_encode</function> function and a corresponding
3380         encoding option will be converted back into object values instead of
3381         arrays (provided that the class definition is available at
3382         reconstruction time). When the second is set, XML-RPC datetime values
3383         will be converted into native <classname>dateTime</classname> objects
3384         instead of strings.</para>
3385
3386         <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
3387         extreme care before enabling the <symbol>decode_php_objs</symbol>
3388         option: when php objects are rebuilt from the received xml, their
3389         constructor function will be silently invoked. This means that you are
3390         allowing the remote end to trigger execution of uncontrolled PHP code
3391         on your server, opening the door to code injection exploits. Only
3392         enable this option when you have complete trust of the remote
3393         server/client.</para>
3394
3395         <para>Example:<programlisting language="php">
3396 // wrapper to expose an existing php function as xmlrpc method handler
3397 function foo_wrapper($m)
3398 {
3399   $params = php_xmlrpc_decode($m);
3400   $retval = call_user_func_array('foo', $params);
3401   return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
3402 }
3403
3404 $s = new xmlrpc_server(array(
3405    "examples.myFunc1" =&gt; array(
3406      "function" =&gt; "foo_wrapper",
3407      "signatures" =&gt; ...
3408   )));
3409 </programlisting></para>
3410       </sect2>
3411
3412       <sect2 id="phpxmlrpcencode">
3413         <title>php_xmlrpc_encode</title>
3414
3415         <funcsynopsis>
3416           <funcprototype>
3417             <funcdef><type>xmlrpcval</type><function>php_xmlrpc_encode</function></funcdef>
3418
3419             <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
3420
3421             <paramdef><type>array</type><parameter>$options</parameter></paramdef>
3422           </funcprototype>
3423         </funcsynopsis>
3424
3425         <para>Returns an <type>xmlrpcval</type> object populated with the PHP
3426         values in <parameter>$phpval</parameter>. Works recursively on arrays
3427         and objects, encoding numerically indexed php arrays into array-type
3428         xmlrpcval objects and non numerically indexed php arrays into
3429         struct-type xmlrpcval objects. Php objects are encoded into
3430         struct-type xmlrpcvals, excepted for php values that are already
3431         instances of the xmlrpcval class or descendants thereof, which will
3432         not be further encoded. Note that there's no support for encoding php
3433         values into base-64 values. Encoding of date-times is optionally
3434         carried on on php strings with the correct format.</para>
3435
3436         <para>The <parameter>options</parameter> parameter is optional. If
3437         specified, it must consist of an array of options to be enabled in the
3438         encoding process. At the moment the only valid options are
3439         <symbol>encode_php_objs</symbol>, <literal>null_extension</literal>
3440         and <symbol>auto_dates</symbol>.</para>
3441
3442         <para>The first will enable the creation of 'particular' xmlrpcval
3443         objects out of php objects, that add a "php_class" xml attribute to
3444         their serialized representation. This attribute allows the function
3445         php_xmlrpc_decode to rebuild the native php objects (provided that the
3446         same class definition exists on both sides of the communication). The
3447         second allows to encode php <literal>NULL</literal> values to the
3448         <literal>&lt;NIL/&gt;</literal> (or
3449         <literal>&lt;EX:NIL/&gt;</literal>, see ...) tag. The last encodes any
3450         string that matches the ISO8601 format into an XML-RPC
3451         datetime.</para>
3452
3453         <para>Example:<programlisting language="php">
3454 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
3455 $val = php_xmlrpc_encode(array(
3456   'first struct_element: an int' =&gt; 666,
3457   'second: an array' =&gt; array ('apple', 'orange', 'banana'),
3458   'third: a base64 element' =&gt; new xmlrpcval('hello world', 'base64'),
3459   'fourth: a datetime' =&gt; '20060107T01:53:00'
3460   ), array('auto_dates'));
3461 </programlisting></para>
3462       </sect2>
3463
3464       <sect2>
3465         <title>php_xmlrpc_decode_xml</title>
3466
3467         <funcsynopsis>
3468           <funcprototype>
3469             <funcdef><type>xmlrpcval | xmlrpcresp |
3470             xmlrpcmsg</type><function>php_xmlrpc_decode_xml</function></funcdef>
3471
3472             <paramdef><type>string</type><parameter>$xml</parameter></paramdef>
3473
3474             <paramdef><type>array</type><parameter>$options</parameter></paramdef>
3475           </funcprototype>
3476         </funcsynopsis>
3477
3478         <para>Decodes the xml representation of either an xmlrpc request,
3479         response or single value, returning the corresponding php-xmlrpc
3480         object, or <literal>FALSE</literal> in case of an error.</para>
3481
3482         <para>The <parameter>options</parameter> parameter is optional. If
3483         specified, it must consist of an array of options to be enabled in the
3484         decoding process. At the moment, no option is supported.</para>
3485
3486         <para>Example:<programlisting language="php">
3487 $text = '&lt;value&gt;&lt;array&gt;&lt;data&gt;&lt;value&gt;Hello world&lt;/value&gt;&lt;/data&gt;&lt;/array&gt;&lt;/value&gt;';
3488 $val = php_xmlrpc_decode_xml($text);
3489 if ($val) echo 'Found a value of type '.$val-&gt;kindOf(); else echo 'Found invalid xml';
3490 </programlisting></para>
3491       </sect2>
3492     </sect1>
3493
3494     <sect1>
3495       <title>Automatic conversion of php functions into xmlrpc methods (and
3496       vice versa)</title>
3497
3498       <para>For the extremely lazy coder, helper functions have been added
3499       that allow to convert a php function into an xmlrpc method, and a
3500       remotely exposed xmlrpc method into a local php function - or a set of
3501       methods into a php class. Note that these comes with many caveat.</para>
3502
3503       <sect2>
3504         <title>wrap_xmlrpc_method</title>
3505
3506         <funcsynopsis>
3507           <funcprototype>
3508             <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
3509
3510             <paramdef>$client</paramdef>
3511
3512             <paramdef>$methodname</paramdef>
3513
3514             <paramdef>$extra_options</paramdef>
3515           </funcprototype>
3516
3517           <funcprototype>
3518             <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
3519
3520             <paramdef>$client</paramdef>
3521
3522             <paramdef>$methodname</paramdef>
3523
3524             <paramdef>$signum</paramdef>
3525
3526             <paramdef>$timeout</paramdef>
3527
3528             <paramdef>$protocol</paramdef>
3529
3530             <paramdef>$funcname</paramdef>
3531           </funcprototype>
3532         </funcsynopsis>
3533
3534         <para>Given an xmlrpc server and a method name, creates a php wrapper
3535         function that will call the remote method and return results using
3536         native php types for both params and results. The generated php
3537         function will return an xmlrpcresp object for failed xmlrpc
3538         calls.</para>
3539
3540         <para>The second syntax is deprecated, and is listed here only for
3541         backward compatibility.</para>
3542
3543         <para>The server must support the
3544         <methodname>system.methodSignature</methodname> xmlrpc method call for
3545         this function to work.</para>
3546
3547         <para>The <parameter>client</parameter> param must be a valid
3548         xmlrpc_client object, previously created with the address of the
3549         target xmlrpc server, and to which the preferred communication options
3550         have been set.</para>
3551
3552         <para>The optional parameters can be passed as array key,value pairs
3553         in the <parameter>extra_options</parameter> param.</para>
3554
3555         <para>The <parameter>signum</parameter> optional param has the purpose
3556         of indicating which method signature to use, if the given server
3557         method has multiple signatures (defaults to 0).</para>
3558
3559         <para>The <parameter>timeout</parameter> and
3560         <parameter>protocol</parameter> optional params are the same as in the
3561         <methodname>xmlrpc_client::send()</methodname> method.</para>
3562
3563         <para>If set, the optional <parameter>new_function_name</parameter>
3564         parameter indicates which name should be used for the generated
3565         function. In case it is not set the function name will be
3566         auto-generated.</para>
3567
3568         <para>If the <literal>return_source</literal> optional parameter is
3569         set, the function will return the php source code to build the wrapper
3570         function, instead of evaluating it (useful to save the code and use it
3571         later as stand-alone xmlrpc client).</para>
3572
3573         <para>If the <literal>encode_php_objs</literal> optional parameter is
3574         set, instances of php objects later passed as parameters to the newly
3575         created function will receive a 'special' treatment that allows the
3576         server to rebuild them as php objects instead of simple arrays. Note
3577         that this entails using a "slightly augmented" version of the xmlrpc
3578         protocol (ie. using element attributes), which might not be understood
3579         by xmlrpc servers implemented using other libraries.</para>
3580
3581         <para>If the <literal>decode_php_objs</literal> optional parameter is
3582         set, instances of php objects that have been appropriately encoded by
3583         the server using a coordinate option will be deserialized as php
3584         objects instead of simple arrays (the same class definition should be
3585         present server side and client side).</para>
3586
3587         <para><emphasis>Note that this might pose a security risk</emphasis>,
3588         since in order to rebuild the object instances their constructor
3589         method has to be invoked, and this means that the remote server can
3590         trigger execution of unforeseen php code on the client: not really a
3591         code injection, but almost. Please enable this option only when you
3592         trust the remote server.</para>
3593
3594         <para>In case of an error during generation of the wrapper function,
3595         FALSE is returned, otherwise the name (or source code) of the new
3596         function.</para>
3597
3598         <para>Known limitations: server must support
3599         <methodname>system.methodsignature</methodname> for the wanted xmlrpc
3600         method; for methods that expose multiple signatures, only one can be
3601         picked; for remote calls with nested xmlrpc params, the caller of the
3602         generated php function has to encode on its own the params passed to
3603         the php function if these are structs or arrays whose (sub)members
3604         include values of type base64.</para>
3605
3606         <para>Note: calling the generated php function 'might' be slow: a new
3607         xmlrpc client is created on every invocation and an xmlrpc-connection
3608         opened+closed. An extra 'debug' param is appended to the parameter
3609         list of the generated php function, useful for debugging
3610         purposes.</para>
3611
3612         <para>Example usage:</para>
3613
3614         <programlisting language="php">
3615 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
3616
3617 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
3618
3619 if (!$function)
3620   die('Cannot introspect remote method');
3621 else {
3622   $stateno = 15;
3623   $statename = $function($a);
3624   if (is_a($statename, 'xmlrpcresp')) // call failed
3625   {
3626     echo 'Call failed: '.$statename-&gt;faultCode().'. Calling again with debug on';
3627     $function($a, true);
3628   }
3629   else
3630     echo "OK, state nr. $stateno is $statename";
3631 }
3632 </programlisting>
3633       </sect2>
3634
3635       <sect2 id="wrap_php_function">
3636         <title>wrap_php_function</title>
3637
3638         <funcsynopsis>
3639           <funcprototype>
3640             <funcdef><type>array</type><function>wrap_php_function</function></funcdef>
3641
3642             <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>
3643
3644             <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>
3645
3646             <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>
3647           </funcprototype>
3648         </funcsynopsis>
3649
3650         <para>Given a user-defined PHP function, create a PHP 'wrapper'
3651         function that can be exposed as xmlrpc method from an xmlrpc_server
3652         object and called from remote clients, and return the appropriate
3653         definition to be added to a server's dispatch map.</para>
3654
3655         <para>The optional <parameter>$wrapper_function_name</parameter>
3656         specifies the name that will be used for the auto-generated
3657         function.</para>
3658
3659         <para>Since php is a typeless language, to infer types of input and
3660         output parameters, it relies on parsing the javadoc-style comment
3661         block associated with the given function. Usage of xmlrpc native types
3662         (such as datetime.dateTime.iso8601 and base64) in the docblock @param
3663         tag is also allowed, if you need the php function to receive/send data
3664         in that particular format (note that base64 encoding/decoding is
3665         transparently carried out by the lib, while datetime vals are passed
3666         around as strings).</para>
3667
3668         <para>Known limitations: only works for
3669         user-defined functions, not for PHP internal functions (reflection
3670         does not support retrieving number/type of params for those); the
3671         wrapped php function will not be able to programmatically return an
3672         xmlrpc error response.</para>
3673
3674         <para>If the <literal>return_source</literal> optional parameter is
3675         set, the function will return the php source code to build the wrapper
3676         function, instead of evaluating it (useful to save the code and use it
3677         later in a stand-alone xmlrpc server). It will be in the stored in the
3678         <literal>source</literal> member of the returned array.</para>
3679
3680         <para>If the <literal>suppress_warnings</literal> optional parameter
3681         is set, any runtime warning generated while processing the
3682         user-defined php function will be catched and not be printed in the
3683         generated xml response.</para>
3684
3685         <para>If the <parameter>extra_options</parameter> array contains the
3686         <literal>encode_php_objs</literal> value, wrapped functions returning
3687         php objects will generate "special" xmlrpc responses: when the xmlrpc
3688         decoding of those responses is carried out by this same lib, using the
3689         appropriate param in php_xmlrpc_decode(), the objects will be
3690         rebuilt.</para>
3691
3692         <para>In short: php objects can be serialized, too (except for their
3693         resource members), using this function. Other libs might choke on the
3694         very same xml that will be generated in this case (i.e. it has a
3695         nonstandard attribute on struct element tags)</para>
3696
3697         <para>If the <literal>decode_php_objs</literal> optional parameter is
3698         set, instances of php objects that have been appropriately encoded by
3699         the client using a coordinate option will be deserialized and passed
3700         to the user function as php objects instead of simple arrays (the same
3701         class definition should be present server side and client
3702         side).</para>
3703
3704         <para><emphasis>Note that this might pose a security risk</emphasis>,
3705         since in order to rebuild the object instances their constructor
3706         method has to be invoked, and this means that the remote client can
3707         trigger execution of unforeseen php code on the server: not really a
3708         code injection, but almost. Please enable this option only when you
3709         trust the remote clients.</para>
3710
3711         <para>Example usage:</para>
3712
3713         <para><programlisting language="php">/**
3714 * State name from state number decoder. NB: do NOT remove this comment block.
3715 * @param integer $stateno the state number
3716 * @return string the name of the state (or error description)
3717 */
3718 function findstate($stateno)
3719 {
3720   global $stateNames;
3721   if (isset($stateNames[$stateno-1]))
3722   {
3723     return $stateNames[$stateno-1];
3724   }
3725   else
3726   {
3727     return "I don't have a state for the index '" . $stateno . "'";
3728   }
3729 }
3730
3731 // wrap php function, build xmlrpc server
3732 $methods = array();
3733 $findstate_sig = wrap_php_function('findstate');
3734 if ($findstate_sig)
3735   $methods['examples.getStateName'] = $findstate_sig;
3736 $srv = new xmlrpc_server($methods);
3737 </programlisting></para>
3738       </sect2>
3739     </sect1>
3740
3741     <sect1 id="deprecated">
3742       <title>Functions removed from the library</title>
3743
3744       <para>The following two functions have been deprecated in version 1.1 of
3745       the library, and removed in version 2, in order to avoid conflicts with
3746       the EPI xml-rpc library, which also defines two functions with the same
3747       names.</para>
3748
3749       <para>To ease the transition to the new naming scheme and avoid breaking
3750       existing implementations, the following scheme has been adopted:
3751       <itemizedlist>
3752           <listitem>
3753             <para>If EPI-XMLRPC is not active in the current PHP installation,
3754             the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
3755             <literal>'0'</literal></para>
3756           </listitem>
3757
3758           <listitem>
3759             <para>If EPI-XMLRPC is active in the current PHP installation, the
3760             constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
3761             <literal>'1'</literal></para>
3762           </listitem>
3763         </itemizedlist></para>
3764
3765       <para>The following documentation is kept for historical
3766       reference:</para>
3767
3768       <sect2 id="xmlrpcdecode">
3769         <title>xmlrpc_decode</title>
3770
3771         <funcsynopsis>
3772           <funcprototype>
3773             <funcdef><type>mixed</type><function>xmlrpc_decode</function></funcdef>
3774
3775             <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
3776           </funcprototype>
3777         </funcsynopsis>
3778
3779         <para>Alias for php_xmlrpc_decode.</para>
3780       </sect2>
3781
3782       <sect2 id="xmlrpcencode">
3783         <title>xmlrpc_encode</title>
3784
3785         <funcsynopsis>
3786           <funcprototype>
3787             <funcdef><type>xmlrpcval</type><function>xmlrpc_encode</function></funcdef>
3788
3789             <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
3790           </funcprototype>
3791         </funcsynopsis>
3792
3793         <para>Alias for php_xmlrpc_encode.</para>
3794       </sect2>
3795     </sect1>
3796
3797     <sect1 id="debugging">
3798       <title>Debugging aids</title>
3799
3800       <sect2>
3801         <title>xmlrpc_debugmsg</title>
3802
3803         <funcsynopsis>
3804           <funcprototype>
3805             <funcdef><type>void</type><function>xmlrpc_debugmsg</function></funcdef>
3806
3807             <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>
3808           </funcprototype>
3809         </funcsynopsis>
3810
3811         <para>Sends the contents of <parameter>$debugstring</parameter> in XML
3812         comments in the server return payload. If a PHP client has debugging
3813         turned on, the user will be able to see server debug
3814         information.</para>
3815
3816         <para>Use this function in your methods so you can pass back
3817         diagnostic information. It is only available from
3818         <filename>xmlrpcs.inc</filename>.</para>
3819       </sect2>
3820     </sect1>
3821   </chapter>
3822
3823   <chapter id="reserved" xreflabel="Reserved methods">
3824     <title>Reserved methods</title>
3825
3826     <para>In order to extend the functionality offered by XML-RPC servers
3827     without impacting on the protocol, reserved methods are supported in this
3828     release.</para>
3829
3830     <para>All methods starting with <function>system.</function> are
3831     considered reserved by the server. PHP for XML-RPC itself provides four
3832     special methods, detailed in this chapter.</para>
3833
3834     <para>Note that all server objects will automatically respond to clients
3835     querying these methods, unless the property
3836     <property>allow_system_funcs</property> has been set to
3837     <constant>false</constant> before calling the
3838     <methodname>service()</methodname> method. This might pose a security risk
3839     if the server is exposed to public access, e.g. on the internet.</para>
3840
3841     <sect1>
3842       <title>system.getCapabilities</title>
3843
3844       <para></para>
3845     </sect1>
3846
3847     <sect1>
3848       <title>system.listMethods</title>
3849
3850       <para>This method may be used to enumerate the methods implemented by
3851       the XML-RPC server.</para>
3852
3853       <para>The <function>system.listMethods</function> method requires no
3854       parameters. It returns an array of strings, each of which is the name of
3855       a method implemented by the server.</para>
3856     </sect1>
3857
3858     <sect1 id="sysmethodsig">
3859       <title>system.methodSignature</title>
3860
3861       <para>This method takes one parameter, the name of a method implemented
3862       by the XML-RPC server.</para>
3863
3864       <para>It returns an array of possible signatures for this method. A
3865       signature is an array of types. The first of these types is the return
3866       type of the method, the rest are parameters.</para>
3867
3868       <para>Multiple signatures (i.e. overloading) are permitted: this is the
3869       reason that an array of signatures are returned by this method.</para>
3870
3871       <para>Signatures themselves are restricted to the top level parameters
3872       expected by a method. For instance if a method expects one array of
3873       structs as a parameter, and it returns a string, its signature is simply
3874       "string, array". If it expects three integers, its signature is "string,
3875       int, int, int".</para>
3876
3877       <para>For parameters that can be of more than one type, the "undefined"
3878       string is supported.</para>
3879
3880       <para>If no signature is defined for the method, a not-array value is
3881       returned. Therefore this is the way to test for a non-signature, if
3882       <parameter>$resp</parameter> below is the response object from a method
3883       call to <function>system.methodSignature</function>:</para>
3884
3885       <programlisting language="php">
3886 $v = $resp-&gt;value();
3887 if ($v-&gt;kindOf() != "array") {
3888   // then the method did not have a signature defined
3889 }
3890 </programlisting>
3891
3892       <para>See the <filename>introspect.php</filename> demo included in this
3893       distribution for an example of using this method.</para>
3894     </sect1>
3895
3896     <sect1 id="sysmethhelp">
3897       <title>system.methodHelp</title>
3898
3899       <para>This method takes one parameter, the name of a method implemented
3900       by the XML-RPC server.</para>
3901
3902       <para>It returns a documentation string describing the use of that
3903       method. If no such string is available, an empty string is
3904       returned.</para>
3905
3906       <para>The documentation string may contain HTML markup.</para>
3907     </sect1>
3908
3909     <sect1>
3910       <title>system.multicall</title>
3911
3912       <para>This method takes one parameter, an array of 'request' struct
3913       types. Each request struct must contain a
3914       <parameter>methodName</parameter> member of type string and a
3915       <parameter>params</parameter> member of type array, and corresponds to
3916       the invocation of the corresponding method.</para>
3917
3918       <para>It returns a response of type array, with each value of the array
3919       being either an error struct (containing the faultCode and faultString
3920       members) or the successful response value of the corresponding single
3921       method call.</para>
3922     </sect1>
3923   </chapter>
3924
3925   <chapter id="examples" xreflabel="Examples">
3926     <title>Examples</title>
3927
3928     <para>The best examples are to be found in the sample files included with
3929     the distribution. Some are included here.</para>
3930
3931     <sect1 id="statename">
3932       <title>XML-RPC client: state name query</title>
3933
3934       <para>Code to get the corresponding state name from a number (1-50) from
3935       the demo server available on SourceForge</para>
3936
3937       <programlisting language="php">
3938   $m = new xmlrpcmsg('examples.getStateName',
3939     array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
3940   $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
3941   $r = $c-&gt;send($m);
3942   if (!$r-&gt;faultCode()) {
3943       $v = $r-&gt;value();
3944       print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
3945         htmlentities($v-&gt;scalarval()) . "&lt;BR&gt;";
3946       print "&lt;HR&gt;I got this value back&lt;BR&gt;&lt;PRE&gt;" .
3947         htmlentities($r-&gt;serialize()) . "&lt;/PRE&gt;&lt;HR&gt;\n";
3948   } else {
3949       print "Fault &lt;BR&gt;";
3950       print "Code: " . htmlentities($r-&gt;faultCode()) . "&lt;BR&gt;" .
3951             "Reason: '" . htmlentities($r-&gt;faultString()) . "'&lt;BR&gt;";
3952   }
3953 </programlisting>
3954     </sect1>
3955
3956     <sect1>
3957       <title>Executing a multicall call</title>
3958
3959       <para>To be documented...</para>
3960     </sect1>
3961   </chapter>
3962
3963   <chapter id="faq">
3964     <title>Frequently Asked Questions</title>
3965
3966     <sect1>
3967       <title>How to send custom XML as payload of a method call</title>
3968
3969       <para>Unfortunately, at the time the XML-RPC spec was designed, support
3970       for namespaces in XML was not as ubiquitous as it is now. As a
3971       consequence, no support was provided in the protocol for embedding XML
3972       elements from other namespaces into an xmlrpc request.</para>
3973
3974       <para>To send an XML "chunk" as payload of a method call or response,
3975       two options are available: either send the complete XML block as a
3976       string xmlrpc value, or as a base64 value. Since the '&lt;' character in
3977       string values is encoded as '&amp;lt;' in the xml payload of the method
3978       call, the XML string will not break the surrounding xmlrpc, unless
3979       characters outside of the assumed character set are used. The second
3980       method has the added benefits of working independently of the charset
3981       encoding used for the xml to be transmitted, and preserving exactly
3982       whitespace, whilst incurring in some extra message length and cpu load
3983       (for carrying out the base64 encoding/decoding).</para>
3984     </sect1>
3985
3986     <sect1>
3987       <title>Is there any limitation on the size of the requests / responses
3988       that can be successfully sent?</title>
3989
3990       <para>Yes. But I have no hard figure to give; it most likely will depend
3991       on the version of PHP in usage and its configuration.</para>
3992
3993       <para>Keep in mind that this library is not optimized for speed nor for
3994       memory usage. Better alternatives exist when there are strict
3995       requirements on throughput or resource usage, such as the php native
3996       xmlrpc extension (see the PHP manual for more information).</para>
3997
3998       <para>Keep in mind also that HTTP is probably not the best choice in
3999       such a situation, and XML is a deadly enemy. CSV formatted data over
4000       socket would be much more efficient.</para>
4001
4002       <para>If you really need to move a massive amount of data around, and
4003       you are crazy enough to do it using phpxmlrpc, your best bet is to
4004       bypass usage of the xmlrpcval objects, at least in the decoding phase,
4005       and have the server (or client) object return to the calling function
4006       directly php values (see <varname>xmlrpc_client::return_type</varname>
4007       and <varname>xmlrpc_server::functions_parameters_type</varname> for more
4008       details).</para>
4009     </sect1>
4010
4011     <sect1>
4012       <title>My server (client) returns an error whenever the client (server)
4013       returns accented characters</title>
4014
4015       <para>To be documented...</para>
4016     </sect1>
4017
4018     <sect1>
4019       <title>How to enable long-lasting method calls</title>
4020
4021       <para>To be documented...</para>
4022     </sect1>
4023
4024     <sect1>
4025       <title>My client returns "XML-RPC Fault #2: Invalid return payload:
4026       enable debugging to examine incoming payload": what should I do?</title>
4027
4028       <para>The response you are seeing is a default error response that the
4029       client object returns to the php application when the server did not
4030       respond to the call with a valid xmlrpc response.</para>
4031
4032       <para>The most likely cause is that you are not using the correct URL
4033       when creating the client object, or you do not have appropriate access
4034       rights to the web page you are requesting, or some other common http
4035       misconfiguration.</para>
4036
4037       <para>To find out what the server is really returning to your client,
4038       you have to enable the debug mode of the client, using
4039       $client-&gt;setdebug(1);</para>
4040     </sect1>
4041
4042     <sect1>
4043       <title>How can I save to a file the xml of the xmlrpc responses received
4044       from servers?</title>
4045
4046       <para>If what you need is to save the responses received from the server
4047       as xml, you have two options:</para>
4048
4049       <para>1- use the serialize() method on the response object.</para>
4050
4051       <programlisting language="php">
4052 $resp = $client-&gt;send($msg);
4053 if (!$resp-&gt;faultCode())
4054   $data_to_be_saved = $resp-&gt;serialize();
4055 </programlisting>
4056
4057       <para>Note that this will not be 100% accurate, since the xml generated
4058       by the response object can be different from the xml received,
4059       especially if there is some character set conversion involved, or such
4060       (eg. if you receive an empty string tag as &lt;string/&gt;, serialize()
4061       will output &lt;string&gt;&lt;/string&gt;), or if the server sent back
4062       as response something invalid (in which case the xml generated client
4063       side using serialize() will correspond to the error response generated
4064       internally by the lib).</para>
4065
4066       <para>2 - set the client object to return the raw xml received instead
4067       of the decoded objects:</para>
4068
4069       <programlisting language="php">
4070 $client = new xmlrpc_client($url);
4071 $client-&gt;return_type = 'xml';
4072 $resp = $client-&gt;send($msg);
4073 if (!$resp-&gt;faultCode())
4074   $data_to_be_saved = $resp-&gt;value();
4075 </programlisting>
4076
4077       <para>Note that using this method the xml response response will not be
4078       parsed at all by the library, only the http communication protocol will
4079       be checked. This means that xmlrpc responses sent by the server that
4080       would have generated an error response on the client (eg. malformed xml,
4081       responses that have faultcode set, etc...) now will not be flagged as
4082       invalid, and you might end up saving not valid xml but random
4083       junk...</para>
4084     </sect1>
4085
4086     <sect1>
4087       <title>Can I use the ms windows character set?</title>
4088
4089       <para>If the data your application is using comes from a Microsoft
4090       application, there are some chances that the character set used to
4091       encode it is CP1252 (the same might apply to data received from an
4092       external xmlrpc server/client, but it is quite rare to find xmlrpc
4093       toolkits that encode to CP1252 instead of UTF8). It is a character set
4094       which is "almost" compatible with ISO 8859-1, but for a few extra
4095       characters.</para>
4096
4097       <para>PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
4098       The net result of this situation is that those extra characters will not
4099       be properly encoded, and will be received at the other end of the
4100       XML-RPC tranmission as "garbled data". Unfortunately the library cannot
4101       provide real support for CP1252 because of limitations in the PHP 4 xml
4102       parser. Luckily, we tried our best to support this character set anyway,
4103       and, since version 2.2.1, there is some form of support, left commented
4104       in the code.</para>
4105
4106       <para>To properly encode outgoing data that is natively in CP1252, you
4107       will have to uncomment all relative code in the file
4108       <filename>xmlrpc.inc</filename> (you can search for the string "1252"),
4109       then set <code>$GLOBALS['xmlrpc_internalencoding']='CP1252';</code>
4110       Please note that all incoming data will then be fed to your application
4111       as UTF-8 to avoid any potentail data loss.</para>
4112     </sect1>
4113
4114     <sect1>
4115       <title>Does the library support using cookies / http sessions?</title>
4116
4117       <para>In short: yes, but a little coding is needed to make it
4118       happen.</para>
4119
4120       <para>The code below uses sessions to e.g. let the client store a value
4121       on the server and retrieve it later.</para>
4122
4123       <para><programlisting>
4124 $resp = $client-&gt;send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
4125 if (!$resp-&gt;faultCode())
4126 {
4127   $cookies = $resp-&gt;cookies();
4128   if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
4129   {
4130     $session_id = $cookies['PHPSESSID']['value'];
4131
4132     // do some other stuff here...
4133
4134     $client-&gt;setcookie('PHPSESSID', $session_id);
4135     $val = $client-&gt;send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
4136   }
4137 }
4138 </programlisting>Server-side sessions are handled normally like in any other
4139       php application. Please see the php manual for more information about
4140       sessions.</para>
4141
4142       <para>NB: unlike web browsers, not all xmlrpc clients support usage of
4143       http cookies. If you have troubles with sessions and control only the
4144       server side of the communication, please check with the makers of the
4145       xmlrpc client in use.</para>
4146     </sect1>
4147   </chapter>
4148
4149   <appendix id="integration">
4150     <title>Integration with the PHP xmlrpc extension</title>
4151
4152     <para>To be documented more...</para>
4153
4154     <para>In short: for the fastest execution possible, you can enable the php
4155     native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
4156     following code snippet gives an example of such integration</para>
4157
4158     <programlisting language="php">
4159 /*** client side ***/
4160 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
4161
4162 // tell the client to return raw xml as response value
4163 $c-&gt;return_type = 'xml';
4164
4165 // let the native xmlrpc extension take care of encoding request parameters
4166 $r = $c-&gt;send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
4167
4168 if ($r-&gt;faultCode())
4169   // HTTP transport error
4170   echo 'Got error '.$r-&gt;faultCode();
4171 else
4172 {
4173   // HTTP request OK, but XML returned from server not parsed yet
4174   $v = xmlrpc_decode($r-&gt;value());
4175   // check if we got a valid xmlrpc response from server
4176   if ($v === NULL)
4177     echo 'Got invalid response';
4178   else
4179   // check if server sent a fault response
4180   if (xmlrpc_is_fault($v))
4181     echo 'Got xmlrpc fault '.$v['faultCode'];
4182   else
4183     echo'Got response: '.htmlentities($v);
4184 }
4185 </programlisting>
4186   </appendix>
4187
4188   <appendix id="substitution">
4189     <title>Substitution of the PHP xmlrpc extension</title>
4190
4191     <para>Yet another interesting situation is when you are using a ready-made
4192     php application, that provides support for the XMLRPC protocol via the
4193     native php xmlrpc extension, but the extension is not available on your
4194     php install (e.g. because of shared hosting constraints).</para>
4195
4196     <para>Since version 2.1, the PHP-XMLRPC library provides a compatibility
4197     layer that aims to be 100% compliant with the xmlrpc extension API. This
4198     means that any code written to run on the extension should obtain the
4199     exact same results, albeit using more resources and a longer processing
4200     time, using the PHP-XMLRPC library and the extension compatibility module.
4201     The module is part of the EXTRAS package, available as a separate download
4202     from the sourceforge.net website, since version 0.2</para>
4203   </appendix>
4204
4205   <appendix id="enough">
4206     <title>'Enough of xmlrpcvals!': new style library usage</title>
4207
4208     <para>To be documented...</para>
4209
4210     <para>In the meantime, see docs about xmlrpc_client::return_type and
4211     xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
4212     php_xmlrpc_decode and php_xmlrpc_decode_xml</para>
4213   </appendix>
4214
4215   <appendix id="debugger">
4216     <title>Usage of the debugger</title>
4217
4218     <para>A webservice debugger is included in the library to help during
4219     development and testing.</para>
4220
4221     <para>The interface should be self-explicative enough to need little
4222     documentation.</para>
4223
4224     <para><graphic align="center" fileref="debugger.gif"
4225     format="GIF" /></para>
4226
4227     <para>The most useful feature of the debugger is without doubt the "Show
4228     debug info" option. It allows to have a screen dump of the complete http
4229     communication between client and server, including the http headers as
4230     well as the request and response payloads, and is invaluable when
4231     troubleshooting problems with charset encoding, authentication or http
4232     compression.</para>
4233
4234     <para>The debugger can take advantage of the JSONRPC library extension, to
4235     allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
4236     visual editor to allow easy mouse-driven construction of the payload for
4237     remote methods. Both components have to be downloaded separately from the
4238     sourceforge.net web pages and copied to the debugger directory to enable
4239     the extra functionality:</para>
4240
4241     <para><itemizedlist>
4242         <listitem>
4243           <para>to enable jsonrpc functionality, download the PHP-XMLRPC
4244           EXTRAS package, and copy the file <filename>jsonrpc.inc</filename>
4245           either to the same directory as the debugger or somewhere in your
4246           php include path</para>
4247         </listitem>
4248       </itemizedlist><itemizedlist>
4249         <listitem>
4250           <para>to enable the visual value editing dialog, download the
4251           JS-XMLRPC library, and copy somewhere in the web root files
4252           <filename>visualeditor.php</filename>,
4253           <filename>visualeditor.css</filename> and the folders
4254           <filename>yui</filename> and <filename>img</filename>. Then edit the
4255           debugger file <filename>controller.php</filename> and set
4256           appropriately the variable <varname>$editorpath</varname>.</para>
4257         </listitem>
4258       </itemizedlist></para>
4259   </appendix>
4260 </book>
4261 <!-- Keep this comment at the end of the file
4262 Local variables:
4263 mode: sgml
4264 sgml-omittag:nil
4265 sgml-shorttag:t
4266 sgml-minimize-attributes:nil
4267 sgml-always-quote-attributes:t
4268 sgml-indent-step:2
4269 sgml-indent-data:t
4270 sgml-parent-document:nil
4271 sgml-exposed-tags:nil
4272 sgml-local-catalogs:nil
4273 sgml-local-ecat-files:nil
4274 sgml-namecase-general:t
4275 sgml-general-insert-case:lower
4276 End:
4277 -->