doc/xmlrpc_php.xml

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