doc/api_changes_v4.md

   1 API Changes between library versions 3 and 4
   2 ============================================
   3
   4 Class loading
   5 -------------
   6
   7 It is not necessary any more to include the files xmlrpc.inc, xmlrpcs.inc and xmlrpc_wrappers.inc to have the
   8 library classes available.
   9
  10 Instead, it is recommended to rely on class autoloading.
  11
  12 * If you are using Composer, just install the library by declaring it as dependency for your project in composer.json
  13
  14         "require": {
  15             ...,
  16             "phpxmlrpc/phpxmlrpc": "~4.0"
  17         },
  18
  19 * If you do not use Composer, an autoloader for the library can be found in src/Atuloader.php.
  20   The php example files in the demo/client folder do make use of it.
  21   Example code to set up the autoloader:
  22
  23         include_once <path to library> . "/src/Autoloader.php";
  24         PhpXmlRpc\Autoloader::register();
  25
  26
  27 * If you still include manually xmlrpc.inc, xmlrpcs.inc or xmlrpc_wrappers.inc, you will not need to set up
  28   class autoloading, as those files do include all the source files for the library classes
  29
  30
  31 New class naming
  32 ----------------
  33
  34 All classes have ben renamed, are now properly namespaced and follow the CamelCase naming convention.
  35 Existing class methods and members have been preserved; all new method names follow camelCase.
  36
  37 Conversion table:
  38
  39 | Old class     | New class          | Notes                                 |
  40 | ------------- | ------------------ | ------------------------------------- |
  41 | xmlrpc_client | PhpXmlRpc\Client   |                                       |
  42 | xmlrpc_server | PhpXmlRpc\Server   | Removed method: echoInput             |
  43 | xmlrpcmsg     | PhpXmlRpc\Request  |                                       |
  44 | xmlrpcresp    | PhpXmlRpc\Response |                                       |
  45 | xmlrpcval     | PhpXmlRpc\Value    | Removed methods: serializeval, getval |
  46
  47
  48 New class methods
  49 -----------------
  50
  51 In case you had extended the classes of the library and added methods to the subclasses, you might find that your
  52 implementation clashes with the new one if you implemented:
  53
  54
  55 | Class     | Method       | Notes                                   |
  56 | --------- | ------------ | --------------------------------------- |
  57 | xmlrpcval | count        | implements interface: Countable         |
  58 | xmlrpcval | getIterator  | implements interface: IteratorAggregate |
  59 | xmlrpcval | offsetExists | implements interface: ArrayAccess       |
  60 | xmlrpcval | offsetGet    | implements interface: ArrayAccess       |
  61 | xmlrpcval | offsetSet    | implements interface: ArrayAccess       |
  62 | xmlrpcval | offsetUnset  | implements interface: ArrayAccess       |
  63
  64
  65 Global variables cleanup
  66 ------------------------
  67
  68 All variables in the global scope have been moved into classes.
  69
  70 Conversion table:
  71
  72 | Old variable             | New variable                                | Notes     |
  73 | ------------------------ | ------------------------------------------- | --------- |
  74 | _xmlrpc_debuginfo        | PhpXmlRpc\Server::$_xmlrpc_debuginfo        | protected |
  75 | _xmlrpcs_capabilities    | NOT AVAILABLE YET                           |           |
  76 | _xmlrpcs_dmap            | NOT AVAILABLE YET                           |           |
  77 | _xmlrpcs_occurred_errors | PhpXmlRpc\Server::$_xmlrpcs_occurred_errors | protected |
  78 | _xmlrpcs_prev_ehandler   | PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler   | protected |
  79 | xmlrpcWPFObjHolder       | PhpXmlRpc\Wrapper::$objHolder               |           |
  80 | ...                      |                                             |           |
  81
  82
  83 Global functions cleanup
  84 ------------------------
  85
  86 Most functions in the global scope have been moved into classes.
  87 Some have been slightly changed.
  88
  89 | Old function                     | New function                                | Notes                                                  |
  90 | -------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
  91 | build_client_wrapper_code        | none                                        |                                                        |
  92 | build_remote_method_wrapper_code | PhpXmlRpc\Wrapper::buildWrapMethodSource    | signature changed                                      |
  93 | decode_chunked                   | PhpXmlRpc\Helper\Http::decodeChunked        |                                                        |
  94 | guess_encoding                   | PhpXmlRpc\Helper\XMLParser::guessEncoding   |                                                        |
  95 | has_encoding                     | PhpXmlRpc\Helper\XMLParser::hasEncoding     |                                                        |
  96 | is_valid_charset                 | PhpXmlRpc\Helper\Charset::isValidCharset    |                                                        |
  97 | iso8601_decode                   | PhpXmlRpc\Helper\Date::iso8601Decode        |                                                        |
  98 | iso8601_encode                   | PhpXmlRpc\Helper\Date::iso8601Encode        |                                                        |
  99 | php_2_xmlrpc_type                | PhpXmlRpc\Wrapper::php2XmlrpcType           |                                                        |
 100 | php_xmlrpc_decode                | PhpXmlRpc\Encoder::decode                   |                                                        |
 101 | php_xmlrpc_decode_xml            | PhpXmlRpc\Encoder::decodeXml                |                                                        |
 102 | php_xmlrpc_encode                | PhpXmlRpc\Encoder::encode                   |                                                        |
 103 | wrap_php_class                   | PhpXmlRpc\Wrapper::wrapPhpClass             | returns closures instead of function names by default  |
 104 | wrap_php_function                | PhpXmlRpc\Wrapper::wrapPhpFunction          | returns closures instead of function names by default  |
 105 | wrap_xmlrpc_method               | PhpXmlRpc\Wrapper::wrapXmrlpcMethod         | returns closures instead of function names by default  |
 106 | wrap_xmlrpc_server               | PhpXmlRpc\Wrapper::wrapXmrlpcServer         | returns closures instead of function names by default; |
 107 |                                  |                                             | returns an array ready for usage in dispatch map       |
 108 | xmlrpc_2_php_type                | PhpXmlRpc\Wrapper::Xmlrpc2phpType           |                                                        |
 109 | xmlrpc_debugmsg                  | PhpXmlRpc\Server::xmlrpc_debugmsg           |                                                        |
 110 | xmlrpc_encode_entitites          | PhpXmlRpc\Helper\Charset::encodeEntitites   |                                                        |
 111
 112
 113 Character sets and encoding
 114 ---------------------------
 115
 116 The default character set used by the library to deliver data to your app is now UTF8.
 117 It is also the character set that the library expects data from your app to be in (including method names).
 118 The value can be changed (to either US-ASCII or ISO-8859-1) by setting the desired value to
 119     PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding
 120
 121 Usage of closures for wrapping
 122 ------------------------------
 123
 124 ...
 125
 126
 127 Differences in server behaviour
 128 -------------------------------
 129
 130 The results for calls to system.listMethods and system.getCapabilities can not be set anymore via changes to
 131 global variables.
 132
 133
 134 Other
 135 -----
 136
 137 * when serialize() is invoked on a response and its payload can not be serialized, an exception is thrown instead of
 138   ending all execution
 139
 140 * all error messages now mention the class and method which generated name
 141
 142 * all library source code has been moved to the src/ directory
 143
 144 * all source code has been reformatted according to modern PSR standards
 145
 146
 147 Enabling compatibility with legacy code
 148 ---------------------------------------
 149
 150 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
 151 replacement, regardless of all of the changes mentioned above.
 152
 153 The magic happens via the xmlrpc.inc, xmlrpcs.inc and xmlrpc_wrappers.inc files, which have been kept solely for
 154 the purpose of backwards compatibility (you might notice that they are still in the 'lib' directory, whereas all of
 155 the refactored code now sits in the 'src' directory).
 156
 157 Of course, some minor changes where inevitable, and backwards compatibility can not be guaranteed at 100%.
 158 Below is the list of all known changes and possible pitfalls when enabling 'compatibility mode'.
 159
 160 ### Default character set used for application data
 161
 162 * when including the xmlrpc.inc file, the defalt character set used by the lib to give data to your app gets switched
 163   back to ISO-8859-1, as it was in previous versions
 164
 165 * 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
 166
 167         // code as was before
 168         include('xmlrpc.inc');
 169         $GLOBALS['xmlrpc_internalencoding'] = 'UTF-8';
 170         // new line needed now
 171         PhpXmlRpc\PhpXmlRpc::importGlobals();
 172
 173 ### Usage of global variables
 174
 175 * ALL global variables which existed after including xmlrpc.inc in version 3 still do exist after including it in v. 4
 176
 177 * Code which relies on using (as in 'reading') their value will keep working unchanged
 178
 179 * Changing the value of some of those variables does not have any effect anymore on library operation.
 180   This is true for:
 181
 182         $GLOBALS['xmlrpcI4']
 183         $GLOBALS['xmlrpcInt']
 184         $GLOBALS['xmlrpcBoolean']
 185         $GLOBALS['xmlrpcDouble']
 186         $GLOBALS['xmlrpcString']
 187         $GLOBALS['xmlrpcDatetTme']
 188         $GLOBALS['xmlrpcBase64']
 189         $GLOBALS['xmlrpcArray']
 190         $GLOBALS['xmlrpcStruct']
 191         $GLOBALS['xmlrpcValue']
 192         $GLOBALS['xmlrpcNull']
 193         $GLOBALS['xmlrpcTypes']
 194         $GLOBALS['xmlrpc_valid_parents']
 195         $GLOBALS['xml_iso88591_Entities']
 196
 197 * Changing the value of the other global variables will still have an effect on operation of the library, but only after
 198   a call to PhpXmlRpc::importGlobals()
 199
 200     Example:
 201
 202         // code as was before
 203         include('xmlrpc.inc');
 204         $GLOBALS['xmlrpc_null_apache_encoding'] = true;
 205         // new line needed now
 206         PhpXmlRpc\PhpXmlRpc::importGlobals();
 207
 208     Alternative solution:
 209
 210         include('xmlrpc.inc');
 211         PhpXmlRpc\PhpXmlRpc::$xmlrpc_null_apache_encoding = true;
 212
 213 * Not all variables which existed after including xmlrpcs.inc in version 3 are available
 214
 215     - $GLOBALS['_xmlrpcs_prev_ehandler'] has been replaced with protected static var PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler
 216         and is thus not available any more
 217
 218     - same for $GLOBALS['_xmlrpcs_occurred_errors']
 219
 220     - same for $GLOBALS['_xmlrpc_debuginfo']
 221
 222     - $GLOBALS['_xmlrpcs_capabilities'] and $GLOBALS['_xmlrpcs_dmap'] have been removed
 223
 224 ### Using typeof/class-name checks in your code
 225
 226 * if you are checking the types of returned objects, your checks will most likely fail.
 227   This is due to the fact that 'old' classes extend the 'new' versions, but library code that creates object
 228   instances will return the new classes.
 229
 230     Example:
 231
 232         is_a(php_xmlrpc_encode('hello world'), 'xmlrpcval') => false
 233         is_a(php_xmlrpc_encode('hello world'), 'PhpXmlRpc\Value') => true
 234
 235 ### server behaviour can not be changed by setting global variables (the ones starting with _xmlrpcs_ )
 236
 237 might be fixed later?