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