first commit

lib/phpxmlrpc/doc/api_changes_v4.md

@@ -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?

lib/phpxmlrpc/doc/build/custom.fo.xsl

@@ -0,0 +1,103 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
+    xmlns:fo="http://www.w3.org/1999/XSL/Format">
+<!--
+ Customization xsl stylesheet for docbook to pdf transform
+ @author Gaetano Giunta
+ @copyright (c) 2007-2015 G. Giunta
+ @license code licensed under the BSD License
+ @todo make the xsl more dynamic: the path to import docbook.xsl could be f.e. rewritten/injected by the php user
+-->
+
+
+<!-- import base stylesheet -->
+<xsl:import href="../../../../vendor/docbook/docbook-xsl/fo/docbook.xsl"/>
+
+
+<!-- customization vars -->
+<xsl:param name="fop1.extensions">1</xsl:param>
+<xsl:param name="draft.mode">no</xsl:param>
+<xsl:param name="funcsynopsis.style">ansi</xsl:param>
+<xsl:param name="id.warnings">0</xsl:param>
+<xsl:param name="highlight.source">1</xsl:param>
+<xsl:param name="highlight.default.language">php</xsl:param>
+<xsl:param name="paper.type">A4</xsl:param>
+<xsl:param name="shade.verbatim">1</xsl:param>
+
+<xsl:attribute-set name="verbatim.properties">
+  <xsl:attribute name="font-size">80%</xsl:attribute>
+</xsl:attribute-set>
+
+
+<!-- elements added / modified -->
+<xsl:template match="funcdef/function">
+  <xsl:choose>
+    <xsl:when test="$funcsynopsis.decoration != 0">
+      <fo:inline font-weight="bold">
+        <xsl:apply-templates/>
+      </fo:inline>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:apply-templates/>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:text> </xsl:text>
+</xsl:template>
+
+<xsl:template match="funcdef/type">
+  <xsl:apply-templates/>
+  <xsl:text> </xsl:text>
+</xsl:template>
+
+<xsl:template match="void">
+  <xsl:choose>
+    <xsl:when test="$funcsynopsis.style='ansi'">
+      <xsl:text>( void )</xsl:text>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:text>( )</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template match="varargs">
+  <xsl:text>( ... )</xsl:text>
+</xsl:template>
+
+<xsl:template match="paramdef">
+  <xsl:variable name="paramnum">
+    <xsl:number count="paramdef" format="1"/>
+  </xsl:variable>
+  <xsl:if test="$paramnum=1">( </xsl:if>
+  <xsl:choose>
+    <xsl:when test="$funcsynopsis.style='ansi'">
+      <xsl:apply-templates/>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:apply-templates select="./parameter"/>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:choose>
+    <xsl:when test="following-sibling::paramdef">
+      <xsl:text>, </xsl:text>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:text> )</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template match="paramdef/type">
+  <xsl:apply-templates/>
+  <xsl:text> </xsl:text>
+</xsl:template>
+
+<!-- default values for function parameters -->
+<xsl:template match="paramdef/initializer">
+  <xsl:text> = </xsl:text>
+  <xsl:apply-templates/>
+</xsl:template>
+
+
+</xsl:stylesheet>

lib/phpxmlrpc/doc/build/custom.xsl

@@ -0,0 +1,91 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<!--
+ Customization xsl stylesheet for docbook to chunked html transform
+ @author Gaetano Giunta
+ @copyright (c) 2007-2015 G. Giunta
+ @license code licensed under the BSD License
+
+ @todo make the xsl more dynamic: the path to import chunk.xsl could be f.e. rewritten/injected by the php user.
+       This would be needed f.e. if the lib is installed as a dependency and is not the top-level composer project.
+       Note: according to http://stackoverflow.com/questions/9861355/using-dynamic-href-in-xslt-import-include this is
+       not easy to do - it would have to be done f.e. by the invoking php script...
+-->
+
+
+<!-- import base stylesheet -->
+<xsl:import href="../../../../vendor/docbook/docbook-xsl/xhtml/chunk.xsl"/>
+
+
+<!-- customization vars -->
+<xsl:param name="draft.mode">no</xsl:param>
+<xsl:param name="funcsynopsis.style">ansi</xsl:param>
+<xsl:param name="html.stylesheet">xmlrpc.css</xsl:param>
+<xsl:param name="id.warnings">0</xsl:param>
+
+
+<!-- elements added / modified -->
+
+<!-- space between function name and opening parenthesis -->
+<xsl:template match="funcdef" mode="ansi-nontabular">
+  <code>
+    <xsl:apply-templates select="." mode="class.attribute"/>
+    <xsl:apply-templates mode="ansi-nontabular"/>
+    <xsl:text> ( </xsl:text>
+  </code>
+</xsl:template>
+
+<!-- space between return type and function name -->
+<xsl:template match="funcdef/type" mode="ansi-nontabular">
+  <xsl:apply-templates mode="ansi-nontabular"/>
+  <xsl:text> </xsl:text>
+</xsl:template>
+
+<!-- space between last param and closing parenthesis, remove tailing semicolon -->
+<xsl:template match="void" mode="ansi-nontabular">
+  <code>void )</code>
+</xsl:template>
+
+<xsl:template match="varargs" mode="ansi-nontabular">
+  <xsl:text>...</xsl:text>
+  <code> )</code>
+</xsl:template>
+
+<xsl:template match="paramdef" mode="ansi-nontabular">
+  <xsl:apply-templates mode="ansi-nontabular"/>
+  <xsl:choose>
+    <xsl:when test="following-sibling::*">
+      <xsl:text>, </xsl:text>
+    </xsl:when>
+    <xsl:otherwise>
+      <code> )</code>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<!-- param types get code formatted (leave a space after type, as it is supposed to be before param name) -->
+<xsl:template match="paramdef/type" mode="ansi-nontabular">
+  <xsl:choose>
+    <xsl:when test="$funcsynopsis.decoration != 0">
+      <code>
+        <xsl:apply-templates mode="ansi-nontabular"/>
+      </code>
+    </xsl:when>
+    <xsl:otherwise>
+      <code>
+        <xsl:apply-templates mode="ansi-nontabular"/>
+      </code>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:text> </xsl:text>
+</xsl:template>
+
+<!-- default values for function parameters -->
+<xsl:template match="paramdef/initializer" mode="ansi-nontabular">
+  <xsl:text> = </xsl:text>
+  <xsl:apply-templates mode="ansi-nontabular"/>
+</xsl:template>
+
+
+</xsl:stylesheet>