X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=src%2FValue.php;h=c9fc61406b39afad04a1f223a7c3e0b58df0ab1a;hb=f4978078febfc4289bb4f45db6ca3f9e6c8c4f94;hp=6e8d7efa6f12d46f62b166659a9012b30f439186;hpb=751f9c979bd0d3ca2198ad31009d4cb4cff691cc;p=plcapi.git diff --git a/src/Value.php b/src/Value.php index 6e8d7ef..c9fc614 100644 --- a/src/Value.php +++ b/src/Value.php @@ -4,7 +4,10 @@ namespace PhpXmlRpc; use PhpXmlRpc\Helper\Charset; -class Value implements \Countable, \IteratorAggregate +/** + * 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"; @@ -38,10 +41,14 @@ class Value implements \Countable, \IteratorAggregate /** * 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 = '') { @@ -79,10 +86,14 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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, int, boolean, string, double, dateTime.iso8601, base64, null. * * @return int 1 or 0 on failure */ @@ -131,7 +142,11 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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 +173,11 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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 +204,7 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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 */ @@ -298,7 +317,7 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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,11 +337,14 @@ class Value implements \Countable, \IteratorAggregate /** * 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 * * @return boolean + * + * @deprecated use array access, e.g. isset($val[$key]) */ public function structmemexists($key) { @@ -336,6 +358,8 @@ class Value implements \Countable, \IteratorAggregate * @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($key) { @@ -344,6 +368,7 @@ class Value implements \Countable, \IteratorAggregate /** * Reset internal pointer for xmlrpc values of type struct. + * @deprecated iterate directly over the object using foreach instead */ public function structreset() { @@ -354,6 +379,8 @@ class Value implements \Countable, \IteratorAggregate * Return next member element for xmlrpc values of type struct. * * @return Value + * + * @deprecated iterate directly over the object using foreach instead */ public function structeach() { @@ -361,7 +388,7 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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 */ @@ -375,6 +402,7 @@ class Value implements \Countable, \IteratorAggregate /** * Returns the type of the xmlrpc value. + * * For integers, 'int' is always returned in place of 'i4'. * * @return string @@ -391,11 +419,13 @@ class Value implements \Countable, \IteratorAggregate } /** - * 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) * * @return Value + * + * @deprecated use array access, e.g. $val[$key] */ public function arraymem($key) { @@ -419,7 +449,7 @@ class Value implements \Countable, \IteratorAggregate * * @return integer * - * @deprecateduse count() instead + * @deprecated use count() instead */ public function structsize() { @@ -429,8 +459,8 @@ class Value implements \Countable, \IteratorAggregate /** * 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 */ @@ -438,7 +468,7 @@ class Value implements \Countable, \IteratorAggregate { switch ($this->mytype) { case 3: - count($this->me['struct']); + return count($this->me['struct']); case 2: return count($this->me['array']); case 1: @@ -454,6 +484,104 @@ class Value implements \Countable, \IteratorAggregate * @return ArrayIterator */ public function getIterator() { - return new \ArrayIterator($this->me); + 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