first commit
This commit is contained in:
237
lib/phpxmlrpc/doc/api_changes_v4.md
Normal file
237
lib/phpxmlrpc/doc/api_changes_v4.md
Normal file
@@ -0,0 +1,237 @@
|
||||
API Changes between library versions 3 and 4
|
||||
============================================
|
||||
|
||||
Class loading
|
||||
-------------
|
||||
|
||||
It is not necessary any more to include the files xmlrpc.inc, xmlrpcs.inc and xmlrpc_wrappers.inc to have the
|
||||
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
|
||||
|
||||
"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 <path to library> . "/src/Autoloader.php";
|
||||
PhpXmlRpc\Autoloader::register();
|
||||
|
||||
|
||||
* If you still include manually xmlrpc.inc, xmlrpcs.inc or xmlrpc_wrappers.inc, you will not need to set up
|
||||
class autoloading, as those files do include all the source files for the library classes
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Conversion table:
|
||||
|
||||
| Old class | New class | Notes |
|
||||
| ------------- | ------------------ | ------------------------------------- |
|
||||
| xmlrpc_client | PhpXmlRpc\Client | |
|
||||
| xmlrpc_server | PhpXmlRpc\Server | Removed method: echoInput |
|
||||
| xmlrpcmsg | PhpXmlRpc\Request | |
|
||||
| xmlrpcresp | PhpXmlRpc\Response | |
|
||||
| xmlrpcval | PhpXmlRpc\Value | Removed methods: serializeval, getval |
|
||||
|
||||
|
||||
New class methods
|
||||
-----------------
|
||||
|
||||
In case you had extended the classes of the library and added methods to the subclasses, you might find that your
|
||||
implementation clashes with the new one if you implemented:
|
||||
|
||||
|
||||
| Class | Method | Notes |
|
||||
| --------- | ------------ | --------------------------------------- |
|
||||
| xmlrpcval | count | implements interface: Countable |
|
||||
| xmlrpcval | getIterator | implements interface: IteratorAggregate |
|
||||
| xmlrpcval | offsetExists | implements interface: ArrayAccess |
|
||||
| xmlrpcval | offsetGet | implements interface: ArrayAccess |
|
||||
| xmlrpcval | offsetSet | implements interface: ArrayAccess |
|
||||
| xmlrpcval | offsetUnset | implements interface: ArrayAccess |
|
||||
|
||||
|
||||
Global variables cleanup
|
||||
------------------------
|
||||
|
||||
All variables in the global scope have been moved into classes.
|
||||
|
||||
Conversion table:
|
||||
|
||||
| Old variable | New variable | Notes |
|
||||
| ------------------------ | ------------------------------------------- | --------- |
|
||||
| _xmlrpc_debuginfo | PhpXmlRpc\Server::$_xmlrpc_debuginfo | protected |
|
||||
| _xmlrpcs_capabilities | NOT AVAILABLE YET | |
|
||||
| _xmlrpcs_dmap | NOT AVAILABLE YET | |
|
||||
| _xmlrpcs_occurred_errors | PhpXmlRpc\Server::$_xmlrpcs_occurred_errors | protected |
|
||||
| _xmlrpcs_prev_ehandler | PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler | protected |
|
||||
| xmlrpcWPFObjHolder | PhpXmlRpc\Wrapper::$objHolder | |
|
||||
| ... | | |
|
||||
|
||||
|
||||
Global functions cleanup
|
||||
------------------------
|
||||
|
||||
Most functions in the global scope have been moved into classes.
|
||||
Some have been slightly changed.
|
||||
|
||||
| Old function | New function | Notes |
|
||||
| -------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
|
||||
| build_client_wrapper_code | none | |
|
||||
| build_remote_method_wrapper_code | PhpXmlRpc\Wrapper->buildWrapMethodSource | signature changed |
|
||||
| decode_chunked | PhpXmlRpc\Helper\Http::decodeChunked | |
|
||||
| guess_encoding | PhpXmlRpc\Helper\XMLParser::guessEncoding | |
|
||||
| has_encoding | PhpXmlRpc\Helper\XMLParser::hasEncoding | |
|
||||
| is_valid_charset | PhpXmlRpc\Helper\Charset->isValidCharset | this method is not static, you need a Charset obj |
|
||||
| iso8601_decode | PhpXmlRpc\Helper\Date::iso8601Decode | |
|
||||
| iso8601_encode | PhpXmlRpc\Helper\Date::iso8601Encode | |
|
||||
| php_2_xmlrpc_type | PhpXmlRpc\Wrapper->php2XmlrpcType | this method is not static, you need a Wrapper obj |
|
||||
| php_xmlrpc_decode | PhpXmlRpc\Encoder->decode | this method is not static, you need an Encoder obj |
|
||||
| php_xmlrpc_decode_xml | PhpXmlRpc\Encoder->decodeXml | this method is not static, you need an Encoder obj |
|
||||
| php_xmlrpc_encode | PhpXmlRpc\Encoder->encode | this method is not static, you need an Encoder obj |
|
||||
| wrap_php_class | PhpXmlRpc\Wrapper->wrapPhpClass | returns closures instead of function names by default |
|
||||
| wrap_php_function | PhpXmlRpc\Wrapper->wrapPhpFunction | returns closures instead of function names by default |
|
||||
| wrap_xmlrpc_method | PhpXmlRpc\Wrapper->wrapXmrlpcMethod | returns closures instead of function names by default |
|
||||
| wrap_xmlrpc_server | PhpXmlRpc\Wrapper->wrapXmrlpcServer | returns closures instead of function names by default; |
|
||||
| | | returns an array ready for usage in dispatch map |
|
||||
| xmlrpc_2_php_type | PhpXmlRpc\Wrapper->Xmlrpc2phpType | this method is not static, you need a Wrapper obj |
|
||||
| xmlrpc_debugmsg | PhpXmlRpc\Server->xmlrpc_debugmsg | |
|
||||
| xmlrpc_encode_entitites | PhpXmlRpc\Helper\Charset->encodeEntitities | this method is not static, you need a Charset obj |
|
||||
|
||||
|
||||
Character sets and encoding
|
||||
---------------------------
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
global variables.
|
||||
|
||||
|
||||
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 them
|
||||
|
||||
* all library source code has been moved to the src/ directory
|
||||
|
||||
* all source code has been reformatted according to modern PSR standards
|
||||
|
||||
|
||||
Enabling compatibility with legacy code
|
||||
---------------------------------------
|
||||
|
||||
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 of 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 purpose of backwards compatibility (you might notice that they are still in the 'lib' directory, whereas all of
|
||||
the refactored code now sits in the 'src' directory).
|
||||
|
||||
Of course, some minor changes where inevitable, and backwards compatibility can not be guaranteed at 100%.
|
||||
Below is the list of all known changes and possible pitfalls when enabling 'compatibility mode'.
|
||||
|
||||
### 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
|
||||
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
|
||||
|
||||
// code as was before
|
||||
include('xmlrpc.inc');
|
||||
$GLOBALS['xmlrpc_internalencoding'] = 'UTF-8';
|
||||
// new line needed now
|
||||
PhpXmlRpc\PhpXmlRpc::importGlobals();
|
||||
|
||||
### 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.
|
||||
This is true for:
|
||||
|
||||
$GLOBALS['xmlrpcI4']
|
||||
$GLOBALS['xmlrpcInt']
|
||||
$GLOBALS['xmlrpcBoolean']
|
||||
$GLOBALS['xmlrpcDouble']
|
||||
$GLOBALS['xmlrpcString']
|
||||
$GLOBALS['xmlrpcDatetTme']
|
||||
$GLOBALS['xmlrpcBase64']
|
||||
$GLOBALS['xmlrpcArray']
|
||||
$GLOBALS['xmlrpcStruct']
|
||||
$GLOBALS['xmlrpcValue']
|
||||
$GLOBALS['xmlrpcNull']
|
||||
$GLOBALS['xmlrpcTypes']
|
||||
$GLOBALS['xmlrpc_valid_parents']
|
||||
$GLOBALS['xml_iso88591_Entities']
|
||||
|
||||
* Changing the value of the other global variables will still have an effect on operation of the library, but only after
|
||||
a call to PhpXmlRpc::importGlobals()
|
||||
|
||||
Example:
|
||||
|
||||
// code as was before
|
||||
include('xmlrpc.inc');
|
||||
$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;
|
||||
|
||||
* 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
|
||||
and is thus not available any more
|
||||
|
||||
- same for $GLOBALS['_xmlrpcs_occurred_errors']
|
||||
|
||||
- same for $GLOBALS['_xmlrpc_debuginfo']
|
||||
|
||||
- $GLOBALS['_xmlrpcs_capabilities'] and $GLOBALS['_xmlrpcs_dmap'] have been removed
|
||||
|
||||
### Using typeof/class-name checks in your code
|
||||
|
||||
* if you are checking the types of returned objects, your checks will most likely fail.
|
||||
This is due to the fact that 'old' classes extend the 'new' versions, but library code that creates object
|
||||
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
|
||||
|
||||
### server behaviour can not be changed by setting global variables (the ones starting with _xmlrpcs_ )
|
||||
|
||||
might be fixed later?
|
||||
Reference in New Issue
Block a user