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