From b6815973f2e7908d5b0e546c60774ab523181386 Mon Sep 17 00:00:00 2001 From: ggiunta Date: Sat, 5 Sep 2009 21:21:14 +0000 Subject: [PATCH 1/1] update docs and NEWS for new release git-svn-id: https://svn.code.sf.net/p/phpxmlrpc/code/trunk/xmlrpc@60 013ecfd8-0664-425d-a759-9c98391dc3f9 --- NEWS | 23 ++++ doc/xmlrpc_php.xml | 277 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 231 insertions(+), 69 deletions(-) diff --git a/NEWS b/NEWS index 5d8ca48..ab62c1e 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,26 @@ +XML-RPC for PHP version 3.0.0 beta - 2009/09/05 + +This is the first release of the library to only support PHP 5. +Some legacy code has been removed, and support for features such as exceptions +and dateTime objects introduced. + +The "beta" tag is meant to indicate the fact that the refactoring has been more widespread +than in precedent releases and that more changes are likely to be introduced with time - +the library is still considered to be production quality. + +* improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects etc... +* improved: add support for the tag used by the apache library, both in input and output +* improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval +* improved: add support for timestamps as parameter for constructor of xmlrpcval +* improved: add option 'dates_as_objects' to php_xmlrpc_decode to return dateTime objects for xmlrpc datetimes +* improved: add new method SetCurlOptions to xmrlpc_client to allow extra flexibility in tweaking http config, such as explicitly binding to an ip address +* improved: add new method SetUserAgent to xmrlpc_client to to allow having different user-agent http headers +* improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the server is in 'phpvals' mode +* improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map with an added option +* improved: catch exceptions thrown during execution of php functions exposed as methods by the server +* fixed: bad encoding if same object is encoded twice using php_xmlrpc_encode + + XML-RPC for PHP version 2.2.2 - 2009/03/16 This release corrects all bugs that have been reported and sucesfully reproduced since diff --git a/doc/xmlrpc_php.xml b/doc/xmlrpc_php.xml index 547b02d..6f42602 100644 --- a/doc/xmlrpc_php.xml +++ b/doc/xmlrpc_php.xml @@ -9,10 +9,10 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ XML-RPC for PHP - version 2.2.2 + version 3.0.0 beta - XXX YY, 2008 + Sep 5, 2009 @@ -112,8 +112,8 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ 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 @@ -153,6 +153,8 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ A. Lambert + Frederic Lecointre + Dan Libby Arnaud Limbourg @@ -175,14 +177,20 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ Peter Russel + Jean-Jacques Sarton + Viliam Simko + Idan Sofer + Douglas Squirrel - Idan Sofer + Heiko Stübner Anatoly Techtonik + Tommaso Trani + Eric van der Vlist Christian Wenz @@ -190,6 +198,8 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ Jim Winstead Przemyslaw Wroblewski + + Bruno Zanetti Melotti @@ -202,6 +212,88 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ functions and methods please take a look at the source code of the library, which is quite thoroughly commented in javadoc-like form. + + 3.0.0 beta + + This is the first release of the library to only support PHP 5. + Some legacy code has been removed, and support for features such as + exceptions and dateTime objects introduced. + + The "beta" tag is meant to indicate the fact that the refactoring + has been more widespread than in precedent releases and that more + changes are likely to be introduced with time - the library is still + considered to be production quality. + + + + improved: removed all usage of php functions deprecated in + php 5.3, usage of assign-by-ref when creating new objects + etc... + + + + improved: add support for the <ex:nil/> tag used by + the apache library, both in input and output + + + + improved: add support for dateTime + objects in both in php_xmlrpc_encode and as + parameter for constructor of + xmlrpcval + + + + improved: add support for timestamps as parameter for + constructor of xmlrpcval + + + + improved: add option 'dates_as_objects' to + php_xmlrpc_decode to return + dateTime objects for xmlrpc + datetimes + + + + improved: add new method + SetCurlOptions to + xmrlpc_client to allow extra flexibility in + tweaking http config, such as explicitly binding to an ip + address + + + + improved: add new method + SetUserAgent to + xmrlpc_client to to allow having different + user-agent http headers + + + + improved: add a new member variable in server class to allow + fine-tuning of the encoding of returned values when the server is + in 'phpvals' mode + + + + improved: allow servers in 'xmlrpcvals' mode to also + register plain php functions by defining them in the dispatch map + with an added option + + + + improved: catch exceptions thrown during execution of php + functions exposed as methods by the server + + + + fixed: bad encoding if same object is encoded twice using + php_xmlrpc_encode + + + + 2.2.2 @@ -763,11 +855,7 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ 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. + 5.0. 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 @@ -775,9 +863,7 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ 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. + installation. The "xmlrpc" native extension is not required to be compiled into your PHP installation, but if it is, there will be no interference with @@ -815,18 +901,6 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ - - 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 @@ -1021,20 +1095,9 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ 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. @@ -1118,9 +1181,10 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ 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. + string double dateTime.iso8601 base64 array struct + null. You should refer to the spec for more information on + what each of these types mean. Notes on types @@ -1168,6 +1232,16 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ representation has the advantage of producing XML that is valid independently of the charset encoding assumed. + + + null + + There is no support for encoding null + values in the XML-RPC spec, but at least a couple of extensions (and + many toolkits) do support it. Before using null + values in your messages, make sure that the responding party accepts + them, and uses the same encoding convention (see ...). + @@ -1222,8 +1296,8 @@ $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $ second parameter must be a name of an XML-RPC type. Valid types are: "int", "boolean", "string", "double", - "dateTime.iso8601", - "base64". + "dateTime.iso8601", "base64" or + "null". Examples: @@ -2084,6 +2158,21 @@ $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80); parameter. + + setCurlOptions + + + + voidsetCurlOptions + + array$options + + This method allows to directly set any desired + option to manipulate the usage of the cURL client (when in cURL + mode). It can be used eg. to explicitly bind to an outgoing ip + address when the server is multihomed + + setDebug @@ -2232,6 +2321,21 @@ $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80); SSL certificates to validate the server with, use the setCaCertificate method. + + + setUserAgent + + + + voidUseragent + + string$useragent + + This method sets a custom user-agent that will be + used by the client in the http headers sent with the request. The + default value is built using the library name and version + constants. + @@ -2472,7 +2576,11 @@ if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 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). + ...). Exceptions thrown duting execution of handler functions are + caught by default and a XML-RPC error reponse is generated instead. + This behaviour can be finetuned by usage of the + exception_handling member variable (see + ...). Note that if you implement a method with a name prefixed by system. the handler function will be invoked by the @@ -2561,6 +2669,14 @@ if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo "system.methodHelp" protocol does not support documenting method parameters individually. + + + parameters_type - this entry can be used + when the server is working in 'xmlrpcvals' mode (see ...) to + define one or more entries in the dispatch map as being functions + that follow the 'phpvals' calling convention. The only useful + value is currently the string phpvals. + Look at the server.php example in the @@ -2649,7 +2765,8 @@ $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. + permits further manipulation of the response, possibly in combination + with output buffering. To prevent the server from sending HTTP headers back to the client, you can pass a second parameter with a value of @@ -2713,6 +2830,19 @@ $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead TRUE. + + exception_handling + + This variable controls the behaviour of the server when an + exception is thrown by a method handler php function. Valid values: + 0,1,2, with 0 being the default. At level 0, the server catches the + exception and return an 'internal error' xmlrpc response; at 1 it + catches the exceptions and return an xmlrpc response with the error + code and error message corresponding to the exception that was + thron; at 2 = the exception is floated to the upper layers in the + code + + response_charset_encoding @@ -2896,8 +3026,10 @@ $resp = $s->service($xmlrpc_request_body, true); // parse a variable instead 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; + return an instance of xmlrpcresp. The only + other way for the server to know when an error response should be + served to the client is to throw an exception and set the server's + exception_handling memeber var to 1; to return a base64 value, the method handler function must encode it on its own, creating an instance of an xmlrpcval @@ -3067,10 +3199,22 @@ $v = new xmlrpcval('κόσμε'); // This xmlrpc value will be corre 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(). + support for the <NIL/> (and <EX:NIL/>) xmlrpc value, as + per the extension to the standard proposed here. This means that + <NIL/> and <EX:NIL/> tags received will be parsed as valid + xmlrpc, and the corresponding xmlrpcvals will return "null" for + scalarTyp(). + + + + xmlrpc_null_apache_encoding + + When set to TRUE, php NULL values encoded + into xmlrpcval objects get serialized using the + <EX:NIL/> tag instead of + <NIL/>. Please note that both forms are + always accepted as input regardless of the value of this + variable. @@ -3205,13 +3349,16 @@ $v = new xmlrpcval('κόσμε'); // This xmlrpc value will be corre 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 + decoding process. At the moment the only valid option are + decode_php_objs and + dates_as_objects. When the first is set, php + objects that have been converted to xml-rpc structs using the php_xmlrpc_encode function and a corresponding encoding option will be converted back into object values instead of arrays (provided that the class definition is available at - reconstruction time). + reconstruction time). When the second is set, XML-RPC datetime values + will be converted into native dateTime objects + instead of strings. WARNING: please take extreme care before enabling the decode_php_objs @@ -3266,15 +3413,19 @@ $s = new xmlrpc_server(array( 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. + encode_php_objs, null_extension + and auto_dates. The first will enable the creation of 'particular' xmlrpcval objects out of php objects, that add a "php_class" xml attribute to their serialized representation. This attribute allows the function php_xmlrpc_decode to rebuild the native php objects (provided that the - same class definition exists on both sides of the - communication) + same class definition exists on both sides of the communication). The + second allows to encode php NULL values to the + <NIL/> (or + <EX:NIL/>, see ...) tag. The last encodes any + string that matches the ISO8601 format into an XML-RPC + datetime. Example: // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values @@ -3841,18 +3992,6 @@ if ($v->kindOf() != "array") { 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 -- 2.43.0