prepare for release

Author: gggeek

NEWS.md

@@ -0,0 +1,14 @@
+## v1.0-alpha (2020/12/31)
+
+Hello world!
+
+The initial release of this lib comes at the very end of a difficult year. Let's hope next year will be better for everybody!
+
+All details about the status of the implementation can be found in the source code in file Xmlrpc.php.
+
+A high level overview is: everything is broadly working except for bugs and for the following missing features:
+- character set handling: at the moment only Latin1 (aka iso-8859-1) is supported - the `$encoding` argument does nothing
+  in `xmlrpc_decode()` and `xmlrpc_decode_request()`
+- the `$output_options` argument in `xmlrpc_encode_request()` does nothing
+- the `xmlrpc_parse_method_descriptions` and `xmlrpc_server_register_introspection_callback` functions exist but do nothing
+- xmlrpc server method `system.describeMethods` is not implemented

README.md

@@ -1,12 +1,28 @@
+Polyfill-XMLRPC
+===============
+
 A pure-php reimplementation of the API exposed by the native XML-RPC extension.
 
 Originally bundled as part of the [phpxmlrpc/extras](https://github.com/gggeek/phpxmlrpc-extras) package.
 
-*Work In Progress!*
-
 Known differences from the original extension
 ---------------------------------------------
 
+### Work in Progress!
+
+This library is not complete yet, and thus to be considered a Work in Progress.
+
+Main features missing are:
+- character set handling: at the moment only Latin1 (aka iso-8859-1) is supported - the $encoding argument does nothing in xmlrpc_decode() and xmlrpc_decode_request()
+- the $output_options argument in xmlrpc_encode_request() does nothing
+- the `xmlrpc_parse_method_descriptions` and `xmlrpc_server_register_introspection_callback` functions exist but do nothing
+- xmlrpc server method `system.describeMethods` is not implemented
+
+For a detailed list of all known differences compared to the behaviour of the PHP extension, see comments at the top of
+file [XmlRpc.php](src/XmlRpc.php).
+
+### Compatibility goals
+
 We strive to reproduce the same behaviour as the XML-RPC extension to the best "reasonable" extent.
 
 This means that the following are _not_ goals of this package:
@@ -17,8 +33,6 @@ This means that the following are _not_ goals of this package:
 - reproducing behaviour of the native extension which is clearly buggy
   Eg. the native extension will produce invalid xmlrpc requests when specific values are passed to an `xmlrpc_encode_request` call
 
-For a detailed list of known differences, see comments at the top of file [XmlRpc.php](src/XmlRpc.php).
-
 Installation and usage
 ----------------------
 

composer.json

@@ -11,7 +11,7 @@
     ],
     "require": {
         "php": "^5.3.0 || ^7.0 || ^8.0",
-        "phpxmlrpc/phpxmlrpc": "dev-master as 4.5.0-dev"
+        "phpxmlrpc/phpxmlrpc": "^4.5.0"
     },
     "require-dev": {
         "ext-curl": "*",

src/Server.php

@@ -23,6 +23,7 @@ public function register_introspection_callback($function)
      * @param array $desc
      * @return int 1 if anything got added to the docs, 0 otherwise
      * @see XMLRPC_ServerAddIntrospectionData in xmlrpc_intropspection.c
+     * @todo save as well in a new member of $this->dmap the combined methodList+typeList, so that it can be used by _xmlrpcs_describeMethods
      */
     public function add_introspection_data($desc)
     {
@@ -35,7 +36,6 @@ public function add_introspection_data($desc)
                     continue;
                 }
                 $methodName = $methodDesc['name'];
-                /// @todo save as well in a new member of $this->dmap the whole $methodDesc, so that it can be used by _xmlrpcs_describeMethods
                 if (isset($methodDesc['purpose'])) {
                     $this->dmap[$methodName]['docstring'] = $methodDesc['purpose'];
                     $out = 1;
@@ -86,6 +86,18 @@ public static function parse_method_descriptions($xml)
         return array();
     }
 
+    /**
+     * Reimplement to allow users to register their own 'system.' methods
+     * @param string $methName
+     * @return bool
+     */
+    protected function isSyscall($methName)
+    {
+        return in_array($methName, array(
+            'system.listMethods', 'system.methodHelp', 'system.methodSignature', 'system.multicall', 'system.getCapabilities', // 'system.describeMethods',
+        ));
+    }
+
     /**
      * @return array[]
      */

src/XmlRpc.php

@@ -50,6 +50,11 @@
  *   - calling `xmlrpc_server_add_introspection_data` with method signatures makes the server validate the number
  *     and type of incoming parameters in later calls to `xmlrpc_server_call_method`, relieving the developer from
  *     having to implement the same checks manually in her php functions
+ *   - marking input parameters as optional in the data passed to calls to `xmlrpc_server_add_introspection_data` and
+ *     `xmlrpc_server_register_introspection_callback` will change the number of method signatures displayed by the
+ *     server in responses to calls to `system.methodSignature`.
+ *     Eg. passing in one signature with one optional param will result in two signatures displayed, one with no params
+ *     and one with one param
  */
 
 namespace PhpXmlRpc\Polyfill\XmlRpc;