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