From 15029be085257a3bbd21af9af8274ea5404442cb Mon Sep 17 00:00:00 2001 From: gggeek Date: Wed, 18 Jan 2023 11:08:54 +0000 Subject: [PATCH] docs --- NEWS.md | 5 +++-- doc/manual/phpxmlrpc_manual.adoc | 21 ++++++++++++++------- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/NEWS.md b/NEWS.md index e7416ecf..e0a2eacd 100644 --- a/NEWS.md +++ b/NEWS.md @@ -34,6 +34,8 @@ * improved: method `Helper\Date::iso8601Encode` now accepts a DateTime input beside a timestamp +* improved: method `Server::add_to_map` has acquired a 6th parameter: `$parametersType = false` + * improved: removed usage of `extension_loaded` in favour of `function_exists` when checking for mbstring. This allows for mbstring functions to be polyfilled @@ -49,6 +51,7 @@ to a custom character set and the mbstring extension is enabled. It will be encoded instead in the specified character set. We expect this to affect few users, as setting `PhpXmlRpc::$internal_encoding` to a custom character set did not make a lot of sense beforehand + - parameters `$timeout` and `$method` are now considered deprecated in `Client::send()` and `Client::multicall()` for library extenders @@ -57,8 +60,6 @@ and reimplemented the `parse` methods, or wholesale replaced it, you will have to adapt your code - also, if you had reimplemented `XMLParser::parse`, be warned that the callers now treat differently results when `_xh['isf'] > 3` - - parameters `$timeout` and `$method` are now considered deprecated in `Client::send()` and `Client::multicall()` - - method `Server::add_to_map` has acquired a 6th parameter: `$parametersType = false` - new methods in helper classes: `Charset::knownCharsets`, `Http::parseAcceptHeader` - if you had been somehow interacting with private method `Client::_try_multicall`, be warned its returned data has changed: it now returns a Response for the cases in which it previously returned false, and an array of Response diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc index d1a774a2..c068366e 100644 --- a/doc/manual/phpxmlrpc_manual.adoc +++ b/doc/manual/phpxmlrpc_manual.adoc @@ -1438,21 +1438,28 @@ The guiding principle used to inform the development process and the version num * 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 +The distinction between __consumers__ and __extenders__ is defined as: 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 +* to avoid breaking compatibility with extenders, the library will not implement strict type declarations. 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 classes, interfaces, exceptions, class methods, constants and properties are allowed to be added in minor versions. + NB: this includes adding magic methods `\__get`, `\__set`, `\__call`, etc... to classes which did not have them * 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 +* types of function and method arguments are only allowed to be changed in major versions +* return types of functions and methods are only allowed to be changed in major versions +* existing function and method arguments, class methods and properties, interfaces, exceptions might be deprecated in + minor versions +* existing class methods and properties might be removed or renamed in minor versions, provided that their previous + incarnations are kept working via usage of php magic functions `\__get`, `\__set`, `\__call` and friends * 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 +* any class, method, property, interface, exception and constant documented using the `@internal` tag is considered not + to be part of the library's API and might not follow the rules above +* using deprecated methods and properties will eventually lead to deprecation errors being triggered - but that has not + yet been enabled 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) -- 2.47.0