doc/xmlrpc_php.xml

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