X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=src%2FValue.php;h=97852b05ea1c56d4488fd369b24f999c9e6af8ac;hb=b5d242c678774aa0952497d77379f61efad733ec;hp=76d3a029e44a2288767376e2daa85ecdd449e42b;hpb=35d2340eea9a168983b8f20d54c399422790f816;p=plcapi.git diff --git a/src/Value.php b/src/Value.php index 76d3a02..97852b0 100644 --- a/src/Value.php +++ b/src/Value.php @@ -4,9 +4,13 @@ namespace PhpXmlRpc; use PhpXmlRpc\Helper\Charset; -class Value +/** + * 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 public static $xmlrpcTypes = array( "i4" => 1, + "i8" => 1, "int" => 1, "boolean" => 1, "double" => 1, @@ -31,27 +36,34 @@ 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; $this->me['string'] = $val; break; case 'i4': + case 'i8': case 'int': case 'double': case 'string': @@ -73,48 +85,35 @@ 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, i8, 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; } // coerce booleans into correct values - // NB: we should either do it for datetimes, integers and doubles, too, + // NB: we should either do it for datetimes, integers, i8 and doubles, too, // or just plain remove this check, implemented on booleans only... if ($type == static::$xmlrpcBoolean) { if (strcasecmp($val, 'true') == 0 || $val == 1 || ($val == true && strcasecmp($val, 'false'))) { @@ -127,88 +126,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. * - * @param array $vals + * 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 * * @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 array $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 +228,7 @@ class Value } } - private function serializedata($typ, $val, $charset_encoding = '') + protected function serializedata($typ, $val, $charsetEncoding = '') { $rs = ''; @@ -249,10 +248,11 @@ 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) . ""; + $rs .= "<${typ}>" . Charset::instance()->encodeEntities($val, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . ""; break; case static::$xmlrpcInt: case static::$xmlrpcI4: + case static::$xmlrpcI8: $rs .= "<${typ}>" . (int)$val . ""; break; case static::$xmlrpcDouble: @@ -284,7 +284,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}"; } break; @@ -297,9 +297,9 @@ class Value } $charsetEncoder = Charset::instance(); foreach ($val as $key2 => $val2) { - $rs .= '' . $charsetEncoder->encode_entities($key2, PhpXmlRpc::$xmlrpc_internalencoding, $charset_encoding) . "\n"; + $rs .= '' . $charsetEncoder->encodeEntities($key2, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "\n"; //$rs.=$this->serializeval($val2); - $rs .= $val2->serialize($charset_encoding); + $rs .= $val2->serialize($charsetEncoding); $rs .= "\n"; } $rs .= ''; @@ -309,7 +309,7 @@ class Value $rs .= "\n\n"; foreach ($val as $element) { //$rs.=$this->serializeval($val[$i]); - $rs .= $element->serialize($charset_encoding); + $rs .= $element->serialize($charsetEncoding); } $rs .= "\n"; break; @@ -321,66 +321,54 @@ 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... - //if (is_object($o) && (get_class($o) == 'xmlrpcval' || is_subclass_of($o, 'xmlrpcval'))) - //{ reset($this->me); list($typ, $val) = each($this->me); - return '' . $this->serializedata($typ, $val, $charset_encoding) . "\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 '' . $this->serializedata($typ, $val) . "\n"; - //} + return '' . $this->serializedata($typ, $val, $charsetEncoding) . "\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 * - * @return xmlrpcval + * @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,8 +401,9 @@ class Value } /** - * Returns the type of the xmlrpcval. - * For integers, 'int' is always returned in place of 'i4'. + * Returns the type of the xmlrpc value. + * + * For integers, 'int' is always returned in place of 'i4'. 'i8' is considered a separate type and returned as such * * @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 xmlrpcval + * @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,142 @@ 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"); + } + } }