--- /dev/null
+= 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. You can find the API documentation at link:$$http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html$$[http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html]
+
+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.
+
+The type i8 on the other hand is considered as a separate type.
+ Note that the library will never output integers as 'i8' on its own,
+ even when php is compiled in 64-bit mode.
+
+===== 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 < > ' " and
+ & All other characters outside of the ASCII range are
+ encoded using their character reference representation (e.g.
+ È 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, $xmlrpcI8 $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";
+$xmlrpcI8="i8";
+$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 '<' 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:
+-->
+++++++++++++++++++++++++++++++++++++++
git://git.onelab.eu / plcapi.git / blobdiff