X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=src%2FResponse.php;h=16ff0a8169381130641d4b145fbe8c0c729a1b65;hb=f4978078febfc4289bb4f45db6ca3f9e6c8c4f94;hp=5f0f6ec75f411bfca85c92c84e94ac877c46d1e3;hpb=64b37dfbd32a7858e729e03eb276a2eaa0f19ccd;p=plcapi.git

diff --git a/src/Response.php b/src/Response.php
index 5f0f6ec..16ff0a8 100644
--- a/src/Response.php
+++ b/src/Response.php
@@ -4,9 +4,13 @@ namespace PhpXmlRpc;
 
 use PhpXmlRpc\Helper\Charset;
 
+/**
+ * This class is used to contain responses to XML-RPC requests.
+ * Server-side, a server method handler will construct a Response and pass it as its return value.
+ * An identical Response object will be returned by the result of an invocation of the send() method of the Client class.
+ */
 class Response
 {
-
     /// @todo: do these need to be public?
     public $val = 0;
     public $valtyp;
@@ -19,54 +23,44 @@ class Response
     public $raw_data = '';
 
     /**
-     * @param mixed $val either an xmlrpcval obj, a php value or the xml serialization of an xmlrpcval (a string)
-     * @param integer $fcode set it to anything but 0 to create an error response
-     * @param string $fstr the error string, in case of an error response
-     * @param string $valtyp either 'xmlrpcvals', 'phpvals' or 'xml'
+     * @param mixed $val either a Value object, a php value or the xml serialization of an xmlrpc value (a string)
+     * @param integer $fCode set it to anything but 0 to create an error response. In that case, $val is discarded
+     * @param string $fString the error string, in case of an error response
+     * @param string $valType The type of $val passed in. Either 'xmlrpcvals', 'phpvals' or 'xml'. Leave empty to let
+     *                        the code guess the correct type.
      *
-     * @todo add check that $val / $fcode / $fstr is of correct type???
-     * NB: as of now we do not do it, since it might be either an xmlrpcval or a plain
-     * php val, or a complete xml chunk, depending on usage of xmlrpc_client::send() inside which creator is called...
+     * @todo add check that $val / $fCode / $fString is of correct type???
+     *       NB: as of now we do not do it, since it might be either an xmlrpc value or a plain php val, or a complete
+     *       xml chunk, depending on usage of Client::send() inside which creator is called...
      */
-    function __construct($val, $fcode = 0, $fstr = '', $valtyp='')
+    public function __construct($val, $fCode = 0, $fString = '', $valType = '')
     {
-        if($fcode != 0)
-        {
+        if ($fCode != 0) {
             // error response
-            $this->errno = $fcode;
-            $this->errstr = $fstr;
-            //$this->errstr = htmlspecialchars($fstr); // XXX: encoding probably shouldn't be done here; fix later.
-        }
-        else
-        {
+            $this->errno = $fCode;
+            $this->errstr = $fString;
+        } else {
             // successful response
             $this->val = $val;
-            if ($valtyp == '')
-            {
+            if ($valType == '') {
                 // user did not declare type of response value: try to guess it
-                if (is_object($this->val) && is_a($this->val, 'PhpXmlRpc\Value'))
-                {
+                if (is_object($this->val) && is_a($this->val, 'PhpXmlRpc\Value')) {
                     $this->valtyp = 'xmlrpcvals';
-                }
-                else if (is_string($this->val))
-                {
+                } elseif (is_string($this->val)) {
                     $this->valtyp = 'xml';
-                }
-                else
-                {
+                } else {
                     $this->valtyp = 'phpvals';
                 }
-            }
-            else
-            {
+            } else {
                 // user declares type of resp value: believe him
-                $this->valtyp = $valtyp;
+                $this->valtyp = $valType;
             }
         }
     }
 
     /**
      * Returns the error code of the response.
+     *
      * @return integer the error code of this response (0 for not-error responses)
      */
     public function faultCode()
@@ -76,6 +70,7 @@ class Response
 
     /**
      * Returns the error code of the response.
+     *
      * @return string the error string of this response ('' for not-error responses)
      */
     public function faultString()
@@ -84,8 +79,11 @@ class Response
     }
 
     /**
-     * Returns the value received by the server.
-     * @return mixed the xmlrpcval object returned by the server. Might be an xml string or php value if the response has been created by specially configured xmlrpc_client objects
+     * Returns the value received by the server. If the Response's faultCode is non-zero then the value returned by this
+     * method should not be used (it may not even be an object).
+     *
+     * @return Value|string|mixed the Value object returned by the server. Might be an xml string or plain php value
+     *                            depending on the convention adopted when creating the Response
      */
     public function value()
     {
@@ -94,12 +92,12 @@ class Response
 
     /**
      * Returns an array with the cookies received from the server.
-     * Array has the form: $cookiename => array ('value' => $val, $attr1 => $val1, $attr2 = $val2, ...)
+     * Array has the form: $cookiename => array ('value' => $val, $attr1 => $val1, $attr2 => $val2, ...)
      * with attributes being e.g. 'expires', 'path', domain'.
-     * NB: cookies sent as 'expired' by the server (i.e. with an expiry date in the past)
-     * are still present in the array. It is up to the user-defined code to decide
-     * how to use the received cookies, and whether they have to be sent back with the next
-     * request to the server (using xmlrpc_client::setCookie) or not
+     * NB: cookies sent as 'expired' by the server (i.e. with an expiry date in the past) are still present in the array.
+     * It is up to the user-defined code to decide how to use the received cookies, and whether they have to be sent back
+     * with the next request to the server (using Client::setCookie) or not.
+     *
      * @return array array of cookies received from the server
      */
     public function cookies()
@@ -108,60 +106,53 @@ class Response
     }
 
     /**
-     * Returns xml representation of the response. XML prologue not included
-     * @param string $charset_encoding the charset to be used for serialization. if null, US-ASCII is assumed
+     * Returns xml representation of the response. XML prologue not included.
+     *
+     * @param string $charsetEncoding the charset to be used for serialization. If null, US-ASCII is assumed
+     *
      * @return string the xml representation of the response
+     *
+     * @throws \Exception
      */
-    public function serialize($charset_encoding='')
+    public function serialize($charsetEncoding = '')
     {
-        if ($charset_encoding != '')
-            $this->content_type = 'text/xml; charset=' . $charset_encoding;
-        else
+        if ($charsetEncoding != '') {
+            $this->content_type = 'text/xml; charset=' . $charsetEncoding;
+        } else {
             $this->content_type = 'text/xml';
-        if (PhpXmlRpc::$xmlrpc_null_apache_encoding)
-        {
-            $result = "<methodResponse xmlns:ex=\"".PhpXmlRpc::$xmlrpc_null_apache_encoding_ns."\">\n";
         }
-        else
-        {
+        if (PhpXmlRpc::$xmlrpc_null_apache_encoding) {
+            $result = "<methodResponse xmlns:ex=\"" . PhpXmlRpc::$xmlrpc_null_apache_encoding_ns . "\">\n";
+        } else {
             $result = "<methodResponse>\n";
         }
-        if($this->errno)
-        {
+        if ($this->errno) {
             // G. Giunta 2005/2/13: let non-ASCII response messages be tolerated by clients
             // by xml-encoding non ascii chars
-            $charsetEncoder =
             $result .= "<fault>\n" .
-"<value>\n<struct><member><name>faultCode</name>\n<value><int>" . $this->errno .
-"</int></value>\n</member>\n<member>\n<name>faultString</name>\n<value><string>" .
-Charset::instance()->encode_entitites($this->errstr, PhpXmlRpc::$xmlrpc_internalencoding, $charset_encoding) . "</string></value>\n</member>\n" .
-"</struct>\n</value>\n</fault>";
-        }
-        else
-        {
-            if(!is_object($this->val) || !is_a($this->val, 'xmlrpcval'))
-            {
-                if (is_string($this->val) && $this->valtyp == 'xml')
-                {
+                "<value>\n<struct><member><name>faultCode</name>\n<value><int>" . $this->errno .
+                "</int></value>\n</member>\n<member>\n<name>faultString</name>\n<value><string>" .
+                Charset::instance()->encodeEntities($this->errstr, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</string></value>\n</member>\n" .
+                "</struct>\n</value>\n</fault>";
+        } else {
+            if (!is_object($this->val) || !is_a($this->val, 'PhpXmlRpc\Value')) {
+                if (is_string($this->val) && $this->valtyp == 'xml') {
                     $result .= "<params>\n<param>\n" .
                         $this->val .
                         "</param>\n</params>";
-                }
-                else
-                {
+                } else {
                     /// @todo try to build something serializable?
-                    die('cannot serialize xmlrpcresp objects whose content is native php values');
+                    throw new \Exception('cannot serialize xmlrpc response objects whose content is native php values');
                 }
-            }
-            else
-            {
+            } else {
                 $result .= "<params>\n<param>\n" .
-                    $this->val->serialize($charset_encoding) .
+                    $this->val->serialize($charsetEncoding) .
                     "</param>\n</params>";
             }
         }
         $result .= "\n</methodResponse>";
         $this->payload = $result;
+
         return $result;
     }
 }