1 API Changes between library versions 3 and 4
2 ============================================
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.
10 Instead, it is recommended to rely on class autoloading.
12 * If you are using Composer, just install the library by declaring it as dependency for your project in composer.json
16 "phpxmlrpc/phpxmlrpc": "~4.0"
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:
23 include_once <path to library> . "/src/Autoloader.php";
24 PhpXmlRpc\Autoloader::register();
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
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.
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 |
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:
55 | Class | Method | Notes |
56 | --------- | ----------- | -------------------------------------- |
57 | xmlrpcval | count | implements interface Countable |
58 | xmlrpcval | getIterator | implements interface IteratorAggregate |
61 Global variables cleanup
62 ------------------------
64 All variables in the global scope have been moved into classes.
68 | Old variable | New variable | Notes |
69 | ------------------------ | ------------------------------------------- | --------- |
70 | _xmlrpc_debuginfo | PhpXmlRpc\Server::$_xmlrpc_debuginfo | protected |
71 | _xmlrpcs_capabilities | NOT AVAILABLE YET | |
72 | _xmlrpcs_dmap | NOT AVAILABLE YET | |
73 | _xmlrpcs_occurred_errors | PhpXmlRpc\Server::$_xmlrpcs_occurred_errors | protected |
74 | _xmlrpcs_prev_ehandler | PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler | protected |
75 | xmlrpcWPFObjHolder | PhpXmlRpc\Wrapper::$objHolder | |
79 Global functions cleanup
80 ------------------------
82 Most functions in the global scope have been moved into classes.
83 Some have been slightly changed.
85 | Old function | New function | Notes |
86 | -------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
87 | build_client_wrapper_code | none | |
88 | build_remote_method_wrapper_code | PhpXmlRpc\Wrapper::buildWrapMethodSource | signature changed |
89 | decode_chunked | PhpXmlRpc\Helper\Http::decodeChunked | |
90 | guess_encoding | PhpXmlRpc\Helper\XMLParser::guessEncoding | |
91 | has_encoding | PhpXmlRpc\Helper\XMLParser::hasEncoding | |
92 | is_valid_charset | PhpXmlRpc\Helper\Charset::isValidCharset | |
93 | iso8601_decode | PhpXmlRpc\Helper\Date::iso8601Decode | |
94 | iso8601_encode | PhpXmlRpc\Helper\Date::iso8601Encode | |
95 | php_2_xmlrpc_type | PhpXmlRpc\Wrapper::php2XmlrpcType | |
96 | php_xmlrpc_decode | PhpXmlRpc\Encoder::decode | |
97 | php_xmlrpc_decode_xml | PhpXmlRpc\Encoder::decodeXml | |
98 | php_xmlrpc_encode | PhpXmlRpc\Encoder::encode | |
99 | wrap_php_class | PhpXmlRpc\Wrapper::wrapPhpClass | returns closures instead of function names by default |
100 | wrap_php_function | PhpXmlRpc\Wrapper::wrapPhpFunction | returns closures instead of function names by default |
101 | wrap_xmlrpc_method | PhpXmlRpc\Wrapper::wrapXmrlpcMethod | returns closures instead of function names by default |
102 | wrap_xmlrpc_server | PhpXmlRpc\Wrapper::wrapXmrlpcServer | returns closures instead of function names by default; |
103 | | | returns an array ready for usage in dispatch map |
104 | xmlrpc_2_php_type | PhpXmlRpc\Wrapper::Xmlrpc2phpType | |
105 | xmlrpc_debugmsg | PhpXmlRpc\Server::xmlrpc_debugmsg | |
106 | xmlrpc_encode_entitites | PhpXmlRpc\Helper\Charset::encodeEntitites | |
109 Character sets and encoding
110 ---------------------------
112 The default character set used by the library to deliver data to your app is now UTF8.
113 It is also the character set that the library expects data from your app to be in (including method names).
114 The value can be changed (to either US-ASCII or ISO-8859-1) by setting teh desired value to
115 PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding
117 Usage of closures for wrapping
118 ------------------------------
123 Differences in server behaviour
124 -------------------------------
126 The results for calls to system.listMethods and system.getCapabilities can not be set anymore via changes to
133 * when serialize() is invoked on a response and its payload can not be serialized, an exception is thrown instead of
136 * all error messages now mention the class and method which generated name
138 * all library source code has been moved to the src/ directory
140 * all source code has been reformatted according to modern PSR standards
143 Enabling compatibility with legacy code
144 ---------------------------------------
146 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
147 replacement, regardless of all of the changes mentioned above.
149 The magic happens via the xmlrpc.inc, xmlrpcs.inc and xmlrpc_wrappers.inc files, which have been kept solely for
150 the purpose of backwards compatibility (you might notice that they are still in the 'lib' directory, whereas all of
151 the refactored code now sits in the 'src' directory).
153 Of course, some minor changes where inevitable, and backwards compatibility can not be guaranteed at 100%.
154 Below is the list of all known changes and possible pitfalls when enabling 'compatibility mode'.
156 ### Default character set used for application data
158 * when including the xmlrpc.inc file, the defalt character set used by the lib to give data to your app gets switched
159 back to ISO-8859-1, as it was in previous versions
161 * 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
163 // code as was before
164 include('xmlrpc.inc');
165 $GLOBALS['xmlrpc_internalencoding'] = 'UTF-8';
166 // new line needed now
167 PhpXmlRpc\PhpXmlRpc::importGlobals();
169 ### Usage of global variables
171 * ALL global variables which existed after including xmlrpc.inc in version 3 still do exist after including it in v. 4
173 * Code which relies on using (as in 'reading') their value will keep working unchanged
175 * Changing the value of some of those variables does not have any effect anymore on library operation.
179 $GLOBALS['xmlrpcInt']
180 $GLOBALS['xmlrpcBoolean']
181 $GLOBALS['xmlrpcDouble']
182 $GLOBALS['xmlrpcString']
183 $GLOBALS['xmlrpcDatetTme']
184 $GLOBALS['xmlrpcBase64']
185 $GLOBALS['xmlrpcArray']
186 $GLOBALS['xmlrpcStruct']
187 $GLOBALS['xmlrpcValue']
188 $GLOBALS['xmlrpcNull']
189 $GLOBALS['xmlrpcTypes']
190 $GLOBALS['xmlrpc_valid_parents']
191 $GLOBALS['xml_iso88591_Entities']
193 * Changing the value of the other global variables will still have an effect on operation of the library, but only after
194 a call to PhpXmlRpc::importGlobals()
198 // code as was before
199 include('xmlrpc.inc');
200 $GLOBALS['xmlrpc_null_apache_encoding'] = true;
201 // new line needed now
202 PhpXmlRpc\PhpXmlRpc::importGlobals();
204 Alternative solution:
206 include('xmlrpc.inc');
207 PhpXmlRpc\PhpXmlRpc::$xmlrpc_null_apache_encoding = true;
209 * Not all variables which existed after including xmlrpcs.inc in version 3 are available
211 - $GLOBALS['_xmlrpcs_prev_ehandler'] has been replaced with protected static var PhpXmlRpc\Server::$_xmlrpcs_prev_ehandler
212 and is thus not available any more
214 - same for $GLOBALS['_xmlrpcs_occurred_errors']
216 - same for $GLOBALS['_xmlrpc_debuginfo']
218 - $GLOBALS['_xmlrpcs_capabilities'] and $GLOBALS['_xmlrpcs_dmap'] have been removed
220 ### Using typeof/class-name checks in your code
222 * if you are checking the types of returned objects, your checks will most likely fail.
223 This is due to the fact that 'old' classes extend the 'new' versions, but library code that creates object
224 instances will return the new classes.
228 is_a(php_xmlrpc_encode('hello world'), 'xmlrpcval') => false
229 is_a(php_xmlrpc_encode('hello world'), 'PhpXmlRpc\Value') => true
231 ### server behaviour can not be changed by setting global variables (the ones starting with _xmlrpcs_ )
233 might be fixed later?