From caec5267590099a2fe0367c66ff6ececda40efee Mon Sep 17 00:00:00 2001 From: gggeek Date: Wed, 20 Jan 2016 22:34:21 +0000 Subject: [PATCH] Prepare docs for release of version 4.0 --- NEWS | 2 +- README.md | 16 +++++++++++++--- doc/api_changes_v4.md | 22 +++++++++++----------- 3 files changed, 25 insertions(+), 15 deletions(-) diff --git a/NEWS b/NEWS index 48798f3..4fd0aad 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,4 @@ -XML-RPC for PHP version 4.0.0 alpha - 2015/7/13 +XML-RPC for PHP version 4.0.0 - 2016/1/20 This release does away with the past and starts a transition to modern-world php. diff --git a/README.md b/README.md index 304f080..2b48d5e 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,25 @@ Detailed installation instructions are in the [INSTALL.md](INSTALL.md) file, alo Documentation ------------- + +*NB: the user manual has not been updated yet with all the changes made in version 4. Please consider it unreliable!* + +*You are encouraged to look instead the code examples found in the demo/ directory* + The user manual can be found in the doc/manual directory, in Asciidoc format: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc) Release tarballs also contain the HTML and PDF versions, as well as an automatically generated API documentation. -*NB: the user manual has not been updated yet with all the changes made in version 4. Please consider it unreliable!* - Upgrading --------- -If you are upgrading from version 3 or earlier, please read the docs in [doc/api_changes_v4.md](doc/api_changes_v4.md) +If you are upgrading from version 3 or earlier you have two options: + +1. adapt your code to the new API (all changes needed are described in [doc/api_changes_v4.md](doc/api_changes_v4.md)) + +2. use instead the *compatibility layer* which is provided. Instructions and pitfalls described in [doc/api_changes_v4.md](doc/api_changes_v4.md##enabling-compatibility-with-legacy-code) + +In any case, read carefully the docs in [doc/api_changes_v4.md](doc/api_changes_v4.md) and report back any undocumented +issue using GitHub. License ------- diff --git a/doc/api_changes_v4.md b/doc/api_changes_v4.md index 7b04ecd..1a01da9 100644 --- a/doc/api_changes_v4.md +++ b/doc/api_changes_v4.md @@ -8,18 +8,18 @@ It is not necessary any more to include the files xmlrpc.inc, xmlrpcs.inc and xm library classes available. Instead, it is recommended to rely on class autoloading. - -* If you are using Composer, just install the library by declaring it as dependency for your project in composer.json + +* If you are using Composer, just install the library by declaring it as dependency for your project in composer.json "require": { ..., "phpxmlrpc/phpxmlrpc": "~4.0" }, - + * If you do not use Composer, an autoloader for the library can be found in src/Atuloader.php. The php example files in the demo/client folder do make use of it. Example code to set up the autoloader: - + include_once . "/src/Autoloader.php"; PhpXmlRpc\Autoloader::register(); @@ -32,7 +32,7 @@ New class naming ---------------- All classes have ben renamed, are now properly namespaced and follow the CamelCase naming convention. -Existing class methods and members have been preserved; all new method names follow camelCase. +Existing class methods and members have been preserved; all new method names follow camelCase. Conversion table: @@ -137,9 +137,9 @@ Other * when serialize() is invoked on a response and its payload can not be serialized, an exception is thrown instead of ending all execution -* all error messages now mention the class and method which generated name +* all error messages now mention the class and method which generated them -* all library source code has been moved to the src/ directory +* all library source code has been moved to the src/ directory * all source code has been reformatted according to modern PSR standards @@ -173,7 +173,7 @@ Below is the list of all known changes and possible pitfalls when enabling 'comp ### Usage of global variables * ALL global variables which existed after including xmlrpc.inc in version 3 still do exist after including it in v. 4 - + * Code which relies on using (as in 'reading') their value will keep working unchanged * Changing the value of some of those variables does not have any effect anymore on library operation. @@ -204,9 +204,9 @@ Below is the list of all known changes and possible pitfalls when enabling 'comp $GLOBALS['xmlrpc_null_apache_encoding'] = true; // new line needed now PhpXmlRpc\PhpXmlRpc::importGlobals(); - + Alternative solution: - + include('xmlrpc.inc'); PhpXmlRpc\PhpXmlRpc::$xmlrpc_null_apache_encoding = true; @@ -228,7 +228,7 @@ Below is the list of all known changes and possible pitfalls when enabling 'comp instances will return the new classes. Example: - + is_a(php_xmlrpc_encode('hello world'), 'xmlrpcval') => false is_a(php_xmlrpc_encode('hello world'), 'PhpXmlRpc\Value') => true -- 2.43.0