Update docs - in particular add one (incomplete) file describing all API changes...

[plcapi.git] / NEWS

XML-RPC for PHP version 4.0.0 - 2015/Y/Z

This release does away with the past and starts a transition to modern-world php.

Code has been heavily refactored, taking care to preserve backwards compatibility as much as possible,
but some breackage is to be expected.

The minimum required php version has been increased to 5.3, even though we strongly urge you to use
more recent versions.

PLEASE READ CAREFULLY THE NOTES BELOW to insure a smooth upgrade.

* new: introduction of namespaces and full OOP.

  All php classes have been renamed and moved to separate files.
  Class autoloading can now be done in accord with the PSR-4 standard.
  All global variables and global functions have been removed.

  Backward compatibility is maintained via lib/xmlrpc.inc, lib/xmlrpcs.inc and lib/xmlrpc_wrappers.inc.
  For more details, head on to doc/api_changes_v4.md

* changed: the default encoding delivered from the library to your code is now utf8.
  It can be changed at anytime setting a value to PhpXmlRpc\PhpXmlRpc::$xmlrpc_internalencoding

* improved: no need to call anymore $client->setSSLVerifyHost(2) to silence a curl warning when using https
  with recent curl builds

* improved: a specific option allows users to decide the version of SSL to use for https calls.
  This is useful f.e. for the testing suite, when the server target of calls has no proper ssl certificate,
  and the cURL extension has been compiled with GnuTLS (such as on Travis VMs)

* improved: the function wrap_php_function() now can be used to wrap closures (it is now a method btw)

* improved: all wrap_something() functions now return a closure by default instead of a function name

* improved: debug messages are not html-escaped any more when executing from the command line

* improved: the library is now tested using Travis ( https://travis-ci.org/ ).
  Tests are executed using all php versions from 5.3 to 7.0 nightly, plus HHVM; code-coverage information
  is generated using php 5.6 and uploaded to both Code Coverage and Scrutinizer online services

* improved: phpunit is now installed via composer, not bundled anymore

* improved: when phpunit is used to generate code-coverage data, the code executed server-side is accounted for

* improved: the test suite has basic checks for the debugger and demo files

* improved: more tests in the test suite

* fixed: the server would fail to decode a request with ISO-8859-1 payload and character set declaration in the xml
  prolog only

* fixed: the client would fail to decode a response with ISO-8859-1 payload and character set declaration in the xml
  prolog only

* fixed: the function decode_xml() would not decode an xml with character set declaration in the xml prolog

* fixed: the client can now successfully call methods using ISO-8859-1 or UTF-8 characters in their name

* fixed: the debugger would fail sending a request with ISO-8859-1 payload (it missed the character set declaration).
  It would have a hard time coping with ISO-8859-1 in other fields, such as e.g. the remote method name

* improved: the debugger is displayed using UTF-8, making it more useful to debug any kind of service

* improved: echo all debug messages even when there are characters in them which php deems to be in a wrong encoding;
  previously those messages would just disappear (this is visible e.g. in the debugger)

* changed: debug info handling
    - at debug level 1, the rebuilt php objects are not dumped to screen (server-side already did that)
    - at debug level 1, curl communication info are not dumped to screen
    - at debug level 1, the tests echo payloads of failures; at debug level 2 all payloads

* improved: makefiles have been replaced with a php_based pakefile

* improved: the source for the manual is stored in asciidoc format, which can be displayed natively by GitHub
  with nice html formatting. Also the HTML version generated by hand and bundled in tarballs is much nicer
  to look at than previous versions

* improved: all php code is now formatted according to the PSR-2 standard


XML-RPC for PHP version 3.0.0 - 2014/6/15

This release corrects all bugs that have been reported and successfully reproduced since
version 3.0.0 beta.

The requirements have increased to php 5.1.0 - which is still way older than what you should be running for any serious
purpose, really.

It also is the first release to be installable via composer.

See the Changelog file or the pdf docs for a complete list of changes.


XML-RPC for PHP version 3.0.0 beta - 2009/09/05

This is the first release of the library to only support PHP 5.
Some legacy code has been removed, and support for features such as exceptions
and dateTime objects introduced.

The "beta" tag is meant to indicate the fact that the refactoring has been more widespread
than in precedent releases and that more changes are likely to be introduced with time -
the library is still considered to be production quality.

* improved: removed all usage of php functions deprecated in php 5.3, usage of assign-by-ref when creating new objects
  etc...
* improved: add support for the <ex:nil/> tag used by the apache library, both in input and output
* improved: add support for dateTime objects in both in php_xmlrpc_encode and as parameter for constructor of xmlrpcval
* improved: add support for timestamps as parameter for constructor of xmlrpcval
* improved: add option 'dates_as_objects' to php_xmlrpc_decode to return dateTime objects for xmlrpc datetimes
* improved: add new method SetCurlOptions to xmrlpc_client to allow extra flexibility in tweaking http config, such as
  explicitly binding to an ip address
* improved: add new method SetUserAgent to xmrlpc_client to to allow having different user-agent http headers
* improved: add a new member variable in server class to allow fine-tuning of the encoding of returned values when the
  server is in 'phpvals' mode
* improved: allow servers in 'xmlrpcvals' mode to also register plain php functions by defining them in the dispatch map
  with an added option
* improved: catch exceptions thrown during execution of php functions exposed as methods by the server
* fixed: bad encoding if same object is encoded twice using php_xmlrpc_encode


XML-RPC for PHP version 2.2.2 - 2009/03/16

This release corrects all bugs that have been reported and sucesfully reproduced since
version 2.2.1.
Regardless of the intimidating message about dropping PHP 4 support, it still does
support that ancient, broken and insecure platform.


* fixed: php warning when receiving 'false' in a bool value
* fixed: improve robustness of the debugger when parsing weird results from non-compliant servers
* fixed: format floating point values using the correct decimal separator even when php locale is set to one that uses
  comma
* fixed: use feof() to test if socket connections are to be closed instead of the number of bytes read (rare bug when
  communicating with some servers)
* fixed: be more tolerant in detection of charset in http headers
* fixed: fix encoding of UTF8 chars outside of the BMP plane
* fixed: fix detection of zlib.output_compression
* improved: allow the add_to_map server method to add docs for single params too
* improved: added the possibility to wrap for exposure as xmlrpc methods plain php class methods, object methods and
  even whole classes


XML-RPC for PHP version 2.2.1 - 2008/03/06

This release corrects all bugs that have been reported and sucesfully reproduced.
It is the last release of the library that will support PHP 4.

* fixed: work around bug in php 5.2.2 which broke support of HTTP_RAW_POST_DATA
* fixed: is_dir parameter of setCaCertificate() method is reversed
* fixed: a php warning in xmlrpc_client creator method
* fixed: parsing of '1e+1' as valid float
* fixed: allow errorlevel 3 to work when prev. error handler was a static method
* fixed: usage of client::setcookie() for multiple cookies in non-ssl mode
* improved: support for CP1252 charset is not part or the library but almost possible
* improved: more info when curl is enabled and debug mode is on


XML-RPC for PHP version 2.2 - 2007/02/25

This release corrects a couple of bugs and adds a few minor features.

* fixed: debugger errors on php installs with magic_quotes_gpc on
* fixed: support for https connections via proxy
* fixed: wrap_xmlrpc_method() generated code failed to properly encode php objects
* improved: slightly faster encoding of data which is internally UTF-8
* improved: debugger always generates a 'null' id for jsonrpc if user omits it
* new: debugger can take advantage of a graphical value builder
  (it has to be downloaded separately, as part of jsxmlrpc package)
* new: support for the <NIL/> xmlrpc extension
* new: server support for the system.getCapabilities xmlrpc extension
* new: wrap_xmlrpc_method() accepts two new options: debug and return_on_fault


XML-RPC for PHP version 2.1 - 2006/08/28

This release corrects quite a few bugs and adds some interesting new features.
There is a minor security enhancement and overall speedup too.

It has been tested with PHP 4.0.5 up to 4.4.4 and 5.1.5.
Please note that 404pl1 is NOT supported, and has not been since 2.0.

*** PLEASE READ CAREFULLY BELOW ***

CHANGES THAT MIGHT AFFECT DEPLOYED APPLICATIONS:

The wrap_php_function and wrap_xmlrpc_method functions have been moved out of
the base library file xmlrpc.inc into a file of their own: xmlrpc_wrappers.inc.
You will have to include() / require() it in your scripts if you have been using
those functions.

For increased security, the automatic rebuilding of php object instances out of
received xmlrpc structs in wrap_xmlrpc_method() has been disabled (but it can be
optionally reenabled).

The constructor of xmlrpcval() values has seen major changes, and it will not
throw a php warning anymore when invoked using an unknown xmlrpc type: the
error will only be written to php error log. Also new xmlrpcval('true', 'boolean')
is not supported anymore.

MAJOR IMPROVEMENTS:

The new function php_xmlrpc_decode_xml() will take the xml representation of
either an xmlrpc request, response or single value and return the corresponding
php-xmlrpc object instance.

Both wrap_php_function() and wrap_xmlrpc_method() functions accept many more
options to fine tune their behaviour, including one to return the php code to
be saved and later used as standalone php script.

A new function wrap_xmlrpc_server() has been added, to wrap all (or some) of the
methods exposed by a remote xmlrpc server into a php class.

Lib internals have been modified to provide better support for grafting extra
functionality on top of it. Stay tuned for future releases of the EXTRAS package.

Last but not least a new file has been added: verify_compat.php, to help users
diagnose the level of compliance of the current php install with the library.

CHANGELOG IN DETAIL:

* fixed bug 1311927: client not playing nice with some proxy/firewall on ports != 80
* fixed bug 1334340: all ereg_ functions have been replaced with corresponding preg_
* fixed bug: wrong handling of 'deflate' http encoding, both server and client side
* fixed bug: sending compressed responses when php output compression is enabled was not working
* fixed bug: addarray() and addstruct() where not returning 1 when adding data to already initialized values
* fixed bug: non-ascii chars used in struct element names where not being encoded correctly
* restored compatibility with php 4.0.5 (for those poor souls still stuck on it)
* server->service() now returns either the payload or xmlrpcresp instance
* server->add_to_map() now accepts methods with no param definitions
* added new function: php_xmlrpc_decode_xml()
* added new function: wrap_xmlrpc_server()
* major improvements and security enhancements to wrap_php_function() and wrap_xmlrpc_method()
* documentation for single parameters of exposed methods can be added to the dispatch map
  (and turned into html docs in conjunction with a future release of the extras package)
* full response payload is saved into xmlrpcresp object for further debugging
* stricter parsing of incoming xmlrpc messages: two more invalid cases are now detected
  (double data element inside array and struct/array after scalar inside value element)
* debugger can now generate code that wraps a remote method into php function (works for jsonrpc, too)
* debugger has better support for being activated via a single GET call (for integration into other tools?)
* more logging of errors in a lot of situations
* javadoc documentation of lib files almost complete
* the usual amount of new testcases in the testsuite
* many performance tweaks and code cleanups
* added foundation for emulating the API of the xmlrpc extension (extras package needed)


XML-RPC for PHP version 2.0 - 2006/04/24

I'm pleased to announce XML-RPC for PHP version 2.0, final.

With respect to the last release candidate, this release corrects a few small
bugs and adds a couple of new features: more authentication options (digest and
ntlm for servers, ntlm for proxies, and some https custom certificates stuff);
all the examples have been reviewed and some demo files added,
including a ready-made xmlrpc proxy (useful e.g. for ajax calls, when the xmlrpc
client is a browser); the server logs more warning messages for incorrect situations;
both client and server are more tolerant of commonly-found mistakes.
The debugger has been upgraded to reflect the new client capabilities.

In greater detail:

* fixed bug: method xmlrpcval::structmemexists($value) would not work
* fixed bug: wrap_xmlrpc_method would fail if invoked with a client object that
  has return_type=phpvals
* fixed bug: in case of call to client::multicall without fallback and server error
* fixed bug: recursive serialization of xmlrpcvals loosing specified UTF8 charset
* fixed bug: serializing to ISO-8859-1 with php 5 would raise an error if non-ascii
  chars where found when decoding
* new: client can use NTLM and Digest authentication methods for https and http 1.1
  connections; authentication to proxy can be set to NTLM, too
* new: server tolerates user functions returning a single xmlrpcval object instead
  of an xmlrpcresp
* new: server does more checks for presence and correct return type of user
  coded method handling functions, and logs inconsistencies to php error log
* new: client method SetCaCertificate($cert, $is_dir) to validate server against
* new: both server and client tolerate receiving 'true' and 'false' for bool values
  (which btw are not valid according to the xmlrpc spec)


XML-RPC for PHP version 2.0RC3 - 2006/01/22

This release corrects a few bugs and adds some interesting new features.
It has been tested with PHP up to 4.4.2 and 5.1.2.

* fixed bug: server not recognizing clients that declare support for http compression
* fixed bug: serialization of new xmlrpcval (8, 'string') when internal encoding
  set to UTF-8
* fixed bug: serialization of new xmlrpcval ('hello', 'int') would produce
  invalid xml-rpc
* new: let the server accept 'class::method' syntax in the dispatch map
* new: php_xmlrpc_decode() can decode xmlrpcmessage objects
* new: both client and server can specify a charset to be used for serializing
  values instead of the default 'US-ASCII+xml-entities-for-other-characters'.
  Values allowed: ISO-8859-1 and UTF-8
* new: the server object can register 'plain' php functions instead of functions
  that accept a single parameter of type xmlrpcmsg. Faster, uses less memory
  (but comes with minor drawbacks as well, read the manual for more details)
* new: client::setDebug(2) can be used to have the request payload printed to
  screen before being sent
* new: server::service($data) lets user parse data other than POST body, for
  easier testing / subclassing
* changed: framework-generated debug messages are sent back by the server base64
  encoded, to avoid any charset/xml compatibility problem
* other minor fixes

The usual refactoring of a lot of (private) methods has taken place, with new
parameters added to some functions.
Javadoc documentation has been improved a lot.
The HTML documentation has been shuffled around a bit, hoping to give it a more
logical organization.

The experimental support for the JSON protocol has been removed, and will be
packaged as a separate download with some extra very interesting stuff (human
readable auto-generated documentation, anyone?).


XML-RPC for PHP version 2.0RC2 - 2005/11/22

This release corrects a few bugs and adds basically one new method for better
HTTPS support:

 * fixed two bugs that prevented xmlrpc calls to take place over https
 * fixed two bugs that prevented proper recognition of xml character set
   when it was declared inside the xml prologue
 * added xmlrpc_client::setKey($key, $keypass) method, to allow using client
   side certificates for https connections
 * fixed bug that prevented proper serialization of string xmlrpcvals when
   $xmlrpc_internalencoding was set to UTF-8
 * fixed bug in xmlrpc_server::echoInput() (and marked method as deprecated)
 * correctly set cookies/http headers into xmlrpcresp objects even when the
   send() method call fails for some reason
 * added a benchmark file in the testsuite directory

A couple of (private/protected) methods have been refactored, as well as a
couple of extra parameters added to some (private) functions - this has no
impact on the public API and should be of interest primarily to people extending
/ subclassing the lib.

There is also new, PARTIAL support for the JSON-RPC protocol, implemented in
two files in the extras dir (more info about json-rpc at http://json-rpc.org)


XML-RPC for PHP version 2.0RC1 - 2005/10/03

I'm pleased to announce XML-RPC for PHP version 2.0, release candidate 1.

This release introduces so many new features it is almost impossible to list them
here, making the library finally on pair with, if not more advanced than, any other
similar offer (e.g. the PEAR XMLRPC package or the Incutio IXR library).
No, really, trust me.

The minimum supported PHP version is now 4.2 - natively - or 4.0.4pl1 - by usage of
a couple of compatibility classes (code taken from PEAR php_compat package).

The placement of files and directories in the distribution has been deeply modified,
in the hope of making it more clear, now that the file count has increased.
I hope you find it easy.

Support for "advanced" HTTP features such as cookies, proxies and keep-alives has
been added at last.

It is now much easier to convert between xmlrpcval objects and php values, and
in fact php_xmlrpc_encode and php_xmlrpc_decode are now the recommended methods
for all cases, except when encoding base64 data.

Two new (experimental) functions have been added, allowing automagic conversion
of a php function into an xmlrpc method to be exposed and vice-versa.

PHP objects can be now automatically serialized as xmlrpc struct values and
correctly deserialized on the other end of the transmission, provided that the
same class definition is present on both sides and no object members are of
type resource.

A lot of the existing class methods have been overloaded with extra parameters
or new functionality, and a few added ex-novo, making usage easier than ever.

A complete debugger solution is included in the distribution. It needs a web server
to run (a freely available version of the same debugger is accessible online, it
can be found at http://phpxmlrpc.sourceforge.net).

For a more detailed list of changes, please read carefully chapter 2 of the
included documentation, or, even better, take a look at the source code, which
is commented in javadoc style quite a bit.


XML-RPC for PHP version 1.2 - 2005/08/14

This removes all use of eval(), which is a potential security problem.
All users are encouraged to upgrade as soon as possible.
As of this release we are no longer php3-compatible.


XML-RPC for PHP version 1.1.1 - 2005/06/30

This is a security vulnerability fix release.
All users are invited to upgrade as soon as possible.


XML-RPC for PHP version 1.1 - 2005/05/03

I'm pleased to announce XML-RPC for PHP version 1.1
It's taken two years to get to the this point, but here we are, finally.

This is a bugfix and maintenance release. No major new features have been added.
All known bugs have been ironed out, unless fixing would have meant breaking
the API.
The code has been tested with PHP 3, 4 and 5, even tough PHP 4 is the main
development platform (and some warnings will be emitted when running PHP5).

Noteworthy changes include:

 * do not clash any more with the EPI xmlrpc extension bundled with PHP 4 and 5
 * fixed the unicode/charset problems that have been plaguing the lib for years
 * proper parsing of int and float values prepended with zeroes or the '+' char
 * accept float values in exponential notation
 * configurable http user-agent string
 * use the same timeout on client socket reads as used for connecting
 * more explicative error messages in xmlrpcresponse in many cases
 * much more tolerant parsing of malformed http responses from xmlrpc servers
 * fixed memleak that prevented the client to be used in never-ending scripts
 * parse bigger xmlrpc messages without crashing (1MB in size or more)
 * be tolerant to xmlrpc responses generated on public servers that add
   javascript advertising at the end of hosted content
 * the lib generates quite a few less PHP warnings during standard operation

This is the last release that will support PHP 3.
The next release will include better support for PHP 5 and (possibly) a slew of
new features.

The changelog is available at:
http://cvs.sourceforge.net/viewcvs.py/phpxmlrpc/xmlrpc/ChangeLog?view=markup

Please report bugs to the XML-RPC PHP mailing list or to the sourceforge project
pages at http://sourceforge.net/projects/phpxmlrpc/


XML-RPC for PHP version 1.0

I'm pleased to announce XML-RPC for PHP version 1.0 (final). It's taken
two years to get to the 1.0 point, but here we are, finally.  The major change
is re-licensing with the BSD open source license, a move from the custom
license previously used.

After this release I expect to move the project to SourceForge and find
another primary maintainer for the code.  More details will follow to the
mailing list.

It can be downloaded from http://xmlrpc.usefulinc.com/php.html

Comprehensive documentation is available in the distribution, but you
can also browse it at http://xmlrpc.usefulinc.com/doc/

Bugfixes in this release include:

 * Small fixes and tidying up.

New features include:

 * experimental support for SSL via the curl extensions to PHP.  Needs
   PHP 4.0.2 or greater, but not PHP 4.0.6 which has broken SSL support.

The changelog is available at: http://xmlrpc.usefulinc.com/ChangeLog.txt

Please report bugs to the XML-RPC PHP mailing list, of which more details are
available at http://xmlrpc.usefulinc.com/list.html, or to
<xmlrpc@usefulinc.com>.


XML-RPC for PHP version 1.0 beta 9

I'm pleased to announce XML-RPC for PHP version 1.0 beta 9. This is
is largely a bugfix release.

It can be downloaded from http://xmlrpc.usefulinc.com/php.html

Comprehensive documentation is available in the distribution, but you
can also browse it at http://xmlrpc.usefulinc.com/doc/

Bugfixes in this release include:

 * Fixed string handling bug where characters between a </string>
   and </value> tag were not ignored.

 * Added in support for PHP's native boolean type.

New features include:

 * new getval() method (experimental only) which has support for
   recreating nested arrays.
 * fledgling unit test suite
 * server.php has support for basic interop test suite

The changelog is available at: http://xmlrpc.usefulinc.com/ChangeLog.txt

Please test this as hard as possible and report bugs to the XML-RPC PHP
mailing list, of which more details are available at
http://xmlrpc.usefulinc.com/list.html, or to <xmlrpc@usefulinc.com>.


XML-RPC for PHP version 1.0 beta 8

I'm pleased to announce XML-RPC for PHP version 1.0 beta 8.

This release fixes several bugs and adds a couple of new helper
functions. The most critical change in this release is that you can no
longer print debug info in comments inside a server method -- you must
now use the new xmlrpc_debugmsg() function.

It can be downloaded from http://xmlrpc.usefulinc.com/php.html

Comprehensive documentation is available in the distribution, but you
can also browse it at http://xmlrpc.usefulinc.com/doc/

Bugfixes in this release include:

 * fixed whitespace handling in values
 * correct sending of Content-length from the server

New features include:

 * xmlrpc_debugmsg() method allows sending of debug info in comments in
   the return payload from a server

 * xmlrpc_encode() and xmlrpc_decode() translate between xmlrpcval
   objects and PHP language arrays. They aren't suitable for all
   datatypes, but can speed up coding in simple scenarios. Thanks to Dan
   Libby for these.

The changelog is available at: http://xmlrpc.usefulinc.com/ChangeLog.txt

Please test this as hard as possible and report bugs to the XML-RPC PHP
mailing list, of which more details are available at
http://xmlrpc.usefulinc.com/list.html, or to <xmlrpc@usefulinc.com>.


XML-RPC for PHP version 1.0 beta 7

I'm pleased to announce XML-RPC for PHP version 1.0 beta 7. This is
fixes some critical bugs that crept in. If it shows itself to be stable
then it'll become the 1.0 release.

It can be downloaded from http://xmlrpc.usefulinc.com/php.html

Comprehensive documentation is available in the distribution, but you
can also browse it at http://xmlrpc.usefulinc.com/doc/

Bugfixes in this release include:

 * Passing of booleans should now work as expected
 * Dollar signs and backslashes in strings should pass OK
 * addScalar() now works properly to append to array vals

New features include:

 * Added support for HTTP Basic authorization through the
   xmlrpc_client::setCredentials method.

 * Added test script and method for verifying correct passing of
         booleans

The changelog is available at: http://xmlrpc.usefulinc.com/ChangeLog.txt

Please test this as hard as possible and report bugs to the XML-RPC PHP
mailing list, of which more details are available at
http://xmlrpc.usefulinc.com/list.html, or to <xmlrpc@usefulinc.com>.


XML-RPC for PHP version 1.0 beta 6

I'm pleased to announce XML-RPC for PHP version 1.0 beta 6. This is the
final beta before the 1.0 release.

It can be downloaded from http://xmlrpc.usefulinc.com/php.html

Comprehensive documentation is available in the distribution, but you
can also browse it at http://xmlrpc.usefulinc.com/doc/

New features in this release include:

 * Perl and Python test programs for the demo server
 * Proper fault generation on a non-"200 OK" response from a remote host
 * Bugfixed base64 decoding
 * ISO8601 helper routines for translation to and from UNIX timestamps
 * reorganization of code to allow eventual integration of alternative
   transports

The changelog is available at: http://xmlrpc.usefulinc.com/ChangeLog.txt

Please test this as hard as possible and report bugs to the XML-RPC PHP
mailing list, of which more details are available at
http://xmlrpc.usefulinc.com/list.html, or to <xmlrpc@usefulinc.com>.