5 use PhpXmlRpc\Helper\Charset;
8 * This class enables the creation of values for XML-RPC, by encapsulating plain php values.
10 class Value implements \Countable, \IteratorAggregate, \ArrayAccess
12 public static $xmlrpcI4 = "i4";
13 public static $xmlrpcI8 = "i8";
14 public static $xmlrpcInt = "int";
15 public static $xmlrpcBoolean = "boolean";
16 public static $xmlrpcDouble = "double";
17 public static $xmlrpcString = "string";
18 public static $xmlrpcDateTime = "dateTime.iso8601";
19 public static $xmlrpcBase64 = "base64";
20 public static $xmlrpcArray = "array";
21 public static $xmlrpcStruct = "struct";
22 public static $xmlrpcValue = "undefined";
23 public static $xmlrpcNull = "null";
25 public static $xmlrpcTypes = array(
32 "dateTime.iso8601" => 1,
39 /// @todo: do these need to be public?
42 public $_php_class = null;
45 * Build an xmlrpc value.
47 * When no value or type is passed in, the value is left uninitialized, and the value can be added later.
49 * @param mixed $val if passing in an array, all array elements should be PhpXmlRpc\Value themselves
50 * @param string $type any valid xmlrpc type name (lowercase): i4, int, boolean, string, double, dateTime.iso8601,
51 * base64, array, struct, null.
52 * If null, 'string' is assumed.
53 * You should refer to http://www.xmlrpc.com/spec for more information on what each of these mean.
55 public function __construct($val = -1, $type = '')
57 // optimization creep - do not call addXX, do it all inline.
58 // downside: booleans will not be coerced anymore
59 if ($val !== -1 || $type != '') {
63 $this->me['string'] = $val;
71 case 'dateTime.iso8601':
75 $this->me[$type] = $val;
79 $this->me['array'] = $val;
83 $this->me['struct'] = $val;
86 error_log("XML-RPC: " . __METHOD__ . ": not a known type ($type)");
92 * Add a single php value to an xmlrpc value.
94 * If the xmlrpc value is an array, the php value is added as its last element.
95 * If the xmlrpc value is empty (uninitialized), this method makes it a scalar value, and sets that value.
96 * Fails if the xmlrpc value is not an array and already initialized.
99 * @param string $type allowed values: i4, i8, int, boolean, string, double, dateTime.iso8601, base64, null.
101 * @return int 1 or 0 on failure
103 public function addScalar($val, $type = 'string')
106 if (isset(static::$xmlrpcTypes[$type])) {
107 $typeOf = static::$xmlrpcTypes[$type];
111 error_log("XML-RPC: " . __METHOD__ . ": not a scalar type ($type)");
115 // coerce booleans into correct values
116 // NB: we should either do it for datetimes, integers and doubles, too,
117 // or just plain remove this check, implemented on booleans only...
118 if ($type == static::$xmlrpcBoolean) {
119 if (strcasecmp($val, 'true') == 0 || $val == 1 || ($val == true && strcasecmp($val, 'false'))) {
126 switch ($this->mytype) {
128 error_log('XML-RPC: ' . __METHOD__ . ': scalar xmlrpc value can have only one value');
131 error_log('XML-RPC: ' . __METHOD__ . ': cannot add anonymous scalar to struct xmlrpc value');
134 // we're adding a scalar value to an array here
135 $this->me['array'][] = new Value($val, $type);
139 // a scalar, so set the value and remember we're scalar
140 $this->me[$type] = $val;
141 $this->mytype = $typeOf;
148 * Add an array of xmlrpc value objects to an xmlrpc value.
150 * If the xmlrpc value is an array, the elements are appended to the existing ones.
151 * If the xmlrpc value is empty (uninitialized), this method makes it an array value, and sets that value.
154 * @param Value[] $values
156 * @return int 1 or 0 on failure
158 * @todo add some checking for $values to be an array of xmlrpc values?
160 public function addArray($values)
162 if ($this->mytype == 0) {
163 $this->mytype = static::$xmlrpcTypes['array'];
164 $this->me['array'] = $values;
167 } elseif ($this->mytype == 2) {
168 // we're adding to an array here
169 $this->me['array'] = array_merge($this->me['array'], $values);
173 error_log('XML-RPC: ' . __METHOD__ . ': already initialized as a [' . $this->kindOf() . ']');
179 * Merges an array of named xmlrpc value objects into an xmlrpc value.
181 * If the xmlrpc value is a struct, the elements are merged with the existing ones (overwriting existing ones).
182 * If the xmlrpc value is empty (uninitialized), this method makes it a struct value, and sets that value.
185 * @param Value[] $values
187 * @return int 1 or 0 on failure
189 * @todo add some checking for $values to be an array?
191 public function addStruct($values)
193 if ($this->mytype == 0) {
194 $this->mytype = static::$xmlrpcTypes['struct'];
195 $this->me['struct'] = $values;
198 } elseif ($this->mytype == 3) {
199 // we're adding to a struct here
200 $this->me['struct'] = array_merge($this->me['struct'], $values);
204 error_log('XML-RPC: ' . __METHOD__ . ': already initialized as a [' . $this->kindOf() . ']');
210 * Returns a string containing either "struct", "array", "scalar" or "undef", describing the base type of the value.
214 public function kindOf()
216 switch ($this->mytype) {
231 protected function serializedata($typ, $val, $charsetEncoding = '')
235 if (!isset(static::$xmlrpcTypes[$typ])) {
239 switch (static::$xmlrpcTypes[$typ]) {
242 case static::$xmlrpcBase64:
243 $rs .= "<${typ}>" . base64_encode($val) . "</${typ}>";
245 case static::$xmlrpcBoolean:
246 $rs .= "<${typ}>" . ($val ? '1' : '0') . "</${typ}>";
248 case static::$xmlrpcString:
249 // G. Giunta 2005/2/13: do NOT use htmlentities, since
250 // it will produce named html entities, which are invalid xml
251 $rs .= "<${typ}>" . Charset::instance()->encodeEntities($val, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</${typ}>";
253 case static::$xmlrpcInt:
254 case static::$xmlrpcI4:
255 case static::$xmlrpcI8:
256 $rs .= "<${typ}>" . (int)$val . "</${typ}>";
258 case static::$xmlrpcDouble:
259 // avoid using standard conversion of float to string because it is locale-dependent,
260 // and also because the xmlrpc spec forbids exponential notation.
261 // sprintf('%F') could be most likely ok but it fails eg. on 2e-14.
262 // The code below tries its best at keeping max precision while avoiding exp notation,
263 // but there is of course no limit in the number of decimal places to be used...
264 $rs .= "<${typ}>" . preg_replace('/\\.?0+$/', '', number_format((double)$val, 128, '.', '')) . "</${typ}>";
266 case static::$xmlrpcDateTime:
267 if (is_string($val)) {
268 $rs .= "<${typ}>${val}</${typ}>";
269 } elseif (is_a($val, 'DateTime')) {
270 $rs .= "<${typ}>" . $val->format('Ymd\TH:i:s') . "</${typ}>";
271 } elseif (is_int($val)) {
272 $rs .= "<${typ}>" . strftime("%Y%m%dT%H:%M:%S", $val) . "</${typ}>";
274 // not really a good idea here: but what shall we output anyway? left for backward compat...
275 $rs .= "<${typ}>${val}</${typ}>";
278 case static::$xmlrpcNull:
279 if (PhpXmlRpc::$xmlrpc_null_apache_encoding) {
286 // no standard type value should arrive here, but provide a possibility
287 // for xmlrpc values of unknown type...
288 $rs .= "<${typ}>${val}</${typ}>";
293 if ($this->_php_class) {
294 $rs .= '<struct php_class="' . $this->_php_class . "\">\n";
298 $charsetEncoder = Charset::instance();
299 foreach ($val as $key2 => $val2) {
300 $rs .= '<member><name>' . $charsetEncoder->encodeEntities($key2, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</name>\n";
301 //$rs.=$this->serializeval($val2);
302 $rs .= $val2->serialize($charsetEncoding);
303 $rs .= "</member>\n";
309 $rs .= "<array>\n<data>\n";
310 foreach ($val as $element) {
311 //$rs.=$this->serializeval($val[$i]);
312 $rs .= $element->serialize($charsetEncoding);
314 $rs .= "</data>\n</array>";
324 * Returns the xml representation of the value. XML prologue not included.
326 * @param string $charsetEncoding the charset to be used for serialization. if null, US-ASCII is assumed
330 public function serialize($charsetEncoding = '')
332 // add check? slower, but helps to avoid recursion in serializing broken xmlrpc values...
333 //if (is_object($o) && (get_class($o) == 'xmlrpcval' || is_subclass_of($o, 'xmlrpcval')))
336 list($typ, $val) = each($this->me);
338 return '<value>' . $this->serializedata($typ, $val, $charsetEncoding) . "</value>\n";
343 * Checks whether a struct member with a given name is present.
345 * Works only on xmlrpc values of type struct.
347 * @param string $key the name of the struct member to be looked up
351 * @deprecated use array access, e.g. isset($val[$key])
353 public function structmemexists($key)
355 return array_key_exists($key, $this->me['struct']);
359 * Returns the value of a given struct member (an xmlrpc value object in itself).
360 * Will raise a php warning if struct member of given name does not exist.
362 * @param string $key the name of the struct member to be looked up
366 * @deprecated use array access, e.g. $val[$key]
368 public function structmem($key)
370 return $this->me['struct'][$key];
374 * Reset internal pointer for xmlrpc values of type struct.
375 * @deprecated iterate directly over the object using foreach instead
377 public function structreset()
379 reset($this->me['struct']);
383 * Return next member element for xmlrpc values of type struct.
387 * @deprecated iterate directly over the object using foreach instead
389 public function structeach()
391 return each($this->me['struct']);
395 * Returns the value of a scalar xmlrpc value (base 64 decoding is automatically handled here)
399 public function scalarval()
402 list(, $b) = each($this->me);
408 * Returns the type of the xmlrpc value.
410 * For integers, 'int' is always returned in place of 'i4' or 'i8'.
414 public function scalartyp()
417 list($a,) = each($this->me);
418 if ($a == static::$xmlrpcI4 || $a == static::$xmlrpcI8) {
419 $a = static::$xmlrpcInt;
426 * Returns the m-th member of an xmlrpc value of array type.
428 * @param integer $key the index of the value to be retrieved (zero based)
432 * @deprecated use array access, e.g. $val[$key]
434 public function arraymem($key)
436 return $this->me['array'][$key];
440 * Returns the number of members in an xmlrpc value of array type.
444 * @deprecated use count() instead
446 public function arraysize()
448 return count($this->me['array']);
452 * Returns the number of members in an xmlrpc value of struct type.
456 * @deprecated use count() instead
458 public function structsize()
460 return count($this->me['struct']);
464 * Returns the number of members in an xmlrpc value:
465 * - 0 for uninitialized values
466 * - 1 for scalar values
467 * - the number of elements for struct and array values
471 public function count()
473 switch ($this->mytype) {
475 return count($this->me['struct']);
477 return count($this->me['array']);
486 * Implements the IteratorAggregate interface
488 * @return ArrayIterator
490 public function getIterator() {
491 switch ($this->mytype) {
493 return new \ArrayIterator($this->me['struct']);
495 return new \ArrayIterator($this->me['array']);
497 return new \ArrayIterator($this->me);
499 return new \ArrayIterator();
501 return new \ArrayIterator();
505 public function offsetSet($offset, $value) {
507 switch ($this->mytype) {
509 if (!($value instanceof \PhpXmlRpc\Value)) {
510 throw new \Exception('It is only possible to add Value objects to an XML-RPC Struct');
512 if (is_null($offset)) {
513 // disallow struct members with empty names
514 throw new \Exception('It is not possible to add anonymous members to an XML-RPC Struct');
516 $this->me['struct'][$offset] = $value;
520 if (!($value instanceof \PhpXmlRpc\Value)) {
521 throw new \Exception('It is only possible to add Value objects to an XML-RPC Array');
523 if (is_null($offset)) {
524 $this->me['array'][] = $value;
526 // nb: we are not checking that $offset is above the existing array range...
527 $this->me['array'][$offset] = $value;
531 // todo: handle i4/i8 vs int
533 list($type,) = each($this->me);
534 if ($type != $offset) {
535 throw new \Exception('');
537 $this->me[$type] = $value;
540 // 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
541 throw new \Exception("XML-RPC Value is of type 'undef' and its value can not be set using array index");
545 public function offsetExists($offset) {
546 switch ($this->mytype) {
548 return isset($this->me['struct'][$offset]);
550 return isset($this->me['array'][$offset]);
552 // todo: handle i4/i8 vs int
553 return $offset == $this->scalartyp();
559 public function offsetUnset($offset) {
560 switch ($this->mytype) {
562 unset($this->me['struct'][$offset]);
565 unset($this->me['array'][$offset]);
568 // can not remove value from a scalar
569 throw new \Exception("XML-RPC Value is of type 'scalar' and its value can not be unset using array index");
571 throw new \Exception("XML-RPC Value is of type 'undef' and its value can not be unset using array index");
575 public function offsetGet($offset) {
576 switch ($this->mytype) {
578 return isset($this->me['struct'][$offset]) ? $this->me['struct'][$offset] : null;
580 return isset($this->me['array'][$offset]) ? $this->me['array'][$offset] : null;
582 // on bad type: null or exception?
584 list($type, $value) = each($this->me);
585 return $type == $offset ? $value : null;
587 // return null or exception?
588 throw new \Exception("XML-RPC Value is of type 'undef' and can not be accessed using array index");