X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=src%2FValue.php;h=d48f0b8ff440fc61a8cf81cd15d23aa83019915a;hb=1c13905fd4fc8b5177aab001489e6f6bf557389a;hp=f0d331af244c4aa1c43a2a933e7a02b6343aeb58;hpb=bd4048215800186db5224ea04e0d45cab97c12b9;p=plcapi.git

diff --git a/src/Value.php b/src/Value.php
index f0d331a..d48f0b8 100644
--- a/src/Value.php
+++ b/src/Value.php
@@ -4,9 +4,13 @@ namespace PhpXmlRpc;
 
 use PhpXmlRpc\Helper\Charset;
 
+/**
+ * This class enables the creation of values for XML-RPC, by encapsulating plain php values.
+ */
 class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 {
     public static $xmlrpcI4 = "i4";
+    public static $xmlrpcI8 = "i8";
     public static $xmlrpcInt = "int";
     public static $xmlrpcBoolean = "boolean";
     public static $xmlrpcDouble = "double";
@@ -20,6 +24,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     public static $xmlrpcTypes = array(
         "i4" => 1,
+        "i8" => 1,
         "int" => 1,
         "boolean" => 1,
         "double" => 1,
@@ -38,10 +43,14 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * 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
-     * @param string $type any valid xmlrpc type name (lowercase). If null, 'string' is assumed
+     * 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 = '')
     {
@@ -54,6 +63,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
                     $this->me['string'] = $val;
                     break;
                 case 'i4':
+                case 'i8':
                 case 'int':
                 case 'double':
                 case 'string':
@@ -79,10 +89,14 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Add a single php value to an (uninitialized) xmlrpc value.
+     * 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, i8, int, boolean, string, double, dateTime.iso8601, base64, null.
      *
      * @return int 1 or 0 on failure
      */
@@ -131,7 +145,11 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Add an array of xmlrpc values objects to an xmlrpc value.
+     * 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[] $values
      *
@@ -158,7 +176,11 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Add an array of named xmlrpc value objects to an xmlrpc value.
+     * 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[] $values
      *
@@ -185,7 +207,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns a string containing "struct", "array", "scalar" or "undef" 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
      */
@@ -230,6 +252,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
                         break;
                     case static::$xmlrpcInt:
                     case static::$xmlrpcI4:
+                    case static::$xmlrpcI8:
                         $rs .= "<${typ}>" . (int)$val . "</${typ}>";
                         break;
                     case static::$xmlrpcDouble:
@@ -298,7 +321,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns xml representation of the value. XML prologue not included.
+     * Returns the xml representation of the value. XML prologue not included.
      *
      * @param string $charsetEncoding the charset to be used for serialization. if null, US-ASCII is assumed
      *
@@ -318,6 +341,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * Checks whether a struct member with a given name is present.
+     *
      * Works only on xmlrpc values of type struct.
      *
      * @param string $key the name of the struct member to be looked up
@@ -368,7 +392,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns the value of a scalar xmlrpc value.
+     * Returns the value of a scalar xmlrpc value (base 64 decoding is automatically handled here)
      *
      * @return mixed
      */
@@ -382,7 +406,8 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * Returns the type of the xmlrpc value.
-     * For integers, 'int' is always returned in place of 'i4'.
+     *
+     * For integers, 'int' is always returned in place of 'i4' or 'i8'.
      *
      * @return string
      */
@@ -390,7 +415,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     {
         reset($this->me);
         list($a,) = each($this->me);
-        if ($a == static::$xmlrpcI4) {
+        if ($a == static::$xmlrpcI4 || $a == static::$xmlrpcI8) {
             $a = static::$xmlrpcInt;
         }
 
@@ -398,7 +423,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns the m-th member of an xmlrpc value of struct type.
+     * Returns the m-th member of an xmlrpc value of array type.
      *
      * @param integer $key the index of the value to be retrieved (zero based)
      *
@@ -438,8 +463,8 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     /**
      * Returns the number of members in an xmlrpc value:
      * - 0 for uninitialized values
-     * - 1 for scalars
-     * - the number of elements for structs and arrays
+     * - 1 for scalar values
+     * - the number of elements for struct and array values
      *
      * @return integer
      */
@@ -503,7 +528,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
                 }
                 return;
             case 1:
-// todo: handle i4 vs int
+// todo: handle i4/i8 vs int
                 reset($this->me);
                 list($type,) = each($this->me);
                 if ($type != $offset) {
@@ -524,7 +549,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
             case 2:
                 return isset($this->me['array'][$offset]);
             case 1:
-// todo: handle i4 vs int
+// todo: handle i4/i8 vs int
                 return $offset == $this->scalartyp();
             default:
                 return false;
@@ -563,4 +588,4 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
                 throw new \Exception("XML-RPC Value is of type 'undef' and can not be accessed using array index");
         }
     }
-}
\ No newline at end of file
+}