From: gggeek <giunta.gaetano@gmail.com>
Date: Tue, 3 Jan 2023 18:01:07 +0000 (+0000)
Subject: WIP docs
X-Git-Tag: 4.9.4~29
X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=d1e4d14bb80088cee60b2504b570f8458b9e61cf;p=plcapi.git

WIP docs
---

diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc
index c01e1196..0961dea3 100644
--- a/doc/manual/phpxmlrpc_manual.adoc
+++ b/doc/manual/phpxmlrpc_manual.adoc
@@ -1074,9 +1074,21 @@ $val = $encoder::decodeXml($text);
 if ($val) echo 'Found a value of type ' . $val->kindOf(); else echo 'Found invalid xml';
 ----
 
-=== Logging
+=== Errors and Logging
 
-@TODO...
+Many of the classes in this library by default use the php error logging facilities to log errors in case there
+is some unexpected but non-fatal event happening, such as f.e. when an invalid xml-rpc request or response are received.
+Going straight to the log instead of triggering a php warning or error has the advantage of not breaking the xml-rpc
+output when the issue is happening within the context of an xmlrpc-server and `display_errors` is enabled.
+
+In case things are not going as you expect, please check the error log first for the presence of any messages from
+PHPXMLRPC which could be useful in troubleshooting what is going on under the hood.
+
+You can customize the way error messages are traced via the static method `setLogger` available for the classes
+`Client`, `Encoder`, `Request`, `Server` and `Value`. Keep in mind that for the moment, classes `Charset`, `HTTP` and
+`XMLParser` do not allow the same customization without hacking the `PhpXmlRpc\Logger` class. Last but not least, be
+aware that the same Logger is also responsible for echoing to screen the debug messages produced by the Client when its
+debug level has been set; this allows to customize the debugging process in the same way.
 
 === Transferring PHP objects over XML-RPC
 
@@ -1477,7 +1489,22 @@ To find out what the server is really returning to your client, you have to enab
 
 If what you need is to save the responses received from the server as xml, you have multiple options:
 
-1- use the `serialize` method on the Response object.
+1 - use the Response's `httpResponse` method
+
+[source, php]
+----
+$resp = $client->send($msg);
+if (!$resp->faultCode())
+    $data_to_be_saved = $resp->httpResponse()['raw_data'];
+----
+
+Note that, while the data saved this way is an accurate copy of what is received from the server, it might not match what
+gets parsed into the response's value, as there is some filtering involved, such as stripping of comments junk from
+the end of the message, character set conversion, etc...
+
+Note also that, in the future, this might need some debug mode to be enabled in order to work.
+
+2 - use the `serialize` method on the Response object.
 
 [source, php]
 ----
@@ -1492,7 +1519,7 @@ as "<string/>", `serialize()` will output "<string></string>"), or if the server
 which case the xml generated client side using serialize() will correspond to the error response generated
 internally by the lib).
 
-2 - set the client object to return the raw xml received instead of the decoded objects:
+3 - set the client object to return the raw xml received instead of the decoded objects:
 
 [source, php]
 ----
@@ -1508,10 +1535,6 @@ protocol will be checked. This means that xml-rpc responses sent by the server t
 response on the client (e.g. malformed xml, responses that have faultCode set, etc...) now will not be flagged as
 invalid, and you might end up saving not valid xml but random junk...
 
-3 - use the Response's `httpResponse` method
-
-@TODO...
-
 === Can I use the MS Windows character set?
 
 If the data your application is using comes from a Microsoft application, there are some chances that the character set
diff --git a/src/Client.php b/src/Client.php
index 6ecdfd3b..e1ada81d 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -705,6 +705,7 @@ class Client
         if ($username != '') {
             $credentials = 'Authorization: Basic ' . base64_encode($username . ':' . $password) . "\r\n";
             if ($authType != 1) {
+                /// @todo make this a proper error, ie. return a failure
                 $this->getLogger()->errorLog('XML-RPC: ' . __METHOD__ . ': warning. Only Basic auth is supported with HTTP 1.0');
             }
         }
@@ -725,6 +726,7 @@ class Client
             $uri = 'http://' . $server . ':' . $port . $this->path;
             if ($proxyUsername != '') {
                 if ($proxyAuthType != 1) {
+                    /// @todo make this a proper error, ie. return a failure
                     $this->getLogger()->errorLog('XML-RPC: ' . __METHOD__ . ': warning. Only Basic auth to proxy is supported with HTTP 1.0');
                 }
                 $proxyCredentials = 'Proxy-Authorization: Basic ' . base64_encode($proxyUsername . ':' . $proxyPassword) . "\r\n";
@@ -1093,6 +1095,7 @@ class Client
             if (defined('CURLOPT_HTTPAUTH')) {
                 curl_setopt($curl, CURLOPT_HTTPAUTH, $authType);
             } elseif ($authType != 1) {
+                /// @todo make this a proper error, ie. return a failure
                 $this->getLogger()->errorLog('XML-RPC: ' . __METHOD__ . ': warning. Only Basic auth is supported by the current PHP/curl install');
             }
         }
@@ -1142,6 +1145,7 @@ class Client
                 if (defined('CURLOPT_PROXYAUTH')) {
                     curl_setopt($curl, CURLOPT_PROXYAUTH, $proxyAuthType);
                 } elseif ($proxyAuthType != 1) {
+                    /// @todo make this a proper error, ie. return a failure
                     $this->getLogger()->errorLog('XML-RPC: ' . __METHOD__ . ': warning. Only Basic auth to proxy is supported by the current PHP/curl install');
                 }
             }
diff --git a/src/Helper/Charset.php b/src/Helper/Charset.php
index 07951d9a..c04fe6b5 100644
--- a/src/Helper/Charset.php
+++ b/src/Helper/Charset.php
@@ -272,6 +272,7 @@ class Charset
 
             default:
                 $escapedData = '';
+                /// @todo allow usage of a custom Logger via the DIC(ish) pattern we use in other classes
                 Logger::instance()->errorLog('XML-RPC: ' . __METHOD__ . ": Converting from $srcEncoding to $destEncoding: not supported...");
         }
 
diff --git a/src/Helper/Http.php b/src/Helper/Http.php
index 4b74f39c..e3f4e805 100644
--- a/src/Helper/Http.php
+++ b/src/Helper/Http.php
@@ -5,6 +5,7 @@ namespace PhpXmlRpc\Helper;
 use PhpXmlRpc\Exception\HttpException;
 use PhpXmlRpc\PhpXmlRpc;
 
+/// @todo allow usage of a custom Logger via the DIC(ish) pattern we use in other classes
 class Http
 {
     /**
diff --git a/src/Helper/XMLParser.php b/src/Helper/XMLParser.php
index 6ccfb34f..f1678b43 100644
--- a/src/Helper/XMLParser.php
+++ b/src/Helper/XMLParser.php
@@ -14,6 +14,7 @@ use PhpXmlRpc\Value;
  *       - add parseRequest, parseResponse, parseValue methods
  * @todo if iconv() or mb_string() are available, we could allow to convert the received xml to a custom charset encoding
  *       while parsing, which is faster than doing it later by going over the rebuilt data structure
+ * @todo allow usage of a custom Logger via the DIC(ish) pattern we use in other classes
  */
 class XMLParser
 {
diff --git a/src/Request.php b/src/Request.php
index 39273cf0..00313202 100644
--- a/src/Request.php
+++ b/src/Request.php
@@ -65,6 +65,7 @@ class Request
         return self::$charsetEncoder;
     }
 
+    /// @todo this should be a static method
     public function setCharsetEncoder($charsetEncoder)
     {
         self::$charsetEncoder = $charsetEncoder;
@@ -300,7 +301,7 @@ class Request
             }
         }
 
-        // if user wants back raw xml, give it to her
+        // if the user wants back raw xml, give it to her
         if ($returnType == 'xml') {
             return new Response($data, 0, '', 'xml', $this->httpResponse);
         }
diff --git a/src/Response.php b/src/Response.php
index 8a3c45ed..afde3ba9 100644
--- a/src/Response.php
+++ b/src/Response.php
@@ -38,6 +38,7 @@ class Response
         return self::$charsetEncoder;
     }
 
+    /// @todo this should be a static method
     public function setCharsetEncoder($charsetEncoder)
     {
         self::$charsetEncoder = $charsetEncoder;
diff --git a/src/Server.php b/src/Server.php
index 9c434895..a483b384 100644
--- a/src/Server.php
+++ b/src/Server.php
@@ -133,6 +133,7 @@ class Server
         return self::$charsetEncoder;
     }
 
+    /// @todo this should be a static method
     public function setCharsetEncoder($charsetEncoder)
     {
         self::$charsetEncoder = $charsetEncoder;
diff --git a/src/Value.php b/src/Value.php
index d76e3b6d..d23f766e 100644
--- a/src/Value.php
+++ b/src/Value.php
@@ -72,6 +72,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
         return self::$charsetEncoder;
     }
 
+    /// @todo this should be a static method
     public function setCharsetEncoder($charsetEncoder)
     {
         self::$charsetEncoder = $charsetEncoder;