From bbc4dfe531c9f8a4e9d784c721a6c1d64cc3a45f Mon Sep 17 00:00:00 2001 From: ggiunta Date: Mon, 16 Mar 2009 22:04:14 +0000 Subject: [PATCH] - prepare for release of ver. 2.2.2 git-svn-id: https://svn.code.sf.net/p/phpxmlrpc/code/trunk/xmlrpc@4 013ecfd8-0664-425d-a759-9c98391dc3f9 --- NEWS | 18 + doc/xmlrpc_php.xml | 8189 ++++++++++++++++++++++---------------------- lib/xmlrpc.inc | 2 +- 3 files changed, 4134 insertions(+), 4075 deletions(-) diff --git a/NEWS b/NEWS index fb02483..709b1fd 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,21 @@ +XML-RPC for PHP version 2.2.2 - 2008/03/16 + +This release corrects all bugs that have been reported and sucesfully reproduced since +version 2.2.1. +Regardless of the intimitading message about dropping PHP 4 support, it still does +support that ancient, broken and insecure platform. + +* fixed: php warning when receiving 'false' in a bool value +* fixed: improve robustness of the debugger when parsing weird results from non-compliant servers +* fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses comma +* 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: be more tolerant in detection of charset in http headers +* fixed: fix encoding of UTF8 chars outside of the BMP plane +* fixed: fix detection of zlib.output_compression +* 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 + + XML-RPC for PHP version 2.2.1 - 2008/03/06 This release corrects all bugs that have been reported and sucesfully reproduced. diff --git a/doc/xmlrpc_php.xml b/doc/xmlrpc_php.xml index 1b97c88..a1c2b10 100644 --- a/doc/xmlrpc_php.xml +++ b/doc/xmlrpc_php.xml @@ -1,4074 +1,4115 @@ - - - - - - XML-RPC for PHP - - version 2.2.2 - - - XXX YY, 2008 - - - - Edd - - Dumbill - - - - Gaetano - - Giunta - - - - Miles - - Lott - - - - Justin R. - - Miller - - - - Andres - - Salomon - - - - - 1999,2000,2001 - - Edd Dumbill, Useful Information Company - - - - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - - - Redistributions of source code must retain the above - copyright notice, this list of conditions and the following - disclaimer. - - - - Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - - - Neither the name of the "XML-RPC for PHP" nor the names of - its contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - - - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, - BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE - REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - - - - Introduction - - XML-RPC is a format devised by Userland Software for achieving - remote procedure call via XML using HTTP as the transport. XML-RPC has its - own web site, www.xmlrpc.com - - 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 Useful Information Company. As of the - 1.0 stable release, the project has been opened to wider involvement and - moved to SourceForge. - - A list of XML-RPC implementations for other languages such as Perl - and Python can be found on the 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 - - S. Kuip - - A. Lambert - - Dan Libby - - Arnaud Limbourg - - Ernest MacDougal Campbell III - - Lukasz Mach - - Kjartan Mannes - - Ben Margolin - - Nicolay Mausz - - Justin Miller - - Jan Pfeifer - - Giancarlo Pinerolo - - Peter Russel - - Viliam Simko - - Douglas Squirrel - - Idan Sofer - - Anatoly Techtonik - - Eric van der Vlist - - Christian Wenz - - Jim Winstead - - Przemyslaw Wroblewski - - - - - What's new - - Note: 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 javadoc-like form. - - - 2.2.2 - - - - 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 - - - - - - 2.2.1 - - Note: this is the last release of the library - that will support PHP 4. Future releases (if any) will target php 5.0 as - minimum supported version. - - - - 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() - 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.inc. 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 of received 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 file: - 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... - - With PHP versions lesser than 5.0.3 wrapping of php functions - into xmlrpc methods is not supported yet. - - - - 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 - - - - - - - System Requirements - - The library has been designed with goals of scalability 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 - 4.2. - - A compatibility layer is provided that allows the code to run on PHP - 4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest - you upgrade as soon as possible. - - Automatic generation of xml-rpc methods from php functions is only - supported with PHP version 5.0.3 and later (note that the lib will - generate some warnings with PHP 5 in strict error reporting mode). - - If you wish to use SSL or HTTP 1.1 to communicate with remote - servers, you need the "curl" extension compiled into your PHP - installation. This is available in PHP 4.0.2 and greater, although 4.0.6 - has a bug preventing SSL working, and versions prior to 4.3.8 do not - support streamlining multiple requests using HTTP Keep-Alive. - - 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. - - - - Files in the distribution - - - - lib/xmlrpc.inc - - - the XML-RPC classes. include() this in - your PHP files to use the classes. - - - - - lib/xmlrpcs.inc - - - the XML-RPC server class. include() this - in addition to xmlrpc.inc to get server functionality - - - - - lib/xmlrpc_wrappers.inc - - - helper functions to "automagically" convert plain php - functions to xmlrpc services and vice versa - - - - - lib/compat/array_key_exists.php, lib/compat/is_a.php, - lib/compat/is_scalar.php, lib/compat/var_export.php, - lib/compat/vesrions_compare.php - - - compatibility functions: these files implement the - compatibility layer needed to run the library with PHP versions 4.0 - and 4.1 - - - - - demo/server/proxy.php - - - a sample server implementing xmlrpc proxy - functionality. - - - - - demo/server/server.php - - - a sample server hosting various demo functions, as well as a - full suite of functions used for interoperability testing. It is - used by testsuite.php (see below) for unit testing the library, and - is not to be copied literally into your production servers - - - - - demo/client/client.php, demo/client/agesort.php, - demo/client/which.php - - - client code to exercise some of the functions in server.php, - including the interopEchoTests.whichToolkit - method. - - - - - demo/client/wrap.php - - - client code to illustrate 'wrapping' of remote methods into - php functions. - - - - - demo/client/introspect.php - - - client code to illustrate usage of introspection capabilities - offered by server.php. - - - - - demo/client/mail.php - - - client code to illustrate usage of an xmlrpc-to-email gateway - using Dave Winer's XML-RPC server at userland.com. - - - - - demo/client/zopetest.php - - - example client code that queries an xmlrpc server built in - Zope. - - - - - demo/vardemo.php - - - examples of how to construct xmlrpcval types - - - - - demo/demo1.txt, demo/demo2.txt, demo/demo3.txt - - - XML-RPC responses captured in a file for testing purposes (you - can use these to test the - xmlrpcmsg->parseResponse() method). - - - - - demo/server/discuss.php, - demo/client/comment.php - - - Software used in the PHP chapter of to provide a comment server and allow the - attachment of comments to stories from Meerkat's data store. - - - - - test/testsuite.php, test/parse_args.php - - - A unit test suite for this software package. If you do - development on this software, please consider submitting tests for - this suite. - - - - - test/benchmark.php - - - A (very limited) benchmarking suite for this software package. - If you do development on this software, please consider submitting - benchmarks for this suite. - - - - - test/phpunit.php, test/PHPUnit/*.php - - - An (incomplete) version PEAR's unit test framework for PHP. - The complete package can be found at http://pear.php.net/package/PHPUnit - - - - - test/verify_compat.php - - - Script designed to help the user to verify the level of - compatibility of the library with the current php install - - - - - 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 Dave's - announcement of these. - - - - - extras/rsakey.pem - - - A test certificate key for the SSL support, which can be used - to generate dummy certificates. It has the passphrase "test." - - - - - - - Known bugs and limitations - - This started out as a bare framework. Many "nice" bits haven't been - put in yet. 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 and functions - 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. - - If a specific character set encoding other than US-ASCII, ISO-8859-1 - or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request - or response messages then it will be ignored for the moment, and the - content will be parsed as if it had been encoded using the charset defined - by - - Very large floating point numbers are serialized using exponential - notation, even though the spec explicitly forbids this behaviour. This - will not be a problem if this library is used on both ends of the - communication, but might cause problems with other implementations. - - Support for receiving from servers version 1 cookies (i.e. - conforming to RFC 2965) is quite incomplete, and might cause unforeseen - errors. - - A PHP warning will be generated in many places when using - xmlrpc.inc and xmlrpcs.inc with - PHP 5 in strict error reporting mode. The simplest workaround to this - problem is to lower the error_reporting level in - php.ini. - - - - 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 and from - XML-RPC.com. - - - - The XML-RPC for PHP development is hosted - on phpxmlrpc.sourceforge.net. - Bugs, feature requests and patches can be posted to the project's - website. - - - - The PHP XML-RPC interest mailing list is - run by the author. More details can be - found here. - - - - For more general XML-RPC questions, there is a Yahoo! Groups - XML-RPC mailing - list. - - - - The XML-RPC.com discussion - group is a useful place to get help with using XML-RPC. This group - is also gatewayed into the Yahoo! Groups mailing list. - - - - - - 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 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 - 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! - - - - - Class documentation - - - xmlrpcval - - This is where a lot of the hard work gets done. This class enables - the creation and encapsulation of values for XML-RPC. - - Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 - before reading on as it will make things clearer. - - The xmlrpcval class can store arbitrarily - complicated values using the following types: i4 int boolean - string double dateTime.iso8601 base64 array struct. You should - refer to the spec for - more information on what each of these types mean. - - - 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 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. - - - - - 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". - - Examples: - - -$myInt = new xmlrpcvalue(1267, "int"); -$myString = new xmlrpcvalue("Hello, World!", "string"); -$myBool = new xmlrpcvalue(1, "boolean"); -$myString2 = new xmlrpcvalue(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: - - -$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. - - - - Methods - - - addScalar - - - - intaddScalar - - string$stringVal - - - - intaddScalar - - mixed$scalarVal - - string$scalartyp - - - - If $val is an empty - xmlrpcval this method makes it a scalar - value, and sets that value. - - If $val is already a scalar value, then - no more scalars can be added and 0 is - returned. - - If $val is an xmlrpcval of type array, - the php value $scalarval is added as its last - element. - - If all went OK, 1 is returned, otherwise - 0. - - - - addArray - - - - intaddArray - - array$arrayVal - - - - The argument is a simple (numerically indexed) array. The - elements of the array must be - xmlrpcval objects - themselves. - - Turns an empty xmlrpcval into an - array with contents as specified by - $arrayVal. - - If $val is an xmlrpcval of type array, - the elements of $arrayVal are appended to the - existing ones. - - See the fourth constructor form for more information. - - If all went OK, 1 is returned, otherwise - 0. - - - - addStruct - - - - intaddStruct - - array$assocArrayVal - - - - The argument is an associative array. The elements of the - array must be xmlrpcval objects - themselves. - - Turns an empty xmlrpcval into a - struct with contents as specified by - $assocArrayVal. - - If $val is an xmlrpcval of type struct, - the elements of $arrayVal are merged with the - existing ones. - - See the fourth constructor form for more information. - - If all went OK, 1 is returned, otherwise - 0. - - - - kindOf - - - - stringkindOf - - - - - - Returns a string containing "struct", "array" or "scalar" - describing the base type of the value. If it returns "undef" it - means that the value hasn't been initialised. - - - - serialize - - - - stringserialize - - - - - - Returns a string containing the XML-RPC representation of this - value. - - - - scalarVal - - - - mixedscalarVal - - - - - - If $val->kindOf() == "scalar", this - method returns the actual PHP-language value of the scalar (base 64 - decoding is automatically handled here). - - - - scalarTyp - - - - stringscalarTyp - - - - - - If $val->kindOf() == "scalar", this - method returns a string denoting the type of the scalar. As - mentioned before, i4 is always coerced to - int. - - - - arrayMem - - - - xmlrpcvalarrayMem - - int$n - - - - If $val->kindOf() == "array", returns - the $nth element in the array represented by - the value $val. The value returned is an - xmlrpcval object. - - -// iterating over values of an array object -for ($i = 0; $i < $val->arraySize(); $i++) -{ - $v = $val->arrayMem($i); - echo "Element $i of the array is of type ".$v->kindOf(); -} - - - - - arraySize - - - - intarraySize - - - - - - If $val is an - array, returns the number of elements in that - array. - - - - structMem - - - - xmlrpcvalstructMem - - string$memberName - - - - If $val->kindOf() == "struct", returns - the element called $memberName from the - struct represented by the value $val. The - value returned is an xmlrpcval object. - - - - structEach - - - - arraystructEach - - - - - - Returns the next (key, value) pair from the struct, when - $val is a struct. - $value is an xmlrpcval itself. See also . - - -// iterating over all values of a struct object -$val->structreset(); -while (list($key, $v) = $val->structEach()) -{ - echo "Element $key of the struct is of type ".$v->kindOf(); -} - - - - - structReset - - - - voidstructReset - - - - - - Resets the internal pointer for - structEach() to the beginning of the struct, - where $val is a struct. - - - - structMemExists - - - - boolstructMemExsists - - string$memberName - - - - Returns TRUE or - FALSE depending on whether a member of the - given name exists in the struct. - - - - - - xmlrpcmsg - - This class provides a representation for a request to an XML-RPC - server. A client sends an xmlrpcmsg to a server, - and receives back an xmlrpcresp (see ). - - - Creation - - The constructor takes the following forms: - - - - xmlrpcmsgnew - xmlrpcmsg - - string$methodName - - array$parameterArraynull - - - - Where methodName is a string indicating - the name of the method you wish to invoke, and - parameterArray is a simple php - Array of xmlrpcval - objects. Here's an example message to the US state - name server: - - -$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); - - - This example requests the name of state number 23. For more - information on xmlrpcval objects, see . - - Note that the parameterArray parameter is - optional and can be omitted for methods that take no input parameters - or if you plan to add parameters one by one. - - - - Methods - - - addParam - - - - booladdParam - - xmlrpcval$xmlrpcVal - - - - Adds the xmlrpcval - xmlrpcVal to the parameter list for this - method call. Returns TRUE or FALSE on error. - - - - getNumParams - - - - intgetNumParams - - - - - - Returns the number of parameters attached to this - message. - - - - getParam - - - - xmlrpcvalgetParam - - int$n - - - - Gets the nth parameter in the message - (with the index zero-based). Use this method in server - implementations to retrieve the values sent by the client. - - - - method - - - - stringmethod - - - - - - stringmethod - - string$methName - - - - Gets or sets the method contained in the XML-RPC - message. - - - - parseResponse - - - - xmlrpcrespparseResponse - - string$xmlString - - - - Given an incoming XML-RPC server response contained in the - string $xmlString, this method constructs an - xmlrpcresp response object and returns it, - setting error codes as appropriate (see ). - - This method processes any HTTP/MIME headers it finds. - - - - parseResponseFile - - - - xmlrpcrespparseResponseFile - - file handle - resource$fileHandle - - - - Given an incoming XML-RPC server response on the open file - handle fileHandle, this method reads all the - data it finds and passes it to - parseResponse. - - This method is useful to construct responses from pre-prepared - files (see files demo1.txt, demo2.txt, demo3.txt - in this distribution). It processes any HTTP headers it finds, and - does not close the file handle. - - - - serialize - - - - string - serialize - - - - - - Returns the an XML string representing the XML-RPC - message. - - - - - - xmlrpc_client - - This is the basic class used to represent a client of an XML-RPC - server. - - - Creation - - The constructor accepts one of two possible syntaxes: - - - - xmlrpc_clientnew - xmlrpc_client - - string$server_url - - - - xmlrpc_clientnew - xmlrpc_client - - string$server_path - - string$server_hostname - - int$server_port80 - - string$transport'http' - - - - Here are a couple of usage examples of the first form: - - -$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php"); -$another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/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: - - -$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 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. - - - - Methods - - This class supports the following methods. - - - send - - This method takes the forms: - - - - xmlrpcrespsend - - xmlrpcmsg$xmlrpc_message - - int$timeout - - string$transport - - - - arraysend - - array$xmlrpc_messages - - int$timeout - - string$transport - - - - xmlrpcrespsend - - string$xml_payload - - int$timeout - - string$transport - - - - Where xmlrpc_message is an instance of - xmlrpcmsg (see ), - and response is an instance of - xmlrpcresp (see ). - - If xmlrpc_messages is an array of - message instances, responses will be an array of - response instances. The client will try to make use of a single - system.multicall xml-rpc method call to forward to the - server all the messages in a single HTTP round trip, unless - $client->no_multicall has been previously set to - TRUE (see the multicall method below), in which case - many consecutive xmlrpc requests will be sent. - - The third syntax allows to build by hand (or any other means) - a complete xmlrpc request message, and send it to the server. - xml_payload should be a string containing the - complete xml representation of the request. It is e.g. useful when, - for maximal speed of execution, the request is serialized into a - string using the native php xmlrpc functions (see the php manual on - xmlrpc). - - The timeout is optional, and will be - set to 0 (wait for platform-specific predefined - timeout) if omitted. This timeout value is passed to - fsockopen(). It is also used for detecting - server timeouts during communication (i.e. if the server does not - send anything to the client for timeout - seconds, the connection will be closed). - - The transport parameter is optional, - and if omitted will default to the transport set using instance - creator or 'http' if omitted. The only other valid values are - 'https', which will use an SSL HTTP connection to connect to the - remote server, and 'http11'. Note that your PHP must have the "curl" - extension compiled in order to use both these features. Note that - when using SSL you should normally set your port number to 443, - unless the SSL server you are contacting runs at any other - port. - - - PHP 4.0.6 has a bug which prevents SSL working. - - - In addition to low-level errors, the XML-RPC server you were - querying may return an error in the - xmlrpcresp object. See for details of how to handle these - errors. - - - - multiCall - - This method takes the form: - - - - arraymultiCall - - array$messages - - int$timeout - - string$transport - - bool$fallback - - - - This method is used to boxcar many method calls in a single - xml-rpc request. It will try first to make use of the - system.multicall xml-rpc method call, and fall back to - executing many separate requests if the server returns any - error. - - msgs is an array of - xmlrpcmsg objects (see ), and response is an - array of xmlrpcresp objects (see ). - - The timeout and - transport parameters are optional, and behave - as in the send method above. - - The fallback parameter is optional, and - defaults to TRUE. When set to - FALSE it will prevent the client to try using - many single method calls in case of failure of the first multicall - request. It should be set only when the server is known to support - the multicall extension. - - - - setAcceptedCompression - - - - voidsetAcceptedCompression - - string$compressionmethod - - - - This method defines whether the client will accept compressed - xml payload forming the bodies of the xmlrpc responses received from - servers. Note that enabling reception of compressed responses merely - adds some standard http headers to xmlrpc requests. It is up to the - xmlrpc server to return compressed responses when receiving such - requests. Allowed values for - compressionmethod are: 'gzip', 'deflate', - 'any' or null (with any meaning either gzip or deflate). - - This requires the "zlib" extension to be enabled in your php - install. If it is, by default xmlrpc_client - instances will enable reception of compressed content. - - - - setCaCertificate - - - - voidsetCaCertificate - - string$certificate - - bool$is_dir - - - - This method sets an optional certificate to be used in - SSL-enabled communication to validate a remote server with (when the - server_method is set to 'https' in the - client's construction or in the send method and - SetSSLVerifypeer has been set to - TRUE). - - The certificate parameter must be the - filename of a PEM formatted certificate, or a directory containing - multiple certificate files. The is_dir - parameter defaults to FALSE, set it to - TRUE to specify that - certificate indicates a directory instead of - a single file. - - This requires the "curl" extension to be compiled into your - installation of PHP. For more details see the man page for the - curl_setopt function. - - - - setCertificate - - - - voidsetCertificate - - string$certificate - - string$passphrase - - - - This method sets the optional certificate and passphrase used - in SSL-enabled communication with a remote server (when the - server_method is set to 'https' in the - client's construction or in the send method). - - The certificate parameter must be the - filename of a PEM formatted certificate. The - passphrase parameter must contain the - password required to use the certificate. - - This requires the "curl" extension to be compiled into your - installation of PHP. For more details see the man page for the - curl_setopt function. - - Note: to retrieve information about the client certificate on - the server side, you will need to look into the environment - variables which are set up by the webserver. Different webservers - will typically set up different variables. - - - - setCookie - - - - voidsetCookie - - string$name - - string$value - - string$path - - string$domain - - int$port - - - - This method sets a cookie that will be sent to the xmlrpc - server along with every further request (useful e.g. for keeping - session info outside of the xml-rpc payload). - - $value is optional, and defaults to - null. - - $path, $domain and $port are optional, - and will be omitted from the cookie header if unspecified. Note that - setting any of these values will turn the cookie into a 'version 1' - cookie, that might not be fully supported by the server (see RFC2965 - for more details). - - - - setCredentials - - - - voidsetCredentials - - string$username - - string$password - - int$authtype - - - - This method sets the username and password for authorizing the - client to a server. With the default (HTTP) transport, this - information is used for HTTP Basic authorization. Note that username - and password can also be set using the class constructor. With HTTP - 1.1 and HTTPS transport, NTLM and Digest authentication protocols - are also supported. To enable them use the constants - CURLAUTH_DIGEST and - CURLAUTH_NTLM as values for the authtype - parameter. - - - - setDebug - - - - voidsetDebug - - int$debugLvl - - - - debugLvl is either 0, - 1 or 2 depending on whether you require the client to - print debugging information to the browser. The default is not to - output this information (0). - - The debugging information at level 1includes the raw data - returned from the XML-RPC server it was querying (including bot HTTP - headers and the full XML payload), and the PHP value the client - attempts to create to represent the value returned by the server. At - level2, the complete payload of the xmlrpc request is also printed, - before being sent t the server. - - This option can be very useful when debugging servers as it - allows you to see exactly what the client sends and the server - returns. - - - - setKey - - - - voidsetKey - - int$key - - int$keypass - - - - This method sets the optional certificate key and passphrase - used in SSL-enabled communication with a remote server (when the - transport is set to 'https' in the client's - construction or in the send method). - - This requires the "curl" extension to be compiled into your - installation of PHP. For more details see the man page for the - curl_setopt function. - - - - setProxy - - - - voidsetProxy - - string$proxyhost - - int$proxyport - - string$proxyusername - - string$proxypassword - - int$authtype - - - - This method enables calling servers via an HTTP proxy. The - proxyusername, - proxypassword and authtype - parameters are optional. Authtype defaults to - CURLAUTH_BASIC (Basic authentication protocol); - the only other valid value is the constant - CURLAUTH_NTLM, and has effect only when the - client uses the HTTP 1.1 protocol. - - NB: CURL versions before 7.11.10 cannot use a proxy to - communicate with https servers. - - - - setRequestCompression - - - - voidsetRequestCompression - - string$compressionmethod - - - - This method defines whether the xml payload forming the - request body will be sent to the server in compressed format, as per - the HTTP specification. This is particularly useful for large - request parameters and over slow network connections. Allowed values - for compressionmethod are: 'gzip', 'deflate', - 'any' or null (with any meaning either gzip or deflate). Note that - there is no automatic fallback mechanism in place for errors due to - servers not supporting receiving compressed request bodies, so make - sure that the particular server you are querying does accept - compressed requests before turning it on. - - This requires the "zlib" extension to be enabled in your php - install. - - - - setSSLVerifyHost - - - - voidsetSSLVerifyHost - - int$i - - - - This method defines whether connections made to XML-RPC - backends via HTTPS should verify the remote host's SSL certificate's - common name (CN). By default, only the existence of a CN is checked. - $i should be an - integer value; 0 to not check the CN at all, 1 to merely check for - its existence, and 2 to check that the CN on the certificate matches - the hostname that is being connected to. - - - - setSSLVerifyPeer - - - - voidsetSSLVerifyPeer - - bool$i - - - - This method defines whether connections made to XML-RPC - backends via HTTPS should verify the remote host's SSL certificate, - and cause the connection to fail if the cert verification fails. - $i should be a boolean - value. Default value: TRUE. To specify custom - SSL certificates to validate the server with, use the - setCaCertificate method. - - - - - Variables - - NB: direct manipulation of these variables is only recommended - for advanced users. - - - no_multicall - - This member variable determines whether the multicall() method - will try to take advantage of the system.multicall xmlrpc method to - dispatch to the server an array of requests in a single http - roundtrip or simply execute many consecutive http calls. Defaults to - FALSE, but it will be enabled automatically on the first failure of - execution of system.multicall. - - - - request_charset_encoding - - This is the charset encoding that will be used for serializing - request sent by the client. - - If defaults to NULL, which means using US-ASCII and encoding - all characters outside of the ASCII range using their xml character - entity representation (this has the benefit that line end characters - will not be mangled in the transfer, a CR-LF will be preserved as - well as a singe LF). - - Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1' - - - - return_type - - This member variable determines whether the value returned - inside an xmlrpcresp object as results of calls to the send() and - multicall() methods will be an xmlrpcval object, a plain php value - or a raw xml string. Allowed values are 'xmlrpcvals' (the default), - 'phpvals' and 'xml'. To allow the user to differentiate between a - correct and a faulty response, fault responses will be returned as - xmlrpcresp objects in any case. Note that the 'phpvals' setting will - yield faster execution times, but some of the information from the - original response will be lost. It will be e.g. impossible to tell - whether a particular php string value was sent by the server as an - xmlrpc string or base64 value. - - Example usage: - - -$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server"); -$client->return_type = 'phpvals'; -$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); -$resp = $client->send($message); -if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value(); - - - For more details about usage of the 'xml' value, see Appendix - A. - - - - - - xmlrpcresp - - This class is used to contain responses to XML-RPC requests. A - server method handler will construct an - xmlrpcresp and pass it as a return value. This - same value will be returned by the result of an invocation of the - send method of the - xmlrpc_client class. - - - Creation - - - - xmlrpcrespnew - xmlrpcresp - - xmlrpcval$xmlrpcval - - - - xmlrpcrespnew - xmlrpcresp - - 0 - - int$errcode - - string$err_string - - - - The first syntax is used when execution has happened without - difficulty: $xmlrpcval is an - xmlrpcval value with the result of the method - execution contained in it. Alternatively it can be a string containing - the xml serialization of the single xml-rpc value result of method - execution. - - The second type of constructor is used in case of failure. - errcode and err_string - are used to provide indication of what has gone wrong. See for more information on passing error - codes. - - - - Methods - - - faultCode - - - - intfaultCode - - - - - - Returns the integer fault code return from the XML-RPC - response. A zero value indicates success, any other value indicates - a failure response. - - - - faultString - - - - stringfaultString - - - - - - Returns the human readable explanation of the fault indicated - by $resp->faultCode(). - - - - value - - - - xmlrpcvalvalue - - - - - - Returns an xmlrpcval object containing - the return value sent by the server. If the response's - faultCode is non-zero then the value returned - by this method should not be used (it may not even be an - object). - - Note: if the xmlrpcresp instance in question has been created - by an xmlrpc_client object whose - return_type was set to 'phpvals', then a plain - php value will be returned instead of an - xmlrpcval object. If the - return_type was set to 'xml', an xml string will - be returned (see the return_type member var above for more - details). - - - - serialize - - - - stringserialize - - - - - - Returns an XML string representation of the response (xml - prologue not included). - - - - - - 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: - - - 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 - below). - - 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: - - - 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 ) 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. - - - - Look at the server.php example in the - distribution to see what a dispatch map looks like. - - - - 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 string examples.getStateName(int) - has the signature array($xmlrpcString, $xmlrpcInt) - and, assuming that it is the only possible signature for the - method, it might be used like this in server creation: -$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': - - -$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: - - -$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. - - 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: - - -$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. - - - - 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: - 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. There is no other way for the server - to know when an error response should be served to the client; - - 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. - - - - - - 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 - - - $xmlrpcerruser - - 800 - The 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: -$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 - - "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: - - -<?php - -include('xmlrpc.inc'); -$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above -$v = new xmlrpcval('κόσμε'); // 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/> xmlrpc value, as per the extension to the - standard proposed here. This means that <NIL/> tags will be - parsed as valid xmlrpc, and the corresponding xmlrpcvals will return - "null" for scalarTyp(). - - - - - - 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: - -
- 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 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. - - - iso8601_encode - - - - stringiso8601_encode - - string$time_t - - int$utc0 - - - - Returns 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. - - - - iso8601_decode - - - - intiso8601_decode - - string$isoString - - int$utc0 - - - - Returns 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. - - - - - 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. - - - php_xmlrpc_decode - - - - mixedphp_xmlrpc_decode - - xmlrpcval$xmlrpc_val - - array$options - - - - arrayphp_xmlrpc_decode - - xmlrpcmsg$xmlrpcmsg_val - - string$options - - - - Returns 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 is - decode_php_objs. When it 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). - - 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: -// 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" => ... - ))); - - - - - php_xmlrpc_encode - - - - xmlrpcvalphp_xmlrpc_encode - - mixed$phpval - - array$options - - - - Returns 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 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) - - Example: -// 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_xml - - string$xml - - array$options - - - - Decodes 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: -$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_options - - - - stringwrap_xmlrpc_method - - $client - - $methodname - - $signum - - $timeout - - $protocol - - $funcname - - - - Given 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: - - -$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 - - - - arraywrap_php_function - - string$funcname - - string$wrapper_function_name - - array$extra_options - - - - Given 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: requires PHP 5.0.3 +; 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: - - /** -* 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); - - - - - - 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: - - - xmlrpc_decode - - - - mixedxmlrpc_decode - - xmlrpcval$xmlrpc_val - - - - Alias for php_xmlrpc_decode. - - - - xmlrpc_encode - - - - xmlrpcvalxmlrpc_encode - - mixed$phpval - - - - Alias for php_xmlrpc_encode. - - - - - Debugging aids - - - xmlrpc_debugmsg - - - - voidxmlrpc_debugmsg - - string$debugstring - - - - Sends 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 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. - - - - 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: - - -$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. - - - - 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 - - The best examples are to be found in the sample files included with - the distribution. Some are included here. - - - 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 - - - $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... - - - - - 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... - - - - My php error log is getting full of "deprecated" errors on - different lines of xmlrpc.inc and xmlrpcs.inc - - This happens when the PHP in usage is version 5, and the error - reporting level is set to include E_STRICT errors. - Since the main development platform of the library remains (for the time - being) PHP 4, there are no plans to fix this asap. The best workaround - is to set the error reporting level to E_ALL ^ - E_STRICT. - - - - 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. - - -$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: - - -$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 tranmission 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 potentail 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. - - -$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 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 - - -/*** 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 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 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 - - - - 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. - - - - 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. - - - - - + + + + + + XML-RPC for PHP + + version 2.2.2 + + + XXX YY, 2008 + + + + Edd + + Dumbill + + + + Gaetano + + Giunta + + + + Miles + + Lott + + + + Justin R. + + Miller + + + + Andres + + Salomon + + + + + 1999,2000,2001 + + Edd Dumbill, Useful Information Company + + + + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + + + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + + + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + + + Neither the name of the "XML-RPC for PHP" nor the names of + its contributors may be used to endorse or promote products + derived from this software without specific prior written + permission. + + + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, + BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + + + Introduction + + XML-RPC is a format devised by Userland Software for achieving + remote procedure call via XML using HTTP as the transport. XML-RPC has its + own web site, www.xmlrpc.com + + 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 Useful Information Company. As of the + 1.0 stable release, the project has been opened to wider involvement and + moved to SourceForge. + + A list of XML-RPC implementations for other languages such as Perl + and Python can be found on the 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 + + S. Kuip + + A. Lambert + + Dan Libby + + Arnaud Limbourg + + Ernest MacDougal Campbell III + + Lukasz Mach + + Kjartan Mannes + + Ben Margolin + + Nicolay Mausz + + Justin Miller + + Jan Pfeifer + + Giancarlo Pinerolo + + Peter Russel + + Viliam Simko + + Douglas Squirrel + + Idan Sofer + + Anatoly Techtonik + + Eric van der Vlist + + Christian Wenz + + Jim Winstead + + Przemyslaw Wroblewski + + + + + What's new + + Note: 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 javadoc-like form. + + + 2.2.2 + + Note: this might 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() + 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.inc. 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 of received 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 file: + 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... + + With PHP versions lesser than 5.0.3 wrapping of php functions + into xmlrpc methods is not supported yet. + + + + 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 + + + + + + + System Requirements + + The library has been designed with goals of scalability 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 + 4.2. + + A compatibility layer is provided that allows the code to run on PHP + 4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest + you upgrade as soon as possible. + + Automatic generation of xml-rpc methods from php functions is only + supported with PHP version 5.0.3 and later (note that the lib will + generate some warnings with PHP 5 in strict error reporting mode). + + If you wish to use SSL or HTTP 1.1 to communicate with remote + servers, you need the "curl" extension compiled into your PHP + installation. This is available in PHP 4.0.2 and greater, although 4.0.6 + has a bug preventing SSL working, and versions prior to 4.3.8 do not + support streamlining multiple requests using HTTP Keep-Alive. + + 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. + + + + Files in the distribution + + + + lib/xmlrpc.inc + + + the XML-RPC classes. include() this in + your PHP files to use the classes. + + + + + lib/xmlrpcs.inc + + + the XML-RPC server class. include() this + in addition to xmlrpc.inc to get server functionality + + + + + lib/xmlrpc_wrappers.inc + + + helper functions to "automagically" convert plain php + functions to xmlrpc services and vice versa + + + + + lib/compat/array_key_exists.php, lib/compat/is_a.php, + lib/compat/is_scalar.php, lib/compat/var_export.php, + lib/compat/vesrions_compare.php + + + compatibility functions: these files implement the + compatibility layer needed to run the library with PHP versions 4.0 + and 4.1 + + + + + demo/server/proxy.php + + + a sample server implementing xmlrpc proxy + functionality. + + + + + demo/server/server.php + + + a sample server hosting various demo functions, as well as a + full suite of functions used for interoperability testing. It is + used by testsuite.php (see below) for unit testing the library, and + is not to be copied literally into your production servers + + + + + demo/client/client.php, demo/client/agesort.php, + demo/client/which.php + + + client code to exercise some of the functions in server.php, + including the interopEchoTests.whichToolkit + method. + + + + + demo/client/wrap.php + + + client code to illustrate 'wrapping' of remote methods into + php functions. + + + + + demo/client/introspect.php + + + client code to illustrate usage of introspection capabilities + offered by server.php. + + + + + demo/client/mail.php + + + client code to illustrate usage of an xmlrpc-to-email gateway + using Dave Winer's XML-RPC server at userland.com. + + + + + demo/client/zopetest.php + + + example client code that queries an xmlrpc server built in + Zope. + + + + + demo/vardemo.php + + + examples of how to construct xmlrpcval types + + + + + demo/demo1.txt, demo/demo2.txt, demo/demo3.txt + + + XML-RPC responses captured in a file for testing purposes (you + can use these to test the + xmlrpcmsg->parseResponse() method). + + + + + demo/server/discuss.php, + demo/client/comment.php + + + Software used in the PHP chapter of to provide a comment server and allow the + attachment of comments to stories from Meerkat's data store. + + + + + test/testsuite.php, test/parse_args.php + + + A unit test suite for this software package. If you do + development on this software, please consider submitting tests for + this suite. + + + + + test/benchmark.php + + + A (very limited) benchmarking suite for this software package. + If you do development on this software, please consider submitting + benchmarks for this suite. + + + + + test/phpunit.php, test/PHPUnit/*.php + + + An (incomplete) version PEAR's unit test framework for PHP. + The complete package can be found at http://pear.php.net/package/PHPUnit + + + + + test/verify_compat.php + + + Script designed to help the user to verify the level of + compatibility of the library with the current php install + + + + + 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 Dave's + announcement of these. + + + + + extras/rsakey.pem + + + A test certificate key for the SSL support, which can be used + to generate dummy certificates. It has the passphrase "test." + + + + + + + Known bugs and limitations + + This started out as a bare framework. Many "nice" bits haven't been + put in yet. 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 and functions + 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. + + If a specific character set encoding other than US-ASCII, ISO-8859-1 + or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request + or response messages then it will be ignored for the moment, and the + content will be parsed as if it had been encoded using the charset defined + by + + Very large floating point numbers are serialized using exponential + notation, even though the spec explicitly forbids this behaviour. This + will not be a problem if this library is used on both ends of the + communication, but might cause problems with other implementations. + + Support for receiving from servers version 1 cookies (i.e. + conforming to RFC 2965) is quite incomplete, and might cause unforeseen + errors. + + A PHP warning will be generated in many places when using + xmlrpc.inc and xmlrpcs.inc with + PHP 5 in strict error reporting mode. The simplest workaround to this + problem is to lower the error_reporting level in + php.ini. + + + + 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 and from + XML-RPC.com. + + + + The XML-RPC for PHP development is hosted + on phpxmlrpc.sourceforge.net. + Bugs, feature requests and patches can be posted to the project's + website. + + + + The PHP XML-RPC interest mailing list is + run by the author. More details can be + found here. + + + + For more general XML-RPC questions, there is a Yahoo! Groups + XML-RPC mailing + list. + + + + The XML-RPC.com discussion + group is a useful place to get help with using XML-RPC. This group + is also gatewayed into the Yahoo! Groups mailing list. + + + + + + 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 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 + 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! + + + + + Class documentation + + + xmlrpcval + + This is where a lot of the hard work gets done. This class enables + the creation and encapsulation of values for XML-RPC. + + Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 + before reading on as it will make things clearer. + + The xmlrpcval class can store arbitrarily + complicated values using the following types: i4 int boolean + string double dateTime.iso8601 base64 array struct. You should + refer to the spec for + more information on what each of these types mean. + + + 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 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. + + + + + 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". + + Examples: + + +$myInt = new xmlrpcvalue(1267, "int"); +$myString = new xmlrpcvalue("Hello, World!", "string"); +$myBool = new xmlrpcvalue(1, "boolean"); +$myString2 = new xmlrpcvalue(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: + + +$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. + + + + Methods + + + addScalar + + + + intaddScalar + + string$stringVal + + + + intaddScalar + + mixed$scalarVal + + string$scalartyp + + + + If $val is an empty + xmlrpcval this method makes it a scalar + value, and sets that value. + + If $val is already a scalar value, then + no more scalars can be added and 0 is + returned. + + If $val is an xmlrpcval of type array, + the php value $scalarval is added as its last + element. + + If all went OK, 1 is returned, otherwise + 0. + + + + addArray + + + + intaddArray + + array$arrayVal + + + + The argument is a simple (numerically indexed) array. The + elements of the array must be + xmlrpcval objects + themselves. + + Turns an empty xmlrpcval into an + array with contents as specified by + $arrayVal. + + If $val is an xmlrpcval of type array, + the elements of $arrayVal are appended to the + existing ones. + + See the fourth constructor form for more information. + + If all went OK, 1 is returned, otherwise + 0. + + + + addStruct + + + + intaddStruct + + array$assocArrayVal + + + + The argument is an associative array. The elements of the + array must be xmlrpcval objects + themselves. + + Turns an empty xmlrpcval into a + struct with contents as specified by + $assocArrayVal. + + If $val is an xmlrpcval of type struct, + the elements of $arrayVal are merged with the + existing ones. + + See the fourth constructor form for more information. + + If all went OK, 1 is returned, otherwise + 0. + + + + kindOf + + + + stringkindOf + + + + + + Returns a string containing "struct", "array" or "scalar" + describing the base type of the value. If it returns "undef" it + means that the value hasn't been initialised. + + + + serialize + + + + stringserialize + + + + + + Returns a string containing the XML-RPC representation of this + value. + + + + scalarVal + + + + mixedscalarVal + + + + + + If $val->kindOf() == "scalar", this + method returns the actual PHP-language value of the scalar (base 64 + decoding is automatically handled here). + + + + scalarTyp + + + + stringscalarTyp + + + + + + If $val->kindOf() == "scalar", this + method returns a string denoting the type of the scalar. As + mentioned before, i4 is always coerced to + int. + + + + arrayMem + + + + xmlrpcvalarrayMem + + int$n + + + + If $val->kindOf() == "array", returns + the $nth element in the array represented by + the value $val. The value returned is an + xmlrpcval object. + + +// iterating over values of an array object +for ($i = 0; $i < $val->arraySize(); $i++) +{ + $v = $val->arrayMem($i); + echo "Element $i of the array is of type ".$v->kindOf(); +} + + + + + arraySize + + + + intarraySize + + + + + + If $val is an + array, returns the number of elements in that + array. + + + + structMem + + + + xmlrpcvalstructMem + + string$memberName + + + + If $val->kindOf() == "struct", returns + the element called $memberName from the + struct represented by the value $val. The + value returned is an xmlrpcval object. + + + + structEach + + + + arraystructEach + + + + + + Returns the next (key, value) pair from the struct, when + $val is a struct. + $value is an xmlrpcval itself. See also . + + +// iterating over all values of a struct object +$val->structreset(); +while (list($key, $v) = $val->structEach()) +{ + echo "Element $key of the struct is of type ".$v->kindOf(); +} + + + + + structReset + + + + voidstructReset + + + + + + Resets the internal pointer for + structEach() to the beginning of the struct, + where $val is a struct. + + + + structMemExists + + + + boolstructMemExsists + + string$memberName + + + + Returns TRUE or + FALSE depending on whether a member of the + given name exists in the struct. + + + + + + xmlrpcmsg + + This class provides a representation for a request to an XML-RPC + server. A client sends an xmlrpcmsg to a server, + and receives back an xmlrpcresp (see ). + + + Creation + + The constructor takes the following forms: + + + + xmlrpcmsgnew + xmlrpcmsg + + string$methodName + + array$parameterArraynull + + + + Where methodName is a string indicating + the name of the method you wish to invoke, and + parameterArray is a simple php + Array of xmlrpcval + objects. Here's an example message to the US state + name server: + + +$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); + + + This example requests the name of state number 23. For more + information on xmlrpcval objects, see . + + Note that the parameterArray parameter is + optional and can be omitted for methods that take no input parameters + or if you plan to add parameters one by one. + + + + Methods + + + addParam + + + + booladdParam + + xmlrpcval$xmlrpcVal + + + + Adds the xmlrpcval + xmlrpcVal to the parameter list for this + method call. Returns TRUE or FALSE on error. + + + + getNumParams + + + + intgetNumParams + + + + + + Returns the number of parameters attached to this + message. + + + + getParam + + + + xmlrpcvalgetParam + + int$n + + + + Gets the nth parameter in the message + (with the index zero-based). Use this method in server + implementations to retrieve the values sent by the client. + + + + method + + + + stringmethod + + + + + + stringmethod + + string$methName + + + + Gets or sets the method contained in the XML-RPC + message. + + + + parseResponse + + + + xmlrpcrespparseResponse + + string$xmlString + + + + Given an incoming XML-RPC server response contained in the + string $xmlString, this method constructs an + xmlrpcresp response object and returns it, + setting error codes as appropriate (see ). + + This method processes any HTTP/MIME headers it finds. + + + + parseResponseFile + + + + xmlrpcrespparseResponseFile + + file handle + resource$fileHandle + + + + Given an incoming XML-RPC server response on the open file + handle fileHandle, this method reads all the + data it finds and passes it to + parseResponse. + + This method is useful to construct responses from pre-prepared + files (see files demo1.txt, demo2.txt, demo3.txt + in this distribution). It processes any HTTP headers it finds, and + does not close the file handle. + + + + serialize + + + + string + serialize + + + + + + Returns the an XML string representing the XML-RPC + message. + + + + + + xmlrpc_client + + This is the basic class used to represent a client of an XML-RPC + server. + + + Creation + + The constructor accepts one of two possible syntaxes: + + + + xmlrpc_clientnew + xmlrpc_client + + string$server_url + + + + xmlrpc_clientnew + xmlrpc_client + + string$server_path + + string$server_hostname + + int$server_port80 + + string$transport'http' + + + + Here are a couple of usage examples of the first form: + + +$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php"); +$another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/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: + + +$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 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. + + + + Methods + + This class supports the following methods. + + + send + + This method takes the forms: + + + + xmlrpcrespsend + + xmlrpcmsg$xmlrpc_message + + int$timeout + + string$transport + + + + arraysend + + array$xmlrpc_messages + + int$timeout + + string$transport + + + + xmlrpcrespsend + + string$xml_payload + + int$timeout + + string$transport + + + + Where xmlrpc_message is an instance of + xmlrpcmsg (see ), + and response is an instance of + xmlrpcresp (see ). + + If xmlrpc_messages is an array of + message instances, responses will be an array of + response instances. The client will try to make use of a single + system.multicall xml-rpc method call to forward to the + server all the messages in a single HTTP round trip, unless + $client->no_multicall has been previously set to + TRUE (see the multicall method below), in which case + many consecutive xmlrpc requests will be sent. + + The third syntax allows to build by hand (or any other means) + a complete xmlrpc request message, and send it to the server. + xml_payload should be a string containing the + complete xml representation of the request. It is e.g. useful when, + for maximal speed of execution, the request is serialized into a + string using the native php xmlrpc functions (see the php manual on + xmlrpc). + + The timeout is optional, and will be + set to 0 (wait for platform-specific predefined + timeout) if omitted. This timeout value is passed to + fsockopen(). It is also used for detecting + server timeouts during communication (i.e. if the server does not + send anything to the client for timeout + seconds, the connection will be closed). + + The transport parameter is optional, + and if omitted will default to the transport set using instance + creator or 'http' if omitted. The only other valid values are + 'https', which will use an SSL HTTP connection to connect to the + remote server, and 'http11'. Note that your PHP must have the "curl" + extension compiled in order to use both these features. Note that + when using SSL you should normally set your port number to 443, + unless the SSL server you are contacting runs at any other + port. + + + PHP 4.0.6 has a bug which prevents SSL working. + + + In addition to low-level errors, the XML-RPC server you were + querying may return an error in the + xmlrpcresp object. See for details of how to handle these + errors. + + + + multiCall + + This method takes the form: + + + + arraymultiCall + + array$messages + + int$timeout + + string$transport + + bool$fallback + + + + This method is used to boxcar many method calls in a single + xml-rpc request. It will try first to make use of the + system.multicall xml-rpc method call, and fall back to + executing many separate requests if the server returns any + error. + + msgs is an array of + xmlrpcmsg objects (see ), and response is an + array of xmlrpcresp objects (see ). + + The timeout and + transport parameters are optional, and behave + as in the send method above. + + The fallback parameter is optional, and + defaults to TRUE. When set to + FALSE it will prevent the client to try using + many single method calls in case of failure of the first multicall + request. It should be set only when the server is known to support + the multicall extension. + + + + setAcceptedCompression + + + + voidsetAcceptedCompression + + string$compressionmethod + + + + This method defines whether the client will accept compressed + xml payload forming the bodies of the xmlrpc responses received from + servers. Note that enabling reception of compressed responses merely + adds some standard http headers to xmlrpc requests. It is up to the + xmlrpc server to return compressed responses when receiving such + requests. Allowed values for + compressionmethod are: 'gzip', 'deflate', + 'any' or null (with any meaning either gzip or deflate). + + This requires the "zlib" extension to be enabled in your php + install. If it is, by default xmlrpc_client + instances will enable reception of compressed content. + + + + setCaCertificate + + + + voidsetCaCertificate + + string$certificate + + bool$is_dir + + + + This method sets an optional certificate to be used in + SSL-enabled communication to validate a remote server with (when the + server_method is set to 'https' in the + client's construction or in the send method and + SetSSLVerifypeer has been set to + TRUE). + + The certificate parameter must be the + filename of a PEM formatted certificate, or a directory containing + multiple certificate files. The is_dir + parameter defaults to FALSE, set it to + TRUE to specify that + certificate indicates a directory instead of + a single file. + + This requires the "curl" extension to be compiled into your + installation of PHP. For more details see the man page for the + curl_setopt function. + + + + setCertificate + + + + voidsetCertificate + + string$certificate + + string$passphrase + + + + This method sets the optional certificate and passphrase used + in SSL-enabled communication with a remote server (when the + server_method is set to 'https' in the + client's construction or in the send method). + + The certificate parameter must be the + filename of a PEM formatted certificate. The + passphrase parameter must contain the + password required to use the certificate. + + This requires the "curl" extension to be compiled into your + installation of PHP. For more details see the man page for the + curl_setopt function. + + Note: to retrieve information about the client certificate on + the server side, you will need to look into the environment + variables which are set up by the webserver. Different webservers + will typically set up different variables. + + + + setCookie + + + + voidsetCookie + + string$name + + string$value + + string$path + + string$domain + + int$port + + + + This method sets a cookie that will be sent to the xmlrpc + server along with every further request (useful e.g. for keeping + session info outside of the xml-rpc payload). + + $value is optional, and defaults to + null. + + $path, $domain and $port are optional, + and will be omitted from the cookie header if unspecified. Note that + setting any of these values will turn the cookie into a 'version 1' + cookie, that might not be fully supported by the server (see RFC2965 + for more details). + + + + setCredentials + + + + voidsetCredentials + + string$username + + string$password + + int$authtype + + + + This method sets the username and password for authorizing the + client to a server. With the default (HTTP) transport, this + information is used for HTTP Basic authorization. Note that username + and password can also be set using the class constructor. With HTTP + 1.1 and HTTPS transport, NTLM and Digest authentication protocols + are also supported. To enable them use the constants + CURLAUTH_DIGEST and + CURLAUTH_NTLM as values for the authtype + parameter. + + + + setDebug + + + + voidsetDebug + + int$debugLvl + + + + debugLvl is either 0, + 1 or 2 depending on whether you require the client to + print debugging information to the browser. The default is not to + output this information (0). + + The debugging information at level 1includes the raw data + returned from the XML-RPC server it was querying (including bot HTTP + headers and the full XML payload), and the PHP value the client + attempts to create to represent the value returned by the server. At + level2, the complete payload of the xmlrpc request is also printed, + before being sent t the server. + + This option can be very useful when debugging servers as it + allows you to see exactly what the client sends and the server + returns. + + + + setKey + + + + voidsetKey + + int$key + + int$keypass + + + + This method sets the optional certificate key and passphrase + used in SSL-enabled communication with a remote server (when the + transport is set to 'https' in the client's + construction or in the send method). + + This requires the "curl" extension to be compiled into your + installation of PHP. For more details see the man page for the + curl_setopt function. + + + + setProxy + + + + voidsetProxy + + string$proxyhost + + int$proxyport + + string$proxyusername + + string$proxypassword + + int$authtype + + + + This method enables calling servers via an HTTP proxy. The + proxyusername, + proxypassword and authtype + parameters are optional. Authtype defaults to + CURLAUTH_BASIC (Basic authentication protocol); + the only other valid value is the constant + CURLAUTH_NTLM, and has effect only when the + client uses the HTTP 1.1 protocol. + + NB: CURL versions before 7.11.10 cannot use a proxy to + communicate with https servers. + + + + setRequestCompression + + + + voidsetRequestCompression + + string$compressionmethod + + + + This method defines whether the xml payload forming the + request body will be sent to the server in compressed format, as per + the HTTP specification. This is particularly useful for large + request parameters and over slow network connections. Allowed values + for compressionmethod are: 'gzip', 'deflate', + 'any' or null (with any meaning either gzip or deflate). Note that + there is no automatic fallback mechanism in place for errors due to + servers not supporting receiving compressed request bodies, so make + sure that the particular server you are querying does accept + compressed requests before turning it on. + + This requires the "zlib" extension to be enabled in your php + install. + + + + setSSLVerifyHost + + + + voidsetSSLVerifyHost + + int$i + + + + This method defines whether connections made to XML-RPC + backends via HTTPS should verify the remote host's SSL certificate's + common name (CN). By default, only the existence of a CN is checked. + $i should be an + integer value; 0 to not check the CN at all, 1 to merely check for + its existence, and 2 to check that the CN on the certificate matches + the hostname that is being connected to. + + + + setSSLVerifyPeer + + + + voidsetSSLVerifyPeer + + bool$i + + + + This method defines whether connections made to XML-RPC + backends via HTTPS should verify the remote host's SSL certificate, + and cause the connection to fail if the cert verification fails. + $i should be a boolean + value. Default value: TRUE. To specify custom + SSL certificates to validate the server with, use the + setCaCertificate method. + + + + + Variables + + NB: direct manipulation of these variables is only recommended + for advanced users. + + + no_multicall + + This member variable determines whether the multicall() method + will try to take advantage of the system.multicall xmlrpc method to + dispatch to the server an array of requests in a single http + roundtrip or simply execute many consecutive http calls. Defaults to + FALSE, but it will be enabled automatically on the first failure of + execution of system.multicall. + + + + request_charset_encoding + + This is the charset encoding that will be used for serializing + request sent by the client. + + If defaults to NULL, which means using US-ASCII and encoding + all characters outside of the ASCII range using their xml character + entity representation (this has the benefit that line end characters + will not be mangled in the transfer, a CR-LF will be preserved as + well as a singe LF). + + Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1' + + + + return_type + + This member variable determines whether the value returned + inside an xmlrpcresp object as results of calls to the send() and + multicall() methods will be an xmlrpcval object, a plain php value + or a raw xml string. Allowed values are 'xmlrpcvals' (the default), + 'phpvals' and 'xml'. To allow the user to differentiate between a + correct and a faulty response, fault responses will be returned as + xmlrpcresp objects in any case. Note that the 'phpvals' setting will + yield faster execution times, but some of the information from the + original response will be lost. It will be e.g. impossible to tell + whether a particular php string value was sent by the server as an + xmlrpc string or base64 value. + + Example usage: + + +$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server"); +$client->return_type = 'phpvals'; +$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int"))); +$resp = $client->send($message); +if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value(); + + + For more details about usage of the 'xml' value, see Appendix + A. + + + + + + xmlrpcresp + + This class is used to contain responses to XML-RPC requests. A + server method handler will construct an + xmlrpcresp and pass it as a return value. This + same value will be returned by the result of an invocation of the + send method of the + xmlrpc_client class. + + + Creation + + + + xmlrpcrespnew + xmlrpcresp + + xmlrpcval$xmlrpcval + + + + xmlrpcrespnew + xmlrpcresp + + 0 + + int$errcode + + string$err_string + + + + The first syntax is used when execution has happened without + difficulty: $xmlrpcval is an + xmlrpcval value with the result of the method + execution contained in it. Alternatively it can be a string containing + the xml serialization of the single xml-rpc value result of method + execution. + + The second type of constructor is used in case of failure. + errcode and err_string + are used to provide indication of what has gone wrong. See for more information on passing error + codes. + + + + Methods + + + faultCode + + + + intfaultCode + + + + + + Returns the integer fault code return from the XML-RPC + response. A zero value indicates success, any other value indicates + a failure response. + + + + faultString + + + + stringfaultString + + + + + + Returns the human readable explanation of the fault indicated + by $resp->faultCode(). + + + + value + + + + xmlrpcvalvalue + + + + + + Returns an xmlrpcval object containing + the return value sent by the server. If the response's + faultCode is non-zero then the value returned + by this method should not be used (it may not even be an + object). + + Note: if the xmlrpcresp instance in question has been created + by an xmlrpc_client object whose + return_type was set to 'phpvals', then a plain + php value will be returned instead of an + xmlrpcval object. If the + return_type was set to 'xml', an xml string will + be returned (see the return_type member var above for more + details). + + + + serialize + + + + stringserialize + + + + + + Returns an XML string representation of the response (xml + prologue not included). + + + + + + 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: + + + 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 + below). + + 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: + + + 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 ) 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. + + + + Look at the server.php example in the + distribution to see what a dispatch map looks like. + + + + 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 string examples.getStateName(int) + has the signature array($xmlrpcString, $xmlrpcInt) + and, assuming that it is the only possible signature for the + method, it might be used like this in server creation: +$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': + + +$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: + + +$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. + + 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: + + +$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. + + + + 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: + 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. There is no other way for the server + to know when an error response should be served to the client; + + 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. + + + + + + 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 + + + $xmlrpcerruser + + 800 + The 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: +$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 + + "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: + + +<?php + +include('xmlrpc.inc'); +$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above +$v = new xmlrpcval('κόσμε'); // 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/> xmlrpc value, as per the extension to the + standard proposed here. This means that <NIL/> tags will be + parsed as valid xmlrpc, and the corresponding xmlrpcvals will return + "null" for scalarTyp(). + + + + + + 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: + +
+ 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 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. + + + iso8601_encode + + + + stringiso8601_encode + + string$time_t + + int$utc0 + + + + Returns 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. + + + + iso8601_decode + + + + intiso8601_decode + + string$isoString + + int$utc0 + + + + Returns 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. + + + + + 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. + + + php_xmlrpc_decode + + + + mixedphp_xmlrpc_decode + + xmlrpcval$xmlrpc_val + + array$options + + + + arrayphp_xmlrpc_decode + + xmlrpcmsg$xmlrpcmsg_val + + string$options + + + + Returns 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 is + decode_php_objs. When it 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). + + 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: +// 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" => ... + ))); + + + + + php_xmlrpc_encode + + + + xmlrpcvalphp_xmlrpc_encode + + mixed$phpval + + array$options + + + + Returns 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 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) + + Example: +// 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_xml + + string$xml + + array$options + + + + Decodes 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: +$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_options + + + + stringwrap_xmlrpc_method + + $client + + $methodname + + $signum + + $timeout + + $protocol + + $funcname + + + + Given 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: + + +$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 + + + + arraywrap_php_function + + string$funcname + + string$wrapper_function_name + + array$extra_options + + + + Given 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: requires PHP 5.0.3 +; 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: + + /** +* 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); + + + + + + 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: + + + xmlrpc_decode + + + + mixedxmlrpc_decode + + xmlrpcval$xmlrpc_val + + + + Alias for php_xmlrpc_decode. + + + + xmlrpc_encode + + + + xmlrpcvalxmlrpc_encode + + mixed$phpval + + + + Alias for php_xmlrpc_encode. + + + + + Debugging aids + + + xmlrpc_debugmsg + + + + voidxmlrpc_debugmsg + + string$debugstring + + + + Sends 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 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. + + + + 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: + + +$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. + + + + 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 + + The best examples are to be found in the sample files included with + the distribution. Some are included here. + + + 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 + + + $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... + + + + + 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... + + + + My php error log is getting full of "deprecated" errors on + different lines of xmlrpc.inc and xmlrpcs.inc + + This happens when the PHP in usage is version 5, and the error + reporting level is set to include E_STRICT errors. + Since the main development platform of the library remains (for the time + being) PHP 4, there are no plans to fix this asap. The best workaround + is to set the error reporting level to E_ALL ^ + E_STRICT. + + + + 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. + + +$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: + + +$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 tranmission 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 potentail 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. + + +$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 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 + + +/*** 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 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 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 + + + + 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. + + + + 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. + + + + + diff --git a/lib/xmlrpc.inc b/lib/xmlrpc.inc index 1c313ae..6bad30a 100644 --- a/lib/xmlrpc.inc +++ b/lib/xmlrpc.inc @@ -231,7 +231,7 @@ $GLOBALS['xmlrpc_internalencoding']='ISO-8859-1'; $GLOBALS['xmlrpcName']='XML-RPC for PHP'; - $GLOBALS['xmlrpcVersion']='2.2.1'; + $GLOBALS['xmlrpcVersion']='2.2.2'; // let user errors start at 800 $GLOBALS['xmlrpcerruser']=800; -- 2.43.0