X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=src%2FValue.php;h=c9fc61406b39afad04a1f223a7c3e0b58df0ab1a;hb=f4978078febfc4289bb4f45db6ca3f9e6c8c4f94;hp=e47e954b9a87b4024244db4fd0e73d930c4a08eb;hpb=e75bfc4ad39a6f30b0b9840f3c63b2f14a1c12c4;p=plcapi.git

diff --git a/src/Value.php b/src/Value.php
index e47e954..c9fc614 100644
--- a/src/Value.php
+++ b/src/Value.php
@@ -4,7 +4,10 @@ namespace PhpXmlRpc;
 
 use PhpXmlRpc\Helper\Charset;
 
-class Value
+/**
+ * This class enables the creation and encapsulation of values for XML-RPC.
+ */
+class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 {
     public static $xmlrpcI4 = "i4";
     public static $xmlrpcInt = "int";
@@ -31,21 +34,27 @@ class Value
         "null" => 1,
     );
 
-    /// @todo: does these need to be public?
+    /// @todo: do these need to be public?
     public $me = array();
     public $mytype = 0;
     public $_php_class = null;
 
     /**
-     * @param mixed $val
-     * @param string $type any valid xmlrpc type name (lowercase). If null, 'string' is assumed
+     * Build an xmlrpc value.
+     *
+     * When no value or type is passed in, the value is left uninitialized, and the value can be added later.
+     *
+     * @param mixed $val if passing in an array, all array elements should be PhpXmlRpc\Value themselves
+     * @param string $type any valid xmlrpc type name (lowercase): i4, int, boolean, string, double, dateTime.iso8601,
+     *                     base64, array, struct, null.
+     *                     If null, 'string' is assumed.
+     *                     You should refer to http://www.xmlrpc.com/spec for more information on what each of these mean.
      */
     public function __construct($val = -1, $type = '')
     {
-        /// @todo: optimization creep - do not call addXX, do it all inline.
-        /// downside: booleans will not be coerced anymore
+        // optimization creep - do not call addXX, do it all inline.
+        // downside: booleans will not be coerced anymore
         if ($val !== -1 || $type != '') {
-            // optimization creep: inlined all work done by constructor
             switch ($type) {
                 case '':
                     $this->mytype = 1;
@@ -73,43 +82,30 @@ class Value
                 default:
                     error_log("XML-RPC: " . __METHOD__ . ": not a known type ($type)");
             }
-            /*if($type=='')
-            {
-                $type='string';
-            }
-            if(static::$xmlrpcTypes[$type]==1)
-            {
-                $this->addScalar($val,$type);
-            }
-            elseif(static::$xmlrpcTypes[$type]==2)
-            {
-                $this->addArray($val);
-            }
-            elseif(static::$xmlrpcTypes[$type]==3)
-            {
-                $this->addStruct($val);
-            }*/
         }
     }
 
     /**
-     * Add a single php value to an (unitialized) xmlrpcval.
+     * Add a single php value to an xmlrpc value.
+     *
+     * If the xmlrpc value is an array, the php value is added as its last element.
+     * If the xmlrpc value is empty (uninitialized), this method makes it a scalar value, and sets that value.
+     * Fails if the xmlrpc value is not an array and already initialized.
      *
      * @param mixed $val
-     * @param string $type
+     * @param string $type allowed values: i4, int, boolean, string, double, dateTime.iso8601, base64, null.
      *
      * @return int 1 or 0 on failure
      */
     public function addScalar($val, $type = 'string')
     {
-        $typeof = null;
+        $typeOf = null;
         if (isset(static::$xmlrpcTypes[$type])) {
-            $typeof = static::$xmlrpcTypes[$type];
+            $typeOf = static::$xmlrpcTypes[$type];
         }
 
-        if ($typeof != 1) {
+        if ($typeOf !== 1) {
             error_log("XML-RPC: " . __METHOD__ . ": not a scalar type ($type)");
-
             return 0;
         }
 
@@ -127,88 +123,88 @@ class Value
         switch ($this->mytype) {
             case 1:
                 error_log('XML-RPC: ' . __METHOD__ . ': scalar xmlrpc value can have only one value');
-
                 return 0;
             case 3:
                 error_log('XML-RPC: ' . __METHOD__ . ': cannot add anonymous scalar to struct xmlrpc value');
-
                 return 0;
             case 2:
                 // we're adding a scalar value to an array here
-                //$ar=$this->me['array'];
-                //$ar[]=new Value($val, $type);
-                //$this->me['array']=$ar;
-                // Faster (?) avoid all the costly array-copy-by-val done here...
                 $this->me['array'][] = new Value($val, $type);
 
                 return 1;
             default:
                 // a scalar, so set the value and remember we're scalar
                 $this->me[$type] = $val;
-                $this->mytype = $typeof;
+                $this->mytype = $typeOf;
 
                 return 1;
         }
     }
 
     /**
-     * Add an array of xmlrpcval objects to an xmlrpcval.
+     * Add an array of xmlrpc value objects to an xmlrpc value.
+     *
+     * If the xmlrpc value is an array, the elements are appended to the existing ones.
+     * If the xmlrpc value is empty (uninitialized), this method makes it an array value, and sets that value.
+     * Fails otherwise.
      *
-     * @param Value[] $vals
+     * @param Value[] $values
      *
      * @return int 1 or 0 on failure
      *
-     * @todo add some checking for $vals to be an array of xmlrpcvals?
+     * @todo add some checking for $values to be an array of xmlrpc values?
      */
-    public function addArray($vals)
+    public function addArray($values)
     {
         if ($this->mytype == 0) {
             $this->mytype = static::$xmlrpcTypes['array'];
-            $this->me['array'] = $vals;
+            $this->me['array'] = $values;
 
             return 1;
         } elseif ($this->mytype == 2) {
             // we're adding to an array here
-            $this->me['array'] = array_merge($this->me['array'], $vals);
+            $this->me['array'] = array_merge($this->me['array'], $values);
 
             return 1;
         } else {
             error_log('XML-RPC: ' . __METHOD__ . ': already initialized as a [' . $this->kindOf() . ']');
-
             return 0;
         }
     }
 
     /**
-     * Add an array of named xmlrpcval objects to an xmlrpcval.
+     * Merges an array of named xmlrpc value objects into an xmlrpc value.
+     *
+     * If the xmlrpc value is a struct, the elements are merged with the existing ones (overwriting existing ones).
+     * If the xmlrpc value is empty (uninitialized), this method makes it a struct value, and sets that value.
+     * Fails otherwise.
      *
-     * @param Value[] $vals
+     * @param Value[] $values
      *
      * @return int 1 or 0 on failure
      *
-     * @todo add some checking for $vals to be an array?
+     * @todo add some checking for $values to be an array?
      */
-    public function addStruct($vals)
+    public function addStruct($values)
     {
         if ($this->mytype == 0) {
             $this->mytype = static::$xmlrpcTypes['struct'];
-            $this->me['struct'] = $vals;
+            $this->me['struct'] = $values;
 
             return 1;
         } elseif ($this->mytype == 3) {
             // we're adding to a struct here
-            $this->me['struct'] = array_merge($this->me['struct'], $vals);
+            $this->me['struct'] = array_merge($this->me['struct'], $values);
 
             return 1;
         } else {
             error_log('XML-RPC: ' . __METHOD__ . ': already initialized as a [' . $this->kindOf() . ']');
-
             return 0;
         }
     }
 
     /**
-     * Returns a string containing "struct", "array" or "scalar" describing the base type of the value.
+     * Returns a string containing either "struct", "array", "scalar" or "undef", describing the base type of the value.
      *
      * @return string
      */
@@ -229,7 +225,7 @@ class Value
         }
     }
 
-    private function serializedata($typ, $val, $charset_encoding = '')
+    protected function serializedata($typ, $val, $charsetEncoding = '')
     {
         $rs = '';
 
@@ -249,7 +245,7 @@ class Value
                     case static::$xmlrpcString:
                         // G. Giunta 2005/2/13: do NOT use htmlentities, since
                         // it will produce named html entities, which are invalid xml
-                        $rs .= "<${typ}>" . Charset::instance()->encode_entities($val, PhpXmlRpc::$xmlrpc_internalencoding, $charset_encoding) . "</${typ}>";
+                        $rs .= "<${typ}>" . Charset::instance()->encodeEntities($val, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</${typ}>";
                         break;
                     case static::$xmlrpcInt:
                     case static::$xmlrpcI4:
@@ -284,7 +280,7 @@ class Value
                         break;
                     default:
                         // no standard type value should arrive here, but provide a possibility
-                        // for xmlrpcvals of unknown type...
+                        // for xmlrpc values of unknown type...
                         $rs .= "<${typ}>${val}</${typ}>";
                 }
                 break;
@@ -297,9 +293,9 @@ class Value
                 }
                 $charsetEncoder = Charset::instance();
                 foreach ($val as $key2 => $val2) {
-                    $rs .= '<member><name>' . $charsetEncoder->encode_entities($key2, PhpXmlRpc::$xmlrpc_internalencoding, $charset_encoding) . "</name>\n";
+                    $rs .= '<member><name>' . $charsetEncoder->encodeEntities($key2, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</name>\n";
                     //$rs.=$this->serializeval($val2);
-                    $rs .= $val2->serialize($charset_encoding);
+                    $rs .= $val2->serialize($charsetEncoding);
                     $rs .= "</member>\n";
                 }
                 $rs .= '</struct>';
@@ -309,7 +305,7 @@ class Value
                 $rs .= "<array>\n<data>\n";
                 foreach ($val as $element) {
                     //$rs.=$this->serializeval($val[$i]);
-                    $rs .= $element->serialize($charset_encoding);
+                    $rs .= $element->serialize($charsetEncoding);
                 }
                 $rs .= "</data>\n</array>";
                 break;
@@ -321,66 +317,58 @@ class Value
     }
 
     /**
-     * Returns xml representation of the value. XML prologue not included.
+     * Returns the xml representation of the value. XML prologue not included.
      *
-     * @param string $charset_encoding the charset to be used for serialization. if null, US-ASCII is assumed
+     * @param string $charsetEncoding the charset to be used for serialization. if null, US-ASCII is assumed
      *
      * @return string
      */
-    public function serialize($charset_encoding = '')
+    public function serialize($charsetEncoding = '')
     {
-        // add check? slower, but helps to avoid recursion in serializing broken xmlrpcvals...
+        // add check? slower, but helps to avoid recursion in serializing broken xmlrpc values...
         //if (is_object($o) && (get_class($o) == 'xmlrpcval' || is_subclass_of($o, 'xmlrpcval')))
         //{
         reset($this->me);
         list($typ, $val) = each($this->me);
 
-        return '<value>' . $this->serializedata($typ, $val, $charset_encoding) . "</value>\n";
-        //}
-    }
-
-    // DEPRECATED
-    public function serializeval($o)
-    {
-        // add check? slower, but helps to avoid recursion in serializing broken xmlrpcvals...
-        //if (is_object($o) && (get_class($o) == 'xmlrpcval' || is_subclass_of($o, 'xmlrpcval')))
-        //{
-        $ar = $o->me;
-        reset($ar);
-        list($typ, $val) = each($ar);
-
-        return '<value>' . $this->serializedata($typ, $val) . "</value>\n";
+        return '<value>' . $this->serializedata($typ, $val, $charsetEncoding) . "</value>\n";
         //}
     }
 
     /**
      * Checks whether a struct member with a given name is present.
-     * Works only on xmlrpcvals of type struct.
      *
-     * @param string $m the name of the struct member to be looked up
+     * Works only on xmlrpc values of type struct.
+     *
+     * @param string $key the name of the struct member to be looked up
      *
      * @return boolean
+     *
+     * @deprecated use array access, e.g. isset($val[$key])
      */
-    public function structmemexists($m)
+    public function structmemexists($key)
     {
-        return array_key_exists($m, $this->me['struct']);
+        return array_key_exists($key, $this->me['struct']);
     }
 
     /**
-     * Returns the value of a given struct member (an xmlrpcval object in itself).
+     * Returns the value of a given struct member (an xmlrpc value object in itself).
      * Will raise a php warning if struct member of given name does not exist.
      *
-     * @param string $m the name of the struct member to be looked up
+     * @param string $key the name of the struct member to be looked up
      *
      * @return Value
+     *
+     * @deprecated use array access, e.g. $val[$key]
      */
-    public function structmem($m)
+    public function structmem($key)
     {
-        return $this->me['struct'][$m];
+        return $this->me['struct'][$key];
     }
 
     /**
-     * Reset internal pointer for xmlrpcvals of type struct.
+     * Reset internal pointer for xmlrpc values of type struct.
+     * @deprecated iterate directly over the object using foreach instead
      */
     public function structreset()
     {
@@ -388,52 +376,19 @@ class Value
     }
 
     /**
-     * Return next member element for xmlrpcvals of type struct.
+     * Return next member element for xmlrpc values of type struct.
      *
-     * @return xmlrpcval
+     * @return Value
+     *
+     * @deprecated iterate directly over the object using foreach instead
      */
     public function structeach()
     {
         return each($this->me['struct']);
     }
 
-    // DEPRECATED! this code looks like it is very fragile and has not been fixed
-    // for a long long time. Shall we remove it for 2.0?
-    public function getval()
-    {
-        // UNSTABLE
-        reset($this->me);
-        list($a, $b) = each($this->me);
-        // contributed by I Sofer, 2001-03-24
-        // add support for nested arrays to scalarval
-        // i've created a new method here, so as to
-        // preserve back compatibility
-
-        if (is_array($b)) {
-            @reset($b);
-            while (list($id, $cont) = @each($b)) {
-                $b[$id] = $cont->scalarval();
-            }
-        }
-
-        // add support for structures directly encoding php objects
-        if (is_object($b)) {
-            $t = get_object_vars($b);
-            @reset($t);
-            while (list($id, $cont) = @each($t)) {
-                $t[$id] = $cont->scalarval();
-            }
-            @reset($t);
-            while (list($id, $cont) = @each($t)) {
-                @$b->$id = $cont;
-            }
-        }
-        // end contrib
-        return $b;
-    }
-
     /**
-     * Returns the value of a scalar xmlrpcval.
+     * Returns the value of a scalar xmlrpc value (base 64 decoding is automatically handled here)
      *
      * @return mixed
      */
@@ -446,7 +401,8 @@ class Value
     }
 
     /**
-     * Returns the type of the xmlrpcval.
+     * Returns the type of the xmlrpc value.
+     *
      * For integers, 'int' is always returned in place of 'i4'.
      *
      * @return string
@@ -463,21 +419,25 @@ class Value
     }
 
     /**
-     * Returns the m-th member of an xmlrpcval of struct type.
+     * Returns the m-th member of an xmlrpc value of array type.
      *
-     * @param integer $m the index of the value to be retrieved (zero based)
+     * @param integer $key the index of the value to be retrieved (zero based)
      *
      * @return Value
+     *
+     * @deprecated use array access, e.g. $val[$key]
      */
-    public function arraymem($m)
+    public function arraymem($key)
     {
-        return $this->me['array'][$m];
+        return $this->me['array'][$key];
     }
 
     /**
-     * Returns the number of members in an xmlrpcval of array type.
+     * Returns the number of members in an xmlrpc value of array type.
      *
      * @return integer
+     *
+     * @deprecated use count() instead
      */
     public function arraysize()
     {
@@ -485,12 +445,143 @@ class Value
     }
 
     /**
-     * Returns the number of members in an xmlrpcval of struct type.
+     * Returns the number of members in an xmlrpc value of struct type.
      *
      * @return integer
+     *
+     * @deprecated use count() instead
      */
     public function structsize()
     {
         return count($this->me['struct']);
     }
-}
+
+    /**
+     * Returns the number of members in an xmlrpc value:
+     * - 0 for uninitialized values
+     * - 1 for scalar values
+     * - the number of elements for struct and array values
+     *
+     * @return integer
+     */
+    public function count()
+    {
+        switch ($this->mytype) {
+            case 3:
+                return count($this->me['struct']);
+            case 2:
+                return count($this->me['array']);
+            case 1:
+                return 1;
+            default:
+                return 0;
+        }
+    }
+
+    /**
+     * Implements the IteratorAggregate interface
+     *
+     * @return ArrayIterator
+     */
+    public function getIterator() {
+        switch ($this->mytype) {
+            case 3:
+                return new \ArrayIterator($this->me['struct']);
+            case 2:
+                return new \ArrayIterator($this->me['array']);
+            case 1:
+                return new \ArrayIterator($this->me);
+            default:
+                return new \ArrayIterator();
+        }
+        return new \ArrayIterator();
+    }
+
+
+    public function offsetSet($offset, $value) {
+
+        switch ($this->mytype) {
+            case 3:
+                if (!($value instanceof \PhpXmlRpc\Value)) {
+                    throw new \Exception('It is only possible to add Value objects to an XML-RPC Struct');
+                }
+                if (is_null($offset)) {
+                    // disallow struct members with empty names
+                    throw new \Exception('It is not possible to add anonymous members to an XML-RPC Struct');
+                } else {
+                    $this->me['struct'][$offset] = $value;
+                }
+                return;
+            case 2:
+                if (!($value instanceof \PhpXmlRpc\Value)) {
+                    throw new \Exception('It is only possible to add Value objects to an XML-RPC Array');
+                }
+                if (is_null($offset)) {
+                    $this->me['array'][] = $value;
+                } else {
+                    // nb: we are not checking that $offset is above the existing array range...
+                    $this->me['array'][$offset] = $value;
+                }
+                return;
+            case 1:
+// todo: handle i4 vs int
+                reset($this->me);
+                list($type,) = each($this->me);
+                if ($type != $offset) {
+                    throw new \Exception('');
+                }
+                $this->me[$type] = $value;
+                return;
+            default:
+                // it would be nice to allow empty values to be be turned into non-empty ones this way, but we miss info to do so
+                throw new \Exception("XML-RPC Value is of type 'undef' and its value can not be set using array index");
+        }
+    }
+
+    public function offsetExists($offset) {
+        switch ($this->mytype) {
+            case 3:
+                return isset($this->me['struct'][$offset]);
+            case 2:
+                return isset($this->me['array'][$offset]);
+            case 1:
+// todo: handle i4 vs int
+                return $offset == $this->scalartyp();
+            default:
+                return false;
+        }
+    }
+
+    public function offsetUnset($offset) {
+        switch ($this->mytype) {
+            case 3:
+                unset($this->me['struct'][$offset]);
+                return;
+            case 2:
+                unset($this->me['array'][$offset]);
+                return;
+            case 1:
+                // can not remove value from a scalar
+                throw new \Exception("XML-RPC Value is of type 'scalar' and its value can not be unset using array index");
+            default:
+                throw new \Exception("XML-RPC Value is of type 'undef' and its value can not be unset using array index");
+        }
+    }
+
+    public function offsetGet($offset) {
+        switch ($this->mytype) {
+            case 3:
+                return isset($this->me['struct'][$offset]) ? $this->me['struct'][$offset] : null;
+            case 2:
+                return isset($this->me['array'][$offset]) ? $this->me['array'][$offset] : null;
+            case 1:
+// on bad type: null or exception?
+                reset($this->me);
+                list($type, $value) = each($this->me);
+                return $type == $offset ? $value : null;
+            default:
+// return null or exception?
+                throw new \Exception("XML-RPC Value is of type 'undef' and can not be accessed using array index");
+        }
+    }
+}
\ No newline at end of file