Documentation
-------------
-See the documentation page at [gggeek.github.io/phpxmlrpc](https://gggeek.github.io/phpxmlrpc) for a list of the
-library main features and all project related information, including information about online resources such as
-debuggers and demo servers.
+* See the documentation page at [gggeek.github.io/phpxmlrpc](https://gggeek.github.io/phpxmlrpc) for a list of the
+ library main features and all project related information, including information about online resources such as
+ debuggers and demo servers.
-The user manual can be found in the doc/manual directory: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc).
-It includes sections about upgrading from previous versions as well as running the library's testing suite and bundled
-debugger.
+* The user manual can be found in the doc/manual directory: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc).
+ It includes sections about upgrading from previous versions and the Backwards compatibility promise as well as about
+ running the library's testing suite and bundled debugger.
-The manual is formatted as an asciidoc file - if viewing it locally, it is recommended to either use an IDE which can
-natively render asciidoc, or view it as html with a browser by serving it via a webserver and accessing
-/doc/manual/index.html
+ The manual is formatted as an asciidoc file - if viewing it locally, it is recommended to either use an IDE which can
+ natively render asciidoc, or view it as html with a browser by serving it via a webserver and accessing
+ /doc/manual/index.html
-Automatically-generated documentation for the API is available online at [http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html](http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html)
+ The latest version of the manual is also accessible online at https://github.com/gggeek/phpxmlrpc/blob/master/doc/manual/phpxmlrpc_manual.adoc
-You are encouraged to look also at the code examples found in the demo/ directory.
+* Automatically-generated documentation for the API is available online at [http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html](http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html)
-Note: to reduce the size of the download, the demo files are not part of the default package installed with Composer.
-You can either check them out online at https://github.com/gggeek/phpxmlrpc/tree/master/demo, download them as a separate
-tarball from https://github.com/gggeek/phpxmlrpc/releases or make sure they are available locally by installing the
-library using Composer option `--prefer-install=source`. Whatever the method chosen, make sure that the demo folder is
-not directly accessible from the internet, i.e. it is not within the webserver root directory).
+* You are encouraged to look also at the code examples found in the demo/ directory.
+
+ Note: to reduce the size of the download, the demo files are not part of the default package installed with Composer.
+ You can either check them out online at https://github.com/gggeek/phpxmlrpc/tree/master/demo, download them as a separate
+ tarball from https://github.com/gggeek/phpxmlrpc/releases or make sure they are available locally by installing the
+ library using Composer option `--prefer-install=source`. Whatever the method chosen, make sure that the demo folder is
+ not directly accessible from the internet, i.e. it is not within the webserver root directory).
License
-------
The default character set used by the library to deliver data to your app is now UTF8.
It is also the character set that the library expects data from your app to be in (including method names).
The value can be changed (to either US-ASCII or ISO-8859-1) by setting the desired value to
- PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding
+ `PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding`
Usage of closures for wrapping
------------------------------
Differences in server behaviour
-------------------------------
-The results for calls to system.listMethods and system.getCapabilities can not be set anymore via changes to
+The results for calls to `system.listMethods` and `system.getCapabilities` can not be set anymore via changes to
global variables.
Other
-----
-* when serialize() is invoked on a response and its payload can not be serialized, an exception is thrown instead of
+* 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 them
If you have code which relies on version 3 of the phpxmlrpc API, you *should* be able to use version 4 as a drop-in
replacement, regardless of all the changes mentioned above.
-The magic happens via the xmlrpc.inc, xmlrpcs.inc and xmlrpc_wrappers.inc files, which have been kept solely for
+The magic happens via the `xmlrpc.inc`, `xmlrpcs.inc` and `xmlrpc_wrappers.inc` files, which have been kept solely for
the purpose of backwards compatibility (you might notice that they are still in the 'lib' directory, whereas all
the refactored code now sits in the 'src' directory).
### Default character set used for application data
-* when including the xmlrpc.inc file, the defalt character set used by the lib to give data to your app gets switched
+* when including the xmlrpc.inc file, the default character set used by the lib to give data to your app gets switched
back to ISO-8859-1, as it was in previous versions
* if yor app used to change that value, you will need to add one line to your code, to make sure it is properly used
* Not all variables which existed after including xmlrpcs.inc in version 3 are available
- - $GLOBALS['_xmlrpcs_prev_ehandler'] has been replaced with protected static var PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler
+ - `$GLOBALS['_xmlrpcs_prev_ehandler']` has been replaced with protected static var `PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler`
and is thus not available any more
- - same for $GLOBALS['_xmlrpcs_occurred_errors']
+ - same for `$GLOBALS['_xmlrpcs_occurred_errors']`
- - same for $GLOBALS['_xmlrpc_debuginfo']
+ - same for `$GLOBALS['_xmlrpc_debuginfo']`
- - $GLOBALS['_xmlrpcs_capabilities'] and $GLOBALS['_xmlrpcs_dmap'] have been removed
+ - `$GLOBALS['_xmlrpcs_capabilities']` and `$GLOBALS['_xmlrpcs_dmap']` have been removed
### Using typeof/class-name checks in your code
== Upgrading [[upgrading]]
+=== our Backward Compatibility promise
+
+The PHPXMLRPC library adheres to Semantic Versioning principles, as outlined in https://semver.org/.
+
+In short, Semantic Versioning means that only major releases (such as 3.0, 4.0 etc.) are allowed to break backward
+compatibility. Minor releases (such as 4.1, 4.2 etc.) may introduce new features, but must do so without breaking the
+existing API of that release branch (4.x in the previous example).
+
+However, __backward compatibility__ comes in many different flavors. In fact, almost every change made to the library can
+potentially break an application. For example:
+* if we add a new argument to an existing class method, this will break an application which extended this class and
+ reimplemented the same method, as it will have to add the new argument as well - even if we give it a default value
+* if we add a new method to a class, this will break an application which extended this class and added the same method,
+ but with a different method signature
+* if we add a new protected property to a class, this will break an application which extended this class and added the
+ same method property, and uses it for a different purpose
+* etc...
+
+The guiding principle used to inform the development process and the version number applied to new releases is:
+* we adhere to strict Semantic Versioning Backward Compatibility rules for __consumers__ of the library.
+* we __strive__ to maintain Semantic Versioning Backward Compatibility for developers __extending__ the library, for
+ as long as humanly possible, but do not guarantee it 100%
+The distinction between __consumers__ and __extenders__ is clear-cut: an extender is anyone implementing a subclass
+of any of the PHPXMLRPC classes, or replacing it wholesale with his/her own implementation.
+
+In detail:
+* to avoid breaking compatibility with extenders, the library will not implement strict type declaration. This might
+ include weird practices such as declaring interfaces but not checking or enforcing them at the point of use
+* return types of functions and methods is only allowed to be changed in major versions
+* new arguments to functions and methods are allowed to be added in minor versions, provided they have a default value
+* new functions and methods are allowed to be added in minor versions
+* existing class methods and properties might be removed or renamed in minor versions. When that happens, their
+ previous incarnations will be kept working via usage of php magic functions `__get`, `__set`, `__call` and friends;
+ using those will eventually lead to deprecation errors being triggered - but that has not yet been enabled
+* exceptions thrown by the library are allowed to be moved to a subclass of their previous class in minor versions
+* exception messages and error messages are not guaranteed to be stable. They mostly get more detailed over time,
+ but might occasionally see complete rewording
+
+Finally, _always read carefully the NEWS file before upgrading_. It is the single most important source of truth
+regarding changes to the API (after the code itself, of course)
+
+=== Upgrading to version 4
+
If you are upgrading to version 4 from version 3 or earlier you have two options:
1. adapt your code to the new API (all changes needed are described in https://github.com/gggeek/phpxmlrpc/blob/master/doc/api_changes_v4.md)
In any case, read carefully the docs available online and report back any undocumented issue using GitHub.
-=== Removed from the library [[deprecated]]
+=== Upgrading to version 2
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 PHP xml-rpc extension, 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 [[xmlrpcdecode]]
*
* @todo do a bit of basic benchmarking: strtr vs. str_replace, str_replace vs htmlspecialchars, hand-coded conversion
* vs mbstring when that is enabled
- * @todo make usage of iconv when it is available and mbstring is not
+ * @todo make use of iconv when it is available and mbstring is not
* @todo support aliases for charset names, eg ASCII, LATIN1, ISO-88591 (see f.e. polyfill-iconv for a list),
* but then take those into account as well in other methods, ie. isValidCharset)
* @todo when converting to ASCII, allow to choose whether to escape the range 0-31,127 (non-print chars) or not
git://git.onelab.eu / plcapi.git / commitdiff