Move api docs to phpdoc (wip); fix wrong property name in Response class

[plcapi.git] / doc / manual / phpxmlrpc_manual.adoc

= XML-RPC for PHP
:revision: 4.0.0
:keywords: xmlrpc, xml, rpc, webservices, http
:toc: left
:imagesdir: images
:source-highlighter: highlightjs


[preface]
== Introduction

WARNING: THIS MANUAL HAS NOT YET BEEN UPDATED TO REFLECT ALL THE CHANGES WHICH HAVE MADE IN VERSION 4. DO NOT USE FOR NOW.

This collection of PHP classes provides a framework for writing XML-RPC clients and servers in PHP.

Main goals of the project are ease of use, flexibility and completeness.

The original author is Edd Dumbill of link:$$http://usefulinc.com/$$[Useful Information Company]. As of the 1.0 stable
    release, the project was opened to wider involvement and moved to
    link:$$http://phpxmlrpc.sourceforge.net/$$[SourceForge]; later, to link:$$https://github.com/gggeek/phpxmlrpc$$[Github]

XML-RPC is a format devised by link:$$http://www.userland.com/$$[Userland Software] for achieving remote procedure call
    via XML using HTTP as the transport. XML-RPC has its own web site, link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com]

A list of XML-RPC implementations for other languages such as Perl and Python can be found on the
    link:$$http://www.xmlrpc.com/$$[www.xmlrpc.com] site.

=== Acknowledgements

Daniel E. Baumann

James Bercegay

Leon Blackwell

Stephane Bortzmeyer

Daniel Convissor

Geoffrey T. Dairiki

Stefan Esser

James Flemer

Ernst de Haan

Tom Knight

Axel Kollmorgen

Peter Kocks

Daniel Krippner

{empty}S. Kuip

{empty}A. Lambert

Frederic Lecointre

Dan Libby

Arnaud Limbourg

Ernest MacDougal Campbell III

Lukasz Mach

Kjartan Mannes

Ben Margolin

Nicolay Mausz

Justin Miller

Jan Pfeifer

Giancarlo Pinerolo

Peter Russel

Jean-Jacques Sarton

Viliam Simko

Idan Sofer

Douglas Squirrel

Heiko Stübner

Anatoly Techtonik

Tommaso Trani

Eric van der Vlist

Christian Wenz

Jim Winstead

Przemyslaw Wroblewski

Bruno Zanetti Melotti


[[requirements]]
== System Requirements

The library has been designed with goals of flexibility and backward compatibility. As such, it supports a wide range of
    PHP installs. Note that not all features of the lib are available in every configuration.

The __minimum supported__ PHP version is 5.3.

If you wish to use HTTPS or HTTP 1.1 to communicate with remote servers, or to use NTLM authentication, you need the
    *curl* extension compiled into your PHP installation.

If you wish to receive XML-RPC requests or responses in any other character set than US-ASCII, ISO-8859-1 or UTF-8, you
    will need the *mbstring* extension compiled into your PHP installation.

The *xmlrpc* native extension is not required to be compiled into your PHP installation, but if it is, there will be no
    interference with the operation of this library.


[[manifest]]
== Files in the distribution

debugger/*:: a graphical debugger which can be used to test calls to xmlrpc servers

demo/*:: example code for implementing both xmlrpc client and server functionality

doc/*:: the documentation/ this manual, and the list of API changes between versions 3 and 4

extras/rsakey.pem:: A test certificate key for the SSL support, which can be used to generate dummy certificates. It has
    the passphrase "test."

extras/test.pl, extras/test.py:: Perl and Python programs to exercise server.php to test that some of the methods work.

extras/workspace.testPhpServer.fttb:: Frontier scripts to exercise the demo server. Thanks to Dave Winer for permission
    to include these. See link:$$http://www.xmlrpc.com/discuss/msgReader$853$$[Dave's announcement of these.]

lib/*:: a compatibility layer for applications which still rely on version 3 of the API

src/*:: the XML-RPC library classes. You can autoload these via Composer, or via a dedicated Autoloader class

tests/*:: the test suite for the library, written using PhpUnit, and the configuration to run it on Travis


[[bugs]]

== Known Bugs

Known bugs are tracked using the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[GitHub issue tracker]

== Known limitations

This started out as a bare framework. Many "nice" bits have been put in over time, but backwards compatibility has
    always taken precedence over API cleanups. As such, you might find some API choices questionable.

Specifically, very little type validation or coercion has been put in. PHP being a loosely-typed language, this is
    going to have to be done explicitly (in other words: you can call a lot of library functions passing them arguments
    of the wrong type and receive an error message only much further down the code, where it will be difficult to
    understand).

dateTime.iso8601 is supported opaquely. It can't be done natively as the XML-RPC specification explicitly forbids
    passing of timezone specifiers in ISO8601 format dates. You can, however, use the PhpXmlRpc\Helper\Date class to do
    the encoding and decoding for you.

Very little HTTP response checking is performed (e.g. HTTP redirects are not followed and the Content-Length HTTP
    header, mandated by the xml-rpc spec, is not validated); cookie support still involves quite a bit of coding on the
    part of the user.

Support for receiving from servers version 1 cookies (i.e. conforming to RFC 2965) is quite incomplete, and might cause
    unforeseen errors.


[[support]]

== Support


=== Online Support

XML-RPC for PHP is offered "as-is" without any warranty or commitment to support. However, informal advice and help is
    available via the XML-RPC for PHP website and mailing list.

* The __XML-RPC for PHP__ development is hosted on
    link:$$https://github.com/gggeek/phpxmlrpc$$[github.com/gggeek/phpxmlrpc]. Bugs, feature requests and patches can be
    posted to the link:$$https://github.com/gggeek/phpxmlrpc/issues$$[project's website].

* The __PHP XML-RPC interest mailing list__ is run by the original author. More details
    link:$$http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc$$[can be found here].


[[jellyfish]]

=== The Jellyfish Book

image::progxmlrpc.s.gif[The Jellyfish Book]
Together with Simon St.Laurent and Joe Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates on
    XML-RPC. It features a rather fetching jellyfish on the cover.

Complete details of the book are link:$$http://www.oreilly.com/catalog/progxmlrpc/$$[available from O'Reilly's web site.]

Edd is responsible for the chapter on PHP, which includes a worked example of creating a forum server, and hooking it up
    the O'Reilly's link:$$http://meerkat.oreillynet.com/$$[Meerkat] service in order to allow commenting on news stories
    from around the Web.

If you've benefited from the effort that has been put into writing this software, then please consider buying the book!


[[apidocs]]

== Class documentation


==== Notes on types

===== int

The type i4 is accepted as a synonym
          for int when creating xmlrpcval objects. The
          xml parsing code will always convert i4 to
          int: int is regarded
          by this implementation as the canonical name for this type.

===== base64

Base 64 encoding is performed transparently to the caller when
          using this type. Decoding is also transparent. Therefore you ought
          to consider it as a "binary" data type, for use when you want to
          pass data that is not 7-bit clean.

===== boolean

The php values ++true++ and
          ++1++ map to ++true++. All other
          values (including the empty string) are converted to
          ++false++.

===== string

Characters <, >;, ', ", &, are encoded using their
          entity reference as &lt; &gt; &apos; &quot; and
          &amp; All other characters outside of the ASCII range are
          encoded using their character reference representation (e.g.
          &#200 for é). The XML-RPC spec recommends only encoding
          ++< >++ but this implementation goes further,
          for reasons explained by link:$$http://www.w3.org/TR/REC-xml#syntax$$[the XML 1.0 recommendation]. In particular, using character reference
          representation has the advantage of producing XML that is valid
          independently of the charset encoding assumed.

===== null

There is no support for encoding ++null++
          values in the XML-RPC spec, but at least a couple of extensions (and
          many toolkits) do support it. Before using ++null++
          values in your messages, make sure that the responding party accepts
          them, and uses the same encoding convention (see ...).

[[xmlrpcval-creation]]

==== Xmlrpcval creation

The constructor is the normal way to create an
        xmlrpcval. The constructor can take these
        forms:

xmlrpcvalnew
            xmlrpcval xmlrpcvalnew
            xmlrpcval string $stringVal xmlrpcvalnew
            xmlrpcval mixed $scalarVal string$scalartyp xmlrpcvalnew
            xmlrpcval array $arrayVal string $arraytyp The first constructor creates an empty value, which must be
        altered using the methods addScalar,
        addArray or addStruct before
        it can be used.

The second constructor creates a simple string value.

The third constructor is used to create a scalar value. The
        second parameter must be a name of an XML-RPC type. Valid types are:
        "++int++", "++boolean++",
        "++string++", "++double++",
        "++dateTime.iso8601++", "++base64++" or
        "null".

Examples:

[source, php]
----

$myInt = new xmlrpcval(1267, "int");
$myString = new xmlrpcval("Hello, World!", "string");
$myBool = new xmlrpcval(1, "boolean");
$myString2 = new xmlrpcval(1.24, "string"); // note: this will serialize a php float value as xmlrpc string

----

The fourth constructor form can be used to compose complex
        XML-RPC values. The first argument is either a simple array in the
        case of an XML-RPC array or an associative
        array in the case of a struct. The elements of
        the array __must be xmlrpcval objects themselves__.

The second parameter must be either "++array++"
        or "++struct++".

Examples:

[source, php]
----

$myArray = new xmlrpcval(
  array(
    new xmlrpcval("Tom"),
    new xmlrpcval("Dick"),
    new xmlrpcval("Harry")
  ),
  "array");

// recursive struct
$myStruct = new xmlrpcval(
  array(
    "name" => new xmlrpcval("Tom", "string"),
    "age" => new xmlrpcval(34, "int"),
    "address" => new xmlrpcval(
      array(
        "street" => new xmlrpcval("Fifht Ave", "string"),
        "city" => new xmlrpcval("NY", "string")
      ),
      "struct")
  ),
  "struct");

----

See the file ++vardemo.php++ in this distribution
        for more examples.

[[xmlrpc-client]]

==== Xmlrpc-client creation

The constructor accepts one of two possible syntaxes:

xmlrpc_clientnew
            xmlrpc_clientstring$server_urlxmlrpc_clientnew
            xmlrpc_clientstring$server_pathstring$server_hostnameint$server_port80string$transport'http'Here are a couple of usage examples of the first form:


[source, php]
----

$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
$another_client = new xmlrpc_client("https://james:bond@secret.service.com:443/xmlrpcserver?agent=007");

----

The second syntax does not allow to express a username and
        password to be used for basic HTTP authorization as in the second
        example above, but instead it allows to choose whether xmlrpc calls
        will be made using the HTTP 1.0 or 1.1 protocol.

Here's another example client set up to query Userland's XML-RPC
        server at __betty.userland.com__:

[source, php]
----

$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);

----

The server_port parameter is optional,
        and if omitted will default to 80 when using HTTP and 443 when using
        HTTPS (see the <<xmlrpc-client-send>> method
        below).

The transport parameter is optional, and
        if omitted will default to 'http'. Allowed values are either
        'http', 'https' or
        'http11'. Its value can be overridden with every call
        to the send method. See the
        send method below for more details about the
        meaning of the different values.


[[xmlrpc-server]]

=== xmlrpc_server

The implementation of this class has been kept as simple to use as
      possible. The constructor for the server basically does all the work.
      Here's a minimal example:


[source, php]
----

  function foo ($xmlrpcmsg) {
    ...
    return new xmlrpcresp($some_xmlrpc_val);
  }

  class bar {
    function foobar($xmlrpcmsg) {
      ...
      return new xmlrpcresp($some_xmlrpc_val);
    }
  }

  $s = new xmlrpc_server(
    array(
      "examples.myFunc1" => array("function" => "foo"),
      "examples.myFunc2" => array("function" => "bar::foobar"),
    ));

----

This performs everything you need to do with a server. The single
      constructor argument is an associative array from xmlrpc method names to
      php function names. The incoming request is parsed and dispatched to the
      relevant php function, which is responsible for returning a
      xmlrpcresp object, that will be serialized back
      to the caller.


==== Method handler functions

Both php functions and class methods can be registered as xmlrpc
        method handlers.

The synopsis of a method handler function is:

xmlrpcresp $resp = function (xmlrpcmsg $msg)

No text should be echoed 'to screen' by the handler function, or
        it will break the xml response sent back to the client. This applies
        also to error and warning messages that PHP prints to screen unless
        the appropriate parameters have been set in the php.in file. Another
        way to prevent echoing of errors inside the response and facilitate
        debugging is to use the server SetDebug method with debug level 3 (see
        ...). Exceptions thrown duting execution of handler functions are
        caught by default and a XML-RPC error reponse is generated instead.
        This behaviour can be finetuned by usage of the
        exception_handling member variable (see
        ...).

Note that if you implement a method with a name prefixed by
        ++system.++ the handler function will be invoked by the
        server with two parameters, the first being the server itself and the
        second being the xmlrpcmsg object.

The same php function can be registered as handler of multiple
        xmlrpc methods.

Here is a more detailed example of what the handler function
        foo may do:


[source, php]
----

  function foo ($xmlrpcmsg) {
    global $xmlrpcerruser; // import user errcode base value

    $meth = $xmlrpcmsg->method(); // retrieve method name
    $par = $xmlrpcmsg->getParam(0); // retrieve value of first parameter - assumes at least one param received
    $val = $par->scalarval(); // decode value of first parameter - assumes it is a scalar value

    ...

    if ($err) {
      // this is an error condition
      return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
        "There's a problem, Captain");
    } else {
      // this is a successful value being returned
      return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
    }
  }

----

See __server.php__ in this distribution for
        more examples of how to do this.

Since release 2.0RC3 there is a new, even simpler way of
        registering php functions with the server. See section 5.7
        below


==== The dispatch map

The first argument to the xmlrpc_server
        constructor is an array, called the __dispatch map__.
        In this array is the information the server needs to service the
        XML-RPC methods you define.

The dispatch map takes the form of an associative array of
        associative arrays: the outer array has one entry for each method, the
        key being the method name. The corresponding value is another
        associative array, which can have the following members:


* ++function++ - this
            entry is mandatory. It must be either a name of a function in the
            global scope which services the XML-RPC method, or an array
            containing an instance of an object and a static method name (for
            static class methods the 'class::method' syntax is also
            supported).


* ++signature++ - this
            entry is an array containing the possible signatures (see <<signatures>>) for the method. If this entry is present
            then the server will check that the correct number and type of
            parameters have been sent for this method before dispatching
            it.


* ++docstring++ - this
            entry is a string containing documentation for the method. The
            documentation may contain HTML markup.


* ++$$signature_docs$$++ - this entry can be used
            to provide documentation for the single parameters. It must match
            in structure the 'signature' member. By default, only the
            documenting_xmlrpc_server class in the
            extras package will take advantage of this, since the
            "system.methodHelp" protocol does not support documenting method
            parameters individually.


* ++$$parameters_type$$++ - this entry can be used
            when the server is working in 'xmlrpcvals' mode (see ...) to
            define one or more entries in the dispatch map as being functions
            that follow the 'phpvals' calling convention. The only useful
            value is currently the string ++phpvals++.

Look at the __server.php__ example in the
        distribution to see what a dispatch map looks like.

[[signatures]]

==== Method signatures

A signature is a description of a method's return type and its
        parameter types. A method may have more than one signature.

Within a server's dispatch map, each method has an array of
        possible signatures. Each signature is an array of types. The first
        entry is the return type. For instance, the method
[source, php]
----
string examples.getStateName(int)

----

 has the signature
[source, php]
----
array($xmlrpcString, $xmlrpcInt)

----

 and, assuming that it is the only possible signature for the
        method, it might be used like this in server creation:
[source, php]
----

$findstate_sig = array(array($xmlrpcString, $xmlrpcInt));

$findstate_doc = 'When passed an integer between 1 and 51 returns the
name of a US state, where the integer is the index of that state name
in an alphabetic order.';

$s = new xmlrpc_server( array(
  "examples.getStateName" => array(
    "function" => "findstate",
    "signature" => $findstate_sig,
    "docstring" => $findstate_doc
  )));

----



Note that method signatures do not allow to check nested
        parameters, e.g. the number, names and types of the members of a
        struct param cannot be validated.

If a method that you want to expose has a definite number of
        parameters, but each of those parameters could reasonably be of
        multiple types, the array of acceptable signatures will easily grow
        into a combinatorial explosion. To avoid such a situation, the lib
        defines the global var $xmlrpcValue, which can be
        used in method signatures as a placeholder for 'any xmlrpc
        type':


[source, php]
----

$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));

$findstate_doc = 'Echoes back to the client the received value, regardless of its type';

$s = new xmlrpc_server( array(
  "echoBack" => array(
    "function" => "echoback",
    "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
    "docstring" => $echoback_doc
  )));

----

Methods system.listMethods,
        system.methodHelp,
        system.methodSignature and
        system.multicall are already defined by the
        server, and should not be reimplemented (see Reserved Methods
        below).


==== Delaying the server response

You may want to construct the server, but for some reason not
        fulfill the request immediately (security verification, for instance).
        If you omit to pass to the constructor the dispatch map or pass it a
        second argument of ++0++ this will have the desired
        effect. You can then use the service() method of
        the server class to service the request. For example:


[source, php]
----

$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request

// ... some code that does other stuff here

$s->service();

----

Note that the service method will print
        the complete result payload to screen and send appropriate HTTP
        headers back to the client, but also return the response object. This
        permits further manipulation of the response, possibly in combination
        with output buffering.

To prevent the server from sending HTTP headers back to the
        client, you can pass a second parameter with a value of
        ++TRUE++ to the service
        method. In this case, the response payload will be returned instead of
        the response object.

Xmlrpc requests retrieved by other means than HTTP POST bodies
        can also be processed. For example:


[source, php]
----

$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request

// ... some code that does other stuff here, including setting dispatch map into server object

$resp = $s->service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload

// ... some code that does other stuff with xml response $resp here

----


==== Modifying the server behaviour

A couple of methods / class variables are available to modify
        the behaviour of the server. The only way to take advantage of their
        existence is by usage of a delayed server response (see above)


===== setDebug()

This function controls weather the server is going to echo
          debugging messages back to the client as comments in response body.
          Valid values: 0,1,2,3, with 1 being the default. At level 0, no
          debug info is returned to the client. At level 2, the complete
          client request is added to the response, as part of the xml
          comments. At level 3, a new PHP error handler is set when executing
          user functions exposed as server methods, and all non-fatal errors
          are trapped and added as comments into the response.


===== allow_system_funcs

Default_value: TRUE. When set to FALSE, disables support for
          System.xxx functions in the server. It
          might be useful e.g. if you do not wish the server to respond to
          requests to System.ListMethods.


===== compress_response

When set to TRUE, enables the server to take advantage of HTTP
          compression, otherwise disables it. Responses will be transparently
          compressed, but only when an xmlrpc-client declares its support for
          compression in the HTTP headers of the request.

Note that the ZLIB php extension must be installed for this to
          work. If it is, compress_response will default to
          TRUE.


===== exception_handling

This variable controls the behaviour of the server when an
          exception is thrown by a method handler php function. Valid values:
          0,1,2, with 0 being the default. At level 0, the server catches the
          exception and return an 'internal error' xmlrpc response; at 1 it
          catches the exceptions and return an xmlrpc response with the error
          code and error message corresponding to the exception that was
          thron; at 2 = the exception is floated to the upper layers in the
          code


===== response_charset_encoding

Charset encoding to be used for response (only affects string
          values).

If it can, the server will convert the generated response from
          internal_encoding to the intended one.

Valid values are: a supported xml encoding (only UTF-8 and
          ISO-8859-1 at present, unless mbstring is enabled), null (leave
          charset unspecified in response and convert output stream to
          US_ASCII), 'default' (use xmlrpc library default as specified in
          xmlrpc.inc, convert output stream if needed), or 'auto' (use
          client-specified charset encoding or same as request if request
          headers do not specify it (unless request is US-ASCII: then use
          library default anyway).


==== Fault reporting

Fault codes for your servers should start at the value indicated
        by the global ++$xmlrpcerruser++ + 1.

Standard errors returned by the server include:

++1++ Unknown method:: Returned if the server was asked to dispatch a method it
              didn't know about

++2++ Invalid return payload:: This error is actually generated by the client, not
              server, code, but signifies that a server returned something it
              couldn't understand. A more detailed error report is sometimes
              added onto the end of the phrase above.

++3++ Incorrect parameters:: This error is generated when the server has signature(s)
              defined for a method, and the parameters passed by the client do
              not match any of signatures.

++4++ Can't introspect: method unknown:: This error is generated by the builtin
              system.* methods when any kind of
              introspection is attempted on a method undefined by the
              server.

++5++ Didn't receive 200 OK from remote server:: This error is generated by the client when a remote server
              doesn't return HTTP/1.1 200 OK in response to a request. A more
              detailed error report is added onto the end of the phrase
              above.

++6++ No data received from server:: This error is generated by the client when a remote server
              returns HTTP/1.1 200 OK in response to a request, but no
              response body follows the HTTP headers.

++7++ No SSL support compiled in:: This error is generated by the client when trying to send
              a request with HTTPS and the CURL extension is not available to
              PHP.

++8++ CURL error:: This error is generated by the client when trying to send
              a request with HTTPS and the HTTPS communication fails.

++9-14++ multicall errors:: These errors are generated by the server when something
              fails inside a system.multicall request.

++100-++ XML parse errors:: Returns 100 plus the XML parser error code for the fault
              that occurred. The faultString returned
              explains where the parse error was in the incoming XML
              stream.


==== 'New style' servers

In the same spirit of simplification that inspired the
        xmlrpc_client::return_type class variable, a new
        class variable has been added to the server class:
        functions_parameters_type. When set to 'phpvals',
        the functions registered in the server dispatch map will be called
        with plain php values as parameters, instead of a single xmlrpcmsg
        instance parameter. The return value of those functions is expected to
        be a plain php value, too. An example is worth a thousand
        words:
[source, php]
----

  function foo($usr_id, $out_lang='en') {
    global $xmlrpcerruser;

    ...

    if ($someErrorCondition)
      return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
    else
      return array(
        'name' => 'Joe',
        'age' => 27,
        'picture' => new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
      );
  }

  $s = new xmlrpc_server(
    array(
      "examples.myFunc" => array(
        "function" => "bar::foobar",
        "signature" => array(
          array($xmlrpcString, $xmlrpcInt),
          array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
        )
      )
    ), false);
  $s->functions_parameters_type = 'phpvals';
  $s->service();

----

There are a few things to keep in mind when using this
        simplified syntax:

to return an xmlrpc error, the method handler function must
        return an instance of xmlrpcresp. The only
        other way for the server to know when an error response should be
        served to the client is to throw an exception and set the server's
        exception_handling memeber var to 1;

to return a base64 value, the method handler function must
        encode it on its own, creating an instance of an xmlrpcval
        object;

the method handler function cannot determine the name of the
        xmlrpc method it is serving, unlike standard handler functions that
        can retrieve it from the message object;

when receiving nested parameters, the method handler function
        has no way to distinguish a php string that was sent as base64 value
        from one that was sent as a string value;

this has a direct consequence on the support of
        system.multicall: a method whose signature contains datetime or base64
        values will not be available to multicall calls;

last but not least, the direct parsing of xml to php values is
        much faster than using xmlrpcvals, and allows the library to handle
        much bigger messages without allocating all available server memory or
        smashing PHP recursive call stack.


[[globalvars]]

== Global variables

Many global variables are defined in the xmlrpc.inc file. Some of
    those are meant to be used as constants (and modifying their value might
    cause unpredictable behaviour), while some others can be modified in your
    php scripts to alter the behaviour of the xml-rpc client and
    server.


=== "Constant" variables


==== $xmlrpcerruser

$xmlrpcerruser800The minimum value for errors reported by user
        implemented XML-RPC servers. Error numbers lower than that are
        reserved for library usage.


==== $xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble, $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray, $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull

For convenience the strings representing the XML-RPC types have
        been encoded as global variables:
[source, php]
----

$xmlrpcI4="i4";
$xmlrpcInt="int";
$xmlrpcBoolean="boolean";
$xmlrpcDouble="double";
$xmlrpcString="string";
$xmlrpcDateTime="dateTime.iso8601";
$xmlrpcBase64="base64";
$xmlrpcArray="array";
$xmlrpcStruct="struct";
$xmlrpcValue="undefined";
$xmlrpcNull="null";

----

==== $xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr, $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities, $xmlEntities, $xmlrpcs_capabilities

Reserved for internal usage.


=== Variables whose value can be modified

[[xmlrpc-defencoding]]

==== xmlrpc_defencoding

$xmlrpc_defencoding"UTF8"This variable defines the character set encoding that will be
        used by the xml-rpc client and server to decode the received messages,
        when a specific charset declaration is not found (in the messages sent
        non-ascii chars are always encoded using character references, so that
        the produced xml is valid regardless of the charset encoding
        assumed).

Allowed values: ++"UTF8"++,
        ++"ISO-8859-1"++, ++"ASCII".++

Note that the appropriate RFC actually mandates that XML
        received over HTTP without indication of charset encoding be treated
        as US-ASCII, but many servers and clients 'in the wild' violate the
        standard, and assume the default encoding is UTF-8.


==== xmlrpc_internalencoding

$xmlrpc_internalencoding"ISO-8859-1"This variable defines the character set encoding
        that the library uses to transparently encode into valid XML the
        xml-rpc values created by the user and to re-encode the received
        xml-rpc values when it passes them to the PHP application. It only
        affects xml-rpc values of string type. It is a separate value from
        xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
        on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
        character set used internally by PHP (unless you are running an
        MBString-enabled installation), so you should change it only in
        special situations, if e.g. the string values exchanged in the xml-rpc
        messages are directly inserted into / fetched from a database
        configured to return UTF8 encoded strings to PHP. Example
        usage:

[source, php]
----

<?php

include('xmlrpc.inc');
$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
$v = new xmlrpcval('κόÏ\83με'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'

----

==== xmlrpcName

$xmlrpcName"XML-RPC for PHP"The string representation of the name of the XML-RPC
        for PHP library. It is used by the client for building the User-Agent
        HTTP header that is sent with every request to the server. You can
        change its value if you need to customize the User-Agent
        string.


==== xmlrpcVersion

$xmlrpcVersion"2.2"The string representation of the version number of
        the XML-RPC for PHP library in use. It is used by the client for
        building the User-Agent HTTP header that is sent with every request to
        the server. You can change its value if you need to customize the
        User-Agent string.


==== xmlrpc_null_extension

When set to TRUE, the lib will enable
        support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as
        per the extension to the standard proposed here. This means that
        <NIL> and <EX:NIL/> tags received will be parsed as valid
        xmlrpc, and the corresponding xmlrpcvals will return "null" for
        scalarTyp().


==== xmlrpc_null_apache_encoding

When set to ++TRUE++, php NULL values encoded
        into xmlrpcval objects get serialized using the
        ++<EX:NIL/>++ tag instead of
        ++<NIL/>++. Please note that both forms are
        always accepted as input regardless of the value of this
        variable.


[[helpers]]

== Helper functions

XML-RPC for PHP contains some helper functions which you can use to
    make processing of XML-RPC requests easier.


=== Date functions

The XML-RPC specification has this to say on dates:

[quote]
____
[[wrap_xmlrpc_method]]
Don't assume a timezone. It should be
        specified by the server in its documentation what assumptions it makes
        about timezones.
____


Unfortunately, this means that date processing isn't
      straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
      use the timezone specifier.

We strongly recommend that in every case where you pass dates in
      XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
      languages include routines for handling GMT times natively, and you
      won't have to translate between timezones.

For more information about dates, see link:$$http://www.uic.edu/year2000/datefmt.html$$[ISO 8601: The Right Format for Dates], which has a handy link to a PDF of the ISO
      8601 specification. Note that XML-RPC uses exactly one of the available
      representations: CCYYMMDDTHH:MM:SS.

[[iso8601encode]]

==== iso8601_encode

stringiso8601_encodestring$time_tint$utc0Returns an ISO 8601 formatted date generated from the UNIX
        timestamp $time_t, as returned by the PHP
        function time().

The argument $utc can be omitted, in
        which case it defaults to ++0++. If it is set to
        ++1++, then the function corrects the time passed in
        for UTC. Example: if you're in the GMT-6:00 timezone and set
        $utc, you will receive a date representation
        six hours ahead of your local time.

The included demo program __vardemo.php__
        includes a demonstration of this function.

[[iso8601decode]]

==== iso8601_decode

intiso8601_decodestring$isoStringint$utc0Returns a UNIX timestamp from an ISO 8601 encoded time and date
        string passed in. If $utc is
        ++1++ then $isoString is assumed
        to be in the UTC timezone, and thus the result is also UTC: otherwise,
        the timezone is assumed to be your local timezone and you receive a
        local timestamp.

[[arrayuse]]

=== Easy use with nested PHP values

Dan Libby was kind enough to contribute two helper functions that
      make it easier to translate to and from PHP values. This makes it easier
      to deal with complex structures. At the moment support is limited to
      int, double, string,
      array, datetime and struct
      datatypes; note also that all PHP arrays are encoded as structs, except
      arrays whose keys are integer numbers starting with 0 and incremented by
      1.

These functions reside in __xmlrpc.inc__.

[[phpxmlrpcdecode]]

==== php_xmlrpc_decode

mixedphp_xmlrpc_decodexmlrpcval$xmlrpc_valarray$optionsarrayphp_xmlrpc_decodexmlrpcmsg$xmlrpcmsg_valstring$optionsReturns a native PHP value corresponding to the values found in
        the xmlrpcval $xmlrpc_val,
        translated into PHP types. Base-64 and datetime values are
        automatically decoded to strings.

In the second form, returns an array containing the parameters
        of the given
        xmlrpcmsg_val, decoded
        to php types.

The options parameter is optional. If
        specified, it must consist of an array of options to be enabled in the
        decoding process. At the moment the only valid option are
        decode_php_objs and
        ++$$dates_as_objects$$++. When the first is set, php
        objects that have been converted to xml-rpc structs using the
        php_xmlrpc_encode function and a corresponding
        encoding option will be converted back into object values instead of
        arrays (provided that the class definition is available at
        reconstruction time). When the second is set, XML-RPC datetime values
        will be converted into native dateTime objects
        instead of strings.

____WARNING__:__ please take
        extreme care before enabling the decode_php_objs
        option: when php objects are rebuilt from the received xml, their
        constructor function will be silently invoked. This means that you are
        allowing the remote end to trigger execution of uncontrolled PHP code
        on your server, opening the door to code injection exploits. Only
        enable this option when you have complete trust of the remote
        server/client.

Example:
[source, php]
----

// wrapper to expose an existing php function as xmlrpc method handler
function foo_wrapper($m)
{
  $params = php_xmlrpc_decode($m);
  $retval = call_user_func_array('foo', $params);
  return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
}

$s = new xmlrpc_server(array(
   "examples.myFunc1" => array(
     "function" => "foo_wrapper",
     "signatures" => ...
  )));

----

[[phpxmlrpcencode]]

==== php_xmlrpc_encode

xmlrpcvalphp_xmlrpc_encodemixed$phpvalarray$optionsReturns an xmlrpcval object populated with the PHP
        values in $phpval. Works recursively on arrays
        and objects, encoding numerically indexed php arrays into array-type
        xmlrpcval objects and non numerically indexed php arrays into
        struct-type xmlrpcval objects. Php objects are encoded into
        struct-type xmlrpcvals, excepted for php values that are already
        instances of the xmlrpcval class or descendants thereof, which will
        not be further encoded. Note that there's no support for encoding php
        values into base-64 values. Encoding of date-times is optionally
        carried on on php strings with the correct format.

The options parameter is optional. If
        specified, it must consist of an array of options to be enabled in the
        encoding process. At the moment the only valid options are
        encode_php_objs, ++$$null_extension$$++
        and auto_dates.

The first will enable the creation of 'particular' xmlrpcval
        objects out of php objects, that add a "php_class" xml attribute to
        their serialized representation. This attribute allows the function
        php_xmlrpc_decode to rebuild the native php objects (provided that the
        same class definition exists on both sides of the communication). The
        second allows to encode php ++NULL++ values to the
        ++<NIL/>++ (or
        ++<EX:NIL>++, see ...) tag. The last encodes any
        string that matches the ISO8601 format into an XML-RPC
        datetime.

Example:
[source, php]
----

// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
$val = php_xmlrpc_encode(array(
  'first struct_element: an int' => 666,
  'second: an array' => array ('apple', 'orange', 'banana'),
  'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
  'fourth: a datetime' => '20060107T01:53:00'
  ), array('auto_dates'));

----

==== php_xmlrpc_decode_xml

xmlrpcval | xmlrpcresp |
            xmlrpcmsgphp_xmlrpc_decode_xmlstring$xmlarray$optionsDecodes the xml representation of either an xmlrpc request,
        response or single value, returning the corresponding php-xmlrpc
        object, or ++FALSE++ in case of an error.

The options parameter is optional. If
        specified, it must consist of an array of options to be enabled in the
        decoding process. At the moment, no option is supported.

Example:
[source, php]
----

$text = '<value><array><data><value>Hello world</value></data></array></value>';
$val = php_xmlrpc_decode_xml($text);
if ($val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';

----

=== Automatic conversion of php functions into xmlrpc methods (and vice versa)

For the extremely lazy coder, helper functions have been added
      that allow to convert a php function into an xmlrpc method, and a
      remotely exposed xmlrpc method into a local php function - or a set of
      methods into a php class. Note that these comes with many caveat.


==== wrap_xmlrpc_method

stringwrap_xmlrpc_method$client$methodname$extra_optionsstringwrap_xmlrpc_method$client$methodname$signum$timeout$protocol$funcnameGiven an xmlrpc server and a method name, creates a php wrapper
        function that will call the remote method and return results using
        native php types for both params and results. The generated php
        function will return an xmlrpcresp object for failed xmlrpc
        calls.

The second syntax is deprecated, and is listed here only for
        backward compatibility.

The server must support the
        system.methodSignature xmlrpc method call for
        this function to work.

The client param must be a valid
        xmlrpc_client object, previously created with the address of the
        target xmlrpc server, and to which the preferred communication options
        have been set.

The optional parameters can be passed as array key,value pairs
        in the extra_options param.

The signum optional param has the purpose
        of indicating which method signature to use, if the given server
        method has multiple signatures (defaults to 0).

The timeout and
        protocol optional params are the same as in the
        xmlrpc_client::send() method.

If set, the optional new_function_name
        parameter indicates which name should be used for the generated
        function. In case it is not set the function name will be
        auto-generated.

If the ++$$return_source$$++ optional parameter is
        set, the function will return the php source code to build the wrapper
        function, instead of evaluating it (useful to save the code and use it
        later as stand-alone xmlrpc client).

If the ++$$encode_php_objs$$++ optional parameter is
        set, instances of php objects later passed as parameters to the newly
        created function will receive a 'special' treatment that allows the
        server to rebuild them as php objects instead of simple arrays. Note
        that this entails using a "slightly augmented" version of the xmlrpc
        protocol (ie. using element attributes), which might not be understood
        by xmlrpc servers implemented using other libraries.

If the ++$$decode_php_objs$$++ optional parameter is
        set, instances of php objects that have been appropriately encoded by
        the server using a coordinate option will be deserialized as php
        objects instead of simple arrays (the same class definition should be
        present server side and client side).

__Note that this might pose a security risk__,
        since in order to rebuild the object instances their constructor
        method has to be invoked, and this means that the remote server can
        trigger execution of unforeseen php code on the client: not really a
        code injection, but almost. Please enable this option only when you
        trust the remote server.

In case of an error during generation of the wrapper function,
        FALSE is returned, otherwise the name (or source code) of the new
        function.

Known limitations: server must support
        system.methodsignature for the wanted xmlrpc
        method; for methods that expose multiple signatures, only one can be
        picked; for remote calls with nested xmlrpc params, the caller of the
        generated php function has to encode on its own the params passed to
        the php function if these are structs or arrays whose (sub)members
        include values of type base64.

Note: calling the generated php function 'might' be slow: a new
        xmlrpc client is created on every invocation and an xmlrpc-connection
        opened+closed. An extra 'debug' param is appended to the parameter
        list of the generated php function, useful for debugging
        purposes.

Example usage:


[source, php]
----

$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');

$function = wrap_xmlrpc_method($client, 'examples.getStateName');

if (!$function)
  die('Cannot introspect remote method');
else {
  $stateno = 15;
  $statename = $function($a);
  if (is_a($statename, 'xmlrpcresp')) // call failed
  {
    echo 'Call failed: '.$statename->faultCode().'. Calling again with debug on';
    $function($a, true);
  }
  else
    echo "OK, state nr. $stateno is $statename";
}

----

[[wrap_php_function]]

==== wrap_php_function

arraywrap_php_functionstring$funcnamestring$wrapper_function_namearray$extra_optionsGiven a user-defined PHP function, create a PHP 'wrapper'
        function that can be exposed as xmlrpc method from an xmlrpc_server
        object and called from remote clients, and return the appropriate
        definition to be added to a server's dispatch map.

The optional $wrapper_function_name
        specifies the name that will be used for the auto-generated
        function.

Since php is a typeless language, to infer types of input and
        output parameters, it relies on parsing the javadoc-style comment
        block associated with the given function. Usage of xmlrpc native types
        (such as datetime.dateTime.iso8601 and base64) in the docblock @param
        tag is also allowed, if you need the php function to receive/send data
        in that particular format (note that base64 encoding/decoding is
        transparently carried out by the lib, while datetime vals are passed
        around as strings).

Known limitations: only works for
        user-defined functions, not for PHP internal functions (reflection
        does not support retrieving number/type of params for those); the
        wrapped php function will not be able to programmatically return an
        xmlrpc error response.

If the ++$$return_source$$++ optional parameter is
        set, the function will return the php source code to build the wrapper
        function, instead of evaluating it (useful to save the code and use it
        later in a stand-alone xmlrpc server). It will be in the stored in the
        ++source++ member of the returned array.

If the ++$$suppress_warnings$$++ optional parameter
        is set, any runtime warning generated while processing the
        user-defined php function will be catched and not be printed in the
        generated xml response.

If the extra_options array contains the
        ++$$encode_php_objs$$++ value, wrapped functions returning
        php objects will generate "special" xmlrpc responses: when the xmlrpc
        decoding of those responses is carried out by this same lib, using the
        appropriate param in php_xmlrpc_decode(), the objects will be
        rebuilt.

In short: php objects can be serialized, too (except for their
        resource members), using this function. Other libs might choke on the
        very same xml that will be generated in this case (i.e. it has a
        nonstandard attribute on struct element tags)

If the ++$$decode_php_objs$$++ optional parameter is
        set, instances of php objects that have been appropriately encoded by
        the client using a coordinate option will be deserialized and passed
        to the user function as php objects instead of simple arrays (the same
        class definition should be present server side and client
        side).

__Note that this might pose a security risk__,
        since in order to rebuild the object instances their constructor
        method has to be invoked, and this means that the remote client can
        trigger execution of unforeseen php code on the server: not really a
        code injection, but almost. Please enable this option only when you
        trust the remote clients.

Example usage:


[source, php]
----
/**
* State name from state number decoder. NB: do NOT remove this comment block.
* @param integer $stateno the state number
* @return string the name of the state (or error description)
*/
function findstate($stateno)
{
  global $stateNames;
  if (isset($stateNames[$stateno-1]))
  {
    return $stateNames[$stateno-1];
  }
  else
  {
    return "I don't have a state for the index '" . $stateno . "'";
  }
}

// wrap php function, build xmlrpc server
$methods = array();
$findstate_sig = wrap_php_function('findstate');
if ($findstate_sig)
  $methods['examples.getStateName'] = $findstate_sig;
$srv = new xmlrpc_server($methods);

----

[[deprecated]]

=== Functions removed from the library

The following two functions have been deprecated in version 1.1 of
      the library, and removed in version 2, in order to avoid conflicts with
      the EPI xml-rpc library, which also defines two functions with the same
      names.

To ease the transition to the new naming scheme and avoid breaking
      existing implementations, the following scheme has been adopted:

* If EPI-XMLRPC is not active in the current PHP installation,
            the constant `XMLRPC_EPI_ENABLED` will be set to
            '0'


* If EPI-XMLRPC is active in the current PHP installation, the
            constant `XMLRPC_EPI_ENABLED` will be set to
            '1'



The following documentation is kept for historical
      reference:

[[xmlrpcdecode]]

==== xmlrpc_decode

mixedx mlrpc_decode xmlrpcval $xmlrpc_val Alias for php_xmlrpc_decode.

[[xmlrpcencode]]

==== xmlrpc_encode

xmlrpcval xmlrpc_encode mixed $phpvalAlias for php_xmlrpc_encode.

[[debugging]]

=== Debugging aids

==== xmlrpc_debugmsg

void xmlrpc_debugmsgstring$debugstringSends the contents of $debugstring in XML
        comments in the server return payload. If a PHP client has debugging
        turned on, the user will be able to see server debug
        information.

Use this function in your methods so you can pass back
        diagnostic information. It is only available from
        __xmlrpcs.inc__.


[[reserved]]

== Reserved methods

In order to extend the functionality offered by XML-RPC servers
    without impacting on the protocol, reserved methods are supported in this
    release.

All methods starting with system. are
    considered reserved by the server. PHP for XML-RPC itself provides four
    special methods, detailed in this chapter.

Note that all server objects will automatically respond to clients
    querying these methods, unless the property
    allow_system_funcs has been set to
    false before calling the
    service() method. This might pose a security risk
    if the server is exposed to public access, e.g. on the internet.


=== system.getCapabilities


=== system.listMethods

This method may be used to enumerate the methods implemented by
      the XML-RPC server.

The system.listMethods method requires no
      parameters. It returns an array of strings, each of which is the name of
      a method implemented by the server.

[[sysmethodsig]]

=== system.methodSignature

This method takes one parameter, the name of a method implemented
      by the XML-RPC server.

It returns an array of possible signatures for this method. A
      signature is an array of types. The first of these types is the return
      type of the method, the rest are parameters.

Multiple signatures (i.e. overloading) are permitted: this is the
      reason that an array of signatures are returned by this method.

Signatures themselves are restricted to the top level parameters
      expected by a method. For instance if a method expects one array of
      structs as a parameter, and it returns a string, its signature is simply
      "string, array". If it expects three integers, its signature is "string,
      int, int, int".

For parameters that can be of more than one type, the "undefined"
      string is supported.

If no signature is defined for the method, a not-array value is
      returned. Therefore this is the way to test for a non-signature, if
      $resp below is the response object from a method
      call to system.methodSignature:

[source, php]
----

$v = $resp->value();
if ($v->kindOf() != "array") {
  // then the method did not have a signature defined
}

----

See the __introspect.php__ demo included in this
      distribution for an example of using this method.

[[sysmethhelp]]

=== system.methodHelp

This method takes one parameter, the name of a method implemented
      by the XML-RPC server.

It returns a documentation string describing the use of that
      method. If no such string is available, an empty string is
      returned.

The documentation string may contain HTML markup.

=== system.multicall

This method takes one parameter, an array of 'request' struct
      types. Each request struct must contain a
      methodName member of type string and a
      params member of type array, and corresponds to
      the invocation of the corresponding method.

It returns a response of type array, with each value of the array
      being either an error struct (containing the faultCode and faultString
      members) or the successful response value of the corresponding single
      method call.


[[examples]]

== Examples

The best examples are to be found in the sample files included with
    the distribution. Some are included here.

[[statename]]

=== XML-RPC client: state name query

Code to get the corresponding state name from a number (1-50) from
      the demo server available on SourceForge

[source, php]
----

  $m = new xmlrpcmsg('examples.getStateName',
    array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
  $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
  $r = $c->send($m);
  if (!$r->faultCode()) {
      $v = $r->value();
      print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
        htmlentities($v->scalarval()) . "<BR>";
      print "<HR>I got this value back<BR><PRE>" .
        htmlentities($r->serialize()) . "</PRE><HR>\n";
  } else {
      print "Fault <BR>";
      print "Code: " . htmlentities($r->faultCode()) . "<BR>" .
            "Reason: '" . htmlentities($r->faultString()) . "'<BR>";
  }

----

=== Executing a multicall call

To be documented...


[[faq]]

[qanda]
== Frequently Asked Questions

==== How to send custom XML as payload of a method call::

Unfortunately, at the time the XML-RPC spec was designed, support
      for namespaces in XML was not as ubiquitous as it is now. As a
      consequence, no support was provided in the protocol for embedding XML
      elements from other namespaces into an xmlrpc request.

To send an XML "chunk" as payload of a method call or response,
      two options are available: either send the complete XML block as a
      string xmlrpc value, or as a base64 value. Since the '<' character in
      string values is encoded as '&lt;' in the xml payload of the method
      call, the XML string will not break the surrounding xmlrpc, unless
      characters outside of the assumed character set are used. The second
      method has the added benefits of working independently of the charset
      encoding used for the xml to be transmitted, and preserving exactly
      whitespace, whilst incurring in some extra message length and cpu load
      (for carrying out the base64 encoding/decoding).


==== Is there any limitation on the size of the requests / responses that can be successfully sent?::

Yes. But I have no hard figure to give; it most likely will depend
      on the version of PHP in usage and its configuration.

Keep in mind that this library is not optimized for speed nor for
      memory usage. Better alternatives exist when there are strict
      requirements on throughput or resource usage, such as the php native
      xmlrpc extension (see the PHP manual for more information).

Keep in mind also that HTTP is probably not the best choice in
      such a situation, and XML is a deadly enemy. CSV formatted data over
      socket would be much more efficient.

If you really need to move a massive amount of data around, and
      you are crazy enough to do it using phpxmlrpc, your best bet is to
      bypass usage of the xmlrpcval objects, at least in the decoding phase,
      and have the server (or client) object return to the calling function
      directly php values (see xmlrpc_client::return_type
      and xmlrpc_server::functions_parameters_type for more
      details).


==== My server (client) returns an error whenever the client (server) returns accented characters

To be documented...


==== How to enable long-lasting method calls

To be documented...


==== My client returns "XML-RPC Fault #2: Invalid return payload: enable debugging to examine incoming payload": what should I do?

The response you are seeing is a default error response that the
      client object returns to the php application when the server did not
      respond to the call with a valid xmlrpc response.

The most likely cause is that you are not using the correct URL
      when creating the client object, or you do not have appropriate access
      rights to the web page you are requesting, or some other common http
      misconfiguration.

To find out what the server is really returning to your client,
      you have to enable the debug mode of the client, using
      $client->setdebug(1);


==== How can I save to a file the xml of the xmlrpc responses received from servers?

If what you need is to save the responses received from the server
      as xml, you have two options:

1- use the serialize() method on the response object.


[source, php]
----

$resp = $client->send($msg);
if (!$resp->faultCode())
  $data_to_be_saved = $resp->serialize();

----

Note that this will not be 100% accurate, since the xml generated
      by the response object can be different from the xml received,
      especially if there is some character set conversion involved, or such
      (eg. if you receive an empty string tag as <string/>, serialize()
      will output <string></string>), or if the server sent back
      as response something invalid (in which case the xml generated client
      side using serialize() will correspond to the error response generated
      internally by the lib).

2 - set the client object to return the raw xml received instead
      of the decoded objects:


[source, php]
----

$client = new xmlrpc_client($url);
$client->return_type = 'xml';
$resp = $client->send($msg);
if (!$resp->faultCode())
  $data_to_be_saved = $resp->value();

----

Note that using this method the xml response response will not be
      parsed at all by the library, only the http communication protocol will
      be checked. This means that xmlrpc responses sent by the server that
      would have generated an error response on the client (eg. malformed xml,
      responses that have faultcode set, etc...) now will not be flagged as
      invalid, and you might end up saving not valid xml but random
      junk...


==== Can I use the ms windows character set?

If the data your application is using comes from a Microsoft
      application, there are some chances that the character set used to
      encode it is CP1252 (the same might apply to data received from an
      external xmlrpc server/client, but it is quite rare to find xmlrpc
      toolkits that encode to CP1252 instead of UTF8). It is a character set
      which is "almost" compatible with ISO 8859-1, but for a few extra
      characters.

PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
      The net result of this situation is that those extra characters will not
      be properly encoded, and will be received at the other end of the
      XML-RPC transmission as "garbled data". Unfortunately the library cannot
      provide real support for CP1252 because of limitations in the PHP 4 xml
      parser. Luckily, we tried our best to support this character set anyway,
      and, since version 2.2.1, there is some form of support, left commented
      in the code.

To properly encode outgoing data that is natively in CP1252, you
      will have to uncomment all relative code in the file
      __xmlrpc.inc__ (you can search for the string "1252"),
      then set ++$$$GLOBALS['xmlrpc_internalencoding']='CP1252';$$++
      Please note that all incoming data will then be fed to your application
      as UTF-8 to avoid any potential data loss.


==== Does the library support using cookies / http sessions?

In short: yes, but a little coding is needed to make it
      happen.

The code below uses sessions to e.g. let the client store a value
      on the server and retrieve it later.

[source, php]
----

$resp = $client->send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
if (!$resp->faultCode())
{
  $cookies = $resp->cookies();
  if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
  {
    $session_id = $cookies['PHPSESSID']['value'];

    // do some other stuff here...

    $client->setcookie('PHPSESSID', $session_id);
    $val = $client->send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
  }
}

----

Server-side sessions are handled normally like in any other
      php application. Please see the php manual for more information about
      sessions.

NB: unlike web browsers, not all xmlrpc clients support usage of
      http cookies. If you have troubles with sessions and control only the
      server side of the communication, please check with the makers of the
      xmlrpc client in use.


[[integration]]

[appendix]
== Integration with the PHP xmlrpc extension

To be documented more...

In short: for the fastest execution possible, you can enable the php
    native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
    following code snippet gives an example of such integration


[source, php]
----

/*** client side ***/
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');

// tell the client to return raw xml as response value
$c->return_type = 'xml';

// let the native xmlrpc extension take care of encoding request parameters
$r = $c->send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));

if ($r->faultCode())
  // HTTP transport error
  echo 'Got error '.$r->faultCode();
else
{
  // HTTP request OK, but XML returned from server not parsed yet
  $v = xmlrpc_decode($r->value());
  // check if we got a valid xmlrpc response from server
  if ($v === NULL)
    echo 'Got invalid response';
  else
  // check if server sent a fault response
  if (xmlrpc_is_fault($v))
    echo 'Got xmlrpc fault '.$v['faultCode'];
  else
    echo'Got response: '.htmlentities($v);
}

----


[[substitution]]

[appendix]
== Substitution of the PHP xmlrpc extension

Yet another interesting situation is when you are using a ready-made
    php application, that provides support for the XMLRPC protocol via the
    native php xmlrpc extension, but the extension is not available on your
    php install (e.g. because of shared hosting constraints).

Since version 2.1, the PHP-XMLRPC library provides a compatibility
    layer that aims to be 100% compliant with the xmlrpc extension API. This
    means that any code written to run on the extension should obtain the
    exact same results, albeit using more resources and a longer processing
    time, using the PHP-XMLRPC library and the extension compatibility module.
    The module is part of the EXTRAS package, available as a separate download
    from the sourceforge.net website, since version 0.2


[[enough]]

[appendix]
== 'Enough of xmlrpcvals!': new style library usage

To be documented...

In the meantime, see docs about xmlrpc_client::return_type and
    xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
    php_xmlrpc_decode and php_xmlrpc_decode_xml


[[debugger]]

[appendix]
== Usage of the debugger

A webservice debugger is included in the library to help during
    development and testing.

The interface should be self-explicative enough to need little
    documentation.

image::debugger.gif[,,,,align="center"]

The most useful feature of the debugger is without doubt the "Show
    debug info" option. It allows to have a screen dump of the complete http
    communication between client and server, including the http headers as
    well as the request and response payloads, and is invaluable when
    troubleshooting problems with charset encoding, authentication or http
    compression.

The debugger can take advantage of the JSONRPC library extension, to
    allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
    visual editor to allow easy mouse-driven construction of the payload for
    remote methods. Both components have to be downloaded separately from the
    sourceforge.net web pages and copied to the debugger directory to enable
    the extra functionality:


* to enable jsonrpc functionality, download the PHP-XMLRPC
          EXTRAS package, and copy the file __jsonrpc.inc__
          either to the same directory as the debugger or somewhere in your
          php include path


* to enable the visual value editing dialog, download the
          JS-XMLRPC library, and copy somewhere in the web root files
          __visualeditor.php__,
          __visualeditor.css__ and the folders
          __yui__ and __img__. Then edit the
          debugger file __controller.php__ and set
          appropriately the variable $editorpath.


[[news]]

[appendix]

== Whats's new

CAUTION: not all items the following list have (yet) been fully documented, and some might not be present in any other
    chapter in the manual. To find a more detailed description of new functions and methods please take a look at the
    source code of the library, which is quite thoroughly commented in phpdoc form.

=== 4.0.0

* new: introduction of namespaces and full OOP.
+
All php classes have been renamed and moved to separate files.
+
Class autoloading can now be done in accord with the PSR-4 standard.
+
All global variables and global functions have been removed.
+
Iterating over xmlrpc value objects is now easier thank to support for ArrayAccess and Traversable interfaces.
+
Backward compatibility is maintained via _lib/xmlrpc.inc_, _lib/xmlrpcs.inc_ and _lib/xmlrpc_wrappers.inc_.
    For more details, head on to doc/api_changes_v4.md

* changed: the default character encoding delivered from the library to your code is now utf8.
  It can be changed at any time setting a value to `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`

* improved: the library now accepts requests/responses sent using other character sets than UTF-8/ISO-8859-1/ASCII.
  This only works when the mbstring php extension is enabled.

* improved: no need to call anymore `$client->setSSLVerifyHost(2)` to silence a curl warning when using https
  with recent curl builds

* improved: the xmlrpcval class now supports the interfaces `Countable` and `IteratorAggregate`

* improved: a specific option allows users to decide the version of SSL to use for https calls.
  This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
  and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)

* improved: the function `wrap_php_function()` now can be used to wrap closures (it is now a method btw)

* improved: all _wrap_something()_ functions now return a closure by default instead of a function name

* improved: debug messages are not html-escaped any more when executing from the command line

* improved: the library is now tested using Travis ( https://travis-ci.org/ ).
  Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
  is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services

* improved: phpunit is now installed via composer, not bundled anymore

* improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for

* improved: the test suite has basic checks for the debugger and demo files

* improved: more tests in the test suite

* fixed: the server would not reset the user-set debug messages between subsequent `service()` calls

* fixed: the server would not reset previous php error handlers when an exception was thrown by user code and
  exception_handling set to 2

* fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
  prolog only

* fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
  prolog only

* fixed: the function `decode_xml()` would not decode an xml with character set declaration in the xml prolog

* fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name

* fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
  It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name

* fixed: the debugger would generate a bad payload via the 'load method synopsis' button for signatures containing NULL
  or undefined parameters

* fixed: the debugger would generate a bad payload via the 'load method synopsis' button for methods with multiple
  signatures

* improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service

* improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
  previously those messages would just disappear (this is visible e.g. in the debugger)

* changed: debug info handling
    - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
    - at debug level 1, curl communication info are not dumped to screen
    - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads

* improved: makefiles have been replaced with a php_based pakefile

* improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
  with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
  to look at than previous versions

* improved: all php code is now formatted according to the PSR-2 standard

=== 3.0.0

__Note:__ this is the last release of the library that will support PHP 5.1 and up. Future releases will target php 5.3
    as minimum supported version.

* when using curl and keepalive, reset curl handle if we did not get back an http 200 response (eg a 302)

* omit port on http 'Host' header if it is 80

* test suite allows interrogating https servers ignoring their certs

* method `setAcceptedCompression` was failing to disable reception of compressed responses if the client supported them

=== 3.0.0 beta

This is the first release of the library to only support PHP 5. Some legacy code has been removed, and support for
    features such as exceptions and dateTime objects introduced.

The "beta" tag is meant to indicate the fact that the refactoring has been more widespread than in precedent releases
    and that more changes are likely to be introduced with time - the library is still considered to be production
    quality.

* improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
    etc...

* improved: add support for the `<ex:nil>` tag used by the apache library, both in input and output

* improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval

* improved: add support for timestamps as parameter for constructor of xmlrpcval

* improved: add option `dates_as_objects` to `php_xmlrpc_decode` to return dateTime objects for xmlrpc datetimes

* improved: add new method `SetCurlOptions` to xmrlpc_client to allow extra flexibility in tweaking http config, such as
    explicitly binding to an ip address

* improved: add new method `SetUserAgent` to xmrlpc_client to to allow having different user-agent http headers

* improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
    server is in 'phpvals' mode

* improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
    with an added option

* improved: catch exceptions thrown during execution of php functions exposed as methods by the server

* fixed: bad encoding if same object is encoded twice using `php_xmlrpc_encode`

=== 2.2.2

__Note:__ this is the last release of the library that will support PHP 4. Future releases (if any) should target
    php 5.0 as minimum supported version.

* fixed: encoding of utf-8 characters outside of the BMP plane

* fixed: character set declarations surrounded by double quotes were not recognized in http headers

* fixed: be more tolerant in detection of charset in http headers

* fixed: fix detection of zlib.output_compression

* fixed: use `feof()` to test if socket connections are to be closed instead of the number of bytes read (rare bug when
    communicating with some servers)

* fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
    comma

* fixed: improve robustness of the debugger when parsing weird results from non-compliant servers

* php warning when receiving `false` in a bool value

* improved: allow the add_to_map server method to add docs for single params too

* improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and even
    whole classes

=== 2.2.1

* fixed: work aroung bug in php 5.2.2 which broke support of `HTTP_RAW_POST_DATA`

* fixed: is_dir parameter of `setCaCertificate()` method is reversed

* fixed: a php warning in xmlrpc_client creator method

* fixed: parsing of `1e+1` as valid float

* fixed: allow errorlevel 3 to work when prev. error handler was a static method

* fixed: usage of `client::setcookie()` for multiple cookies in non-ssl mode

* improved: support for CP1252 charset is not part or the library but almost possible

* improved: more info when curl is enabled and debug mode is on

=== 2.2

* fixed: debugger errors on php installs with `magic_quotes_gpc` on

* fixed: support for https connections via proxy

* fixed: `wrap_xmlrpc_method()` generated code failed to properly encode php objects

* improved: slightly faster encoding of data which is internally UTF-8

* improved: debugger always generates a `null` id for jsonrpc if user omits it

* new: debugger can take advantage of a graphical value builder (it has to be downloaded separately, as part of jsxmlrpc
    package. See Appendix D for more details)

* new: support for the `<NIL/>` xmlrpc extension. see below for more details

* new: server support for the `system.getCapabilities` xmlrpc extension

* new: `wrap_xmlrpc_method`, `wrap_xmlrpc_method()` accepts two new options: debug and return_on_fault

=== 2.1

* The wrap_php_function and wrap_xmlrpc_method functions have been moved out of the base library file _xmlrpc.inc_
    into a file of their own: _xmlrpc_wrappers.php_. You will have to include() / require() it in your scripts if
    you have been using those functions.
    For increased security, the automatic rebuilding of php object instances out ofreceived xmlrpc structs in
    `wrap_xmlrpc_method()` has been disabled (but it can be optionally re-enabled).
    Both `wrap_php_function()` and `wrap_xmlrpc_method()` functions accept many more options to fine tune their behaviour,
    including one to return the php code to be saved and later used as standalone php script

* The constructor of xmlrpcval() values has seen some internal changes, and it will not throw a php warning anymore when
    invoked using an unknown xmlrpc type: the error will only be written to php error log. Also
    `new xmlrpcval('true', 'boolean')` is not supported anymore

* The new function `php_xmlrpc_decode_xml()` will take the xml representation of either an xmlrpc request, response or
    single value and return the corresponding php-xmlrpc object instance

* A new function `wrap_xmlrpc_server()` has been added, to wrap all (or some) of the methods exposed by a remote xmlrpc
    server into a php class

* A new file has been added: _verify_compat.php_, to help users diagnose the level of compliance of their php
    installation with the library

* Restored compatibility with php 4.0.5 (for those poor souls still stuck on it)

* Method `xmlrpc_server->service()` now returns a value: either the response payload or xmlrpcresp object instance

* Method `xmlrpc_server->add_to_map()` now accepts xmlrpc methods with no param definitions

* Documentation for single parameters of exposed methods can be added to the dispatch map (and turned into html docs in
    conjunction with a future release of the 'extras' package)

* Full response payload is saved into xmlrpcresp object for further debugging

* The debugger can now generate code that wraps a remote method into a php function (works for jsonrpc, too); it also
    has better support for being activated via a single GET call (e.g. for integration into other tools)

* Stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected (double `data` element inside
    `array` and `struct`/`array` after scalar inside `value` element)

* More logging of errors in a lot of situations

* Javadoc documentation of lib files (almost) complete

* Many performance tweaks and code cleanups, plus the usual crop of bugs fixed (see NEWS file for complete list of bugs)

* Lib internals have been modified to provide better support for grafting extra functionality on top of it. Stay tuned
    for future releases of the EXTRAS package (or go read Appendix B)...

=== 2.0 final

* Added to the client class the possibility to use Digest and NTLM authentication methods (when using the CURL library)
    for connecting to servers and NTLM for connecting to proxies

* Added to the client class the possibility to specify alternate certificate files/directories for authenticating the
    peer with when using HTTPS communication

* Reviewed all examples and added a new demo file, containing a proxy to forward xmlrpc requests to other servers
    (useful e.g. for ajax coding)

* The debugger has been upgraded to reflect the new client capabilities

* All known bugs have been squashed, and the lib is more tolerant than ever of commonly-found mistakes

=== 2.0 Release candidate 3

* Added to server class the property functions_parameters_type, that allows the server to register plain php functions
    as xmlrpc methods (i.e. functions that do not take an xmlrpcmsg object as unique param)

* let server and client objects serialize calls using a specified character set encoding for the produced xml instead of
    US-ASCII (ISO-8859-1 and UTF-8 supported)

* let `php_xmlrpc_decode` accept xmlrpcmsg objects as valid input

* 'class::method' syntax is now accepted in the server dispatch map

* `xmlrpc_clent::SetDebug()` accepts integer values instead of a boolean value, with debugging level 2 adding to the
    information printed to screen the complete client request

=== 2.0 Release candidate 2

* Added a new property of the client object: `xmlrpc_client->return_type`, indicating whether calls to the
    send() method will return xmlrpcresp objects whose value() is an xmlrpcval object, a php value (automatically
    decoded) or the raw xml received from the server.

* Added in the extras dir. two new library files: _jsonrpc.inc_ and _jsonrpcs.inc_ containing new classes that
    implement support for the json-rpc protocol (alpha quality code)

* Added a new client method: `setKey($key, $keypass)` to be used in HTTPS connections

* Added a new file containing some benchmarks in the testsuite directory

=== 2.0 Release candidate 1

* Support for HTTP proxies (new method: `xmlrpc_client::setProxy()`)

* Support HTTP compression of both requests and responses.
    Clients can specify what kind of compression they accept for responses between deflate/gzip/any, and whether to
    compress the requests.
    Servers by default compress responses to clients that explicitly declare support for compression (new methods:
    `xmlrpc_client::setAcceptedCompression()`, `xmlrpc_client::setRequestCompression()`).
    Note that the ZLIB php extension needs to be enabled in PHP to support compression.

* Implement HTTP 1.1 connections, but only if CURL is enabled (added an extra parameter to
    `xmlrpc_client::xmlrpc_client` to set the desired HTTP protocol at creation time and a new supported value for
    the last parameter of `xmlrpc_client::send`, which now can be safely omitted if it has been specified at
    creation time).
+
With PHP versions greater than 4.3.8 keep-alives are enabled by default for HTTP 1.1 connections. This should yield
    faster execution times when making multiple calls in sequence to the same xml-rpc server from a single client.

* Introduce support for cookies.
    Cookies to be sent to the server with a request can be set using `xmlrpc_client::setCookie()`, while cookies
    received from the server are found in ++xmlrpcresp::cookies()++. It is left to the user to check for validity of
    received cookies and decide whether they apply to successive calls or not.

* Better support for detecting different character set encodings of xml-rpc requests and responses: both client and
    server objects will correctly detect the charset encoding of received xml, and use an appropriate xml parser.
+
Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.

* Added one new xmlrpcmsg constructor syntax, allowing usage of a single string with the complete URL of the target
    server

* Convert xml-rpc boolean values into native php values instead of 0 and 1

* Force the `php_xmlrpc_encode` function to properly encode numerically indexed php arrays into xml-rpc arrays
    (numerically indexed php arrays always start with a key of 0 and increment keys by values of 1)

* Prevent the `php_xmlrpc_encode` function from further re-encoding any objects of class ++xmlrpcval++ that
    are passed to it. This allows to call the function with arguments consisting of mixed php values / xmlrpcval objects

* Allow a server to NOT respond to system.* method calls (setting the `$server->allow_system_funcs` property).

* Implement a new xmlrpcval method to determine if a value of type struct has a member of a given name without having to
    loop trough all members: `xmlrpcval::structMemExists()`

* Expand methods `xmlrpcval::addArray`, `addScalar` and `addStruct` allowing extra php values to be added to
    xmlrpcval objects already formed.

* Let the `xmlrpc_client::send` method accept an XML string for sending instead of an xmlrpcmsg object, to
    facilitate debugging and integration with the php native xmlrpc extension

* Extend the `php_xmlrpc_encode` and `php_xmlrpc_decode` functions to allow serialization and rebuilding of
    PHP objects. To successfully rebuild a serialized object, the object class must be defined in the deserializing end
    of the transfer. Note that object members of type resource will be deserialized as NULL values.
+
Note that his has been implemented adding a "php_class" attribute to xml representation of xmlrpcval of STRUCT type,
    which, strictly speaking, breaks the xml-rpc spec. Other xmlrpc implementations are supposed to ignore such an
    attribute (unless they implement a brain-dead custom xml parser...), so it should be safe enabling it in
    heterogeneous environments. The activation of this feature is done by usage of an option passed as second parameter
    to both `php_xmlrpc_encode` and `php_xmlrpc_decode`.

* Extend the `php_xmlrpc_encode` function to allow automatic serialization of iso8601-conforming php strings as
    datetime.iso8601 xmlrpcvals, by usage of an optional parameter

* Added an automatic stub code generator for converting xmlrpc methods to php functions and vice-versa.
+
This is done via two new functions: `wrap_php_function` and `wrap_xmlrpc_method`, and has many caveats,
    with php being a typeless language and all...

* Allow object methods to be used in server dispatch map

* Added a complete debugger solution, in the __debugger__ folder

* Added configurable server-side debug messages, controlled by the new method `xmlrpc_server::SetDebug()`.
    At level 0, no debug messages are sent to the client; level 1 is the same as the old behaviour; at level 2 a lot
    more info is echoed back to the client, regarding the received call; at level 3 all warnings raised during server
    processing are trapped (this prevents breaking the xml to be echoed back to the client) and added to the debug info
    sent back to the client

* New XML parsing code, yields smaller memory footprint and faster execution times, not to mention complete elimination
    of the dreaded __eval()__ construct, so prone to code injection exploits

* Rewritten most of the error messages, making text more explicative

++++++++++++++++++++++++++++++++++++++
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-namecase-general:t
sgml-general-insert-case:lower
End:
-->
++++++++++++++++++++++++++++++++++++++