library/Zend/XmlRpc/Value.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   7  * This source file is subject to the new BSD license that is bundled
   8  * with this package in the file LICENSE.txt.
   9  * It is also available through the world-wide-web at this URL:
  10  * http://framework.zend.com/license/new-bsd
  11  * If you did not receive a copy of the license and are unable to
  12  * obtain it through the world-wide-web, please send an email
  13  * to license@zend.com so we can send you a copy immediately.
  14  *
  15  * @category   Zend
  16  * @package    Zend_XmlRpc
  17  * @subpackage Value
  18  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  19  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20  * @version    $Id: Value.php 17786 2009-08-23 22:26:33Z lars $
  21  */
  22
  23 /**
  24  * Represent a native XML-RPC value entity, used as parameters for the methods
  25  * called by the Zend_XmlRpc_Client object and as the return value for those calls.
  26  *
  27  * This object as a very important static function Zend_XmlRpc_Value::getXmlRpcValue, this
  28  * function acts likes a factory for the Zend_XmlRpc_Value objects
  29  *
  30  * Using this function, users/Zend_XmlRpc_Client object can create the Zend_XmlRpc_Value objects
  31  * from PHP variables, XML string or by specifing the exact XML-RPC natvie type
  32  *
  33  * @package    Zend_XmlRpc
  34  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  35  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  36  */
  37 abstract class Zend_XmlRpc_Value
  38 {
  39     /**
  40      * The native XML-RPC representation of this object's value
  41      *
  42      * If the native type of this object is array or struct, this will be an array
  43      * of Zend_XmlRpc_Value objects
  44      */
  45     protected $_value;
  46
  47     /**
  48      * The native XML-RPC type of this object
  49      * One of the XMLRPC_TYPE_* constants
  50      */
  51     protected $_type;
  52
  53     /**
  54      * XML code representation of this object (will be calculated only once)
  55      */
  56     protected $_as_xml;
  57
  58     /**
  59      * DOMElement representation of object (will be calculated only once)
  60      */
  61     protected $_as_dom;
  62
  63     /**
  64      * Specify that the XML-RPC native type will be auto detected from a PHP variable type
  65      */
  66     const AUTO_DETECT_TYPE = 'auto_detect';
  67
  68     /**
  69      * Specify that the XML-RPC value will be parsed out from a given XML code
  70      */
  71     const XML_STRING = 'xml';
  72
  73     /**
  74      * All the XML-RPC native types
  75      */
  76     const XMLRPC_TYPE_I4       = 'i4';
  77     const XMLRPC_TYPE_INTEGER  = 'int';
  78     const XMLRPC_TYPE_DOUBLE   = 'double';
  79     const XMLRPC_TYPE_BOOLEAN  = 'boolean';
  80     const XMLRPC_TYPE_STRING   = 'string';
  81     const XMLRPC_TYPE_DATETIME = 'dateTime.iso8601';
  82     const XMLRPC_TYPE_BASE64   = 'base64';
  83     const XMLRPC_TYPE_ARRAY    = 'array';
  84     const XMLRPC_TYPE_STRUCT   = 'struct';
  85     const XMLRPC_TYPE_NIL      = 'nil';
  86
  87
  88     /**
  89      * Get the native XML-RPC type (the type is one of the Zend_XmlRpc_Value::XMLRPC_TYPE_* constants)
  90      *
  91      * @return string
  92      */
  93     public function getType()
  94     {
  95         return $this->_type;
  96     }
  97
  98
  99     /**
 100      * Return the value of this object, convert the XML-RPC native value into a PHP variable
 101      *
 102      * @return mixed
 103      */
 104     abstract public function getValue();
 105
 106
 107     /**
 108      * Return the XML code that represent a native MXL-RPC value
 109      *
 110      * @return string
 111      */
 112     abstract public function saveXML();
 113
 114     /**
 115      * Return DOMElement representation of object
 116      *
 117      * @return DOMElement
 118      */
 119     public function getAsDOM()
 120     {
 121         if (!$this->_as_dom) {
 122             $doc = new DOMDocument('1.0');
 123             $doc->loadXML($this->saveXML());
 124             $this->_as_dom = $doc->documentElement;
 125         }
 126
 127         return $this->_as_dom;
 128     }
 129
 130     protected function _stripXmlDeclaration(DOMDocument $dom)
 131     {
 132         return preg_replace('/<\?xml version="1.0"( encoding="[^\"]*")?\?>\n/u', '', $dom->saveXML());
 133     }
 134
 135     /**
 136      * Creates a Zend_XmlRpc_Value* object, representing a native XML-RPC value
 137      * A XmlRpcValue object can be created in 3 ways:
 138      * 1. Autodetecting the native type out of a PHP variable
 139      *    (if $type is not set or equal to Zend_XmlRpc_Value::AUTO_DETECT_TYPE)
 140      * 2. By specifing the native type ($type is one of the Zend_XmlRpc_Value::XMLRPC_TYPE_* constants)
 141      * 3. From a XML string ($type is set to Zend_XmlRpc_Value::XML_STRING)
 142      *
 143      * By default the value type is autodetected according to it's PHP type
 144      *
 145      * @param mixed $value
 146      * @param Zend_XmlRpc_Value::constant $type
 147      *
 148      * @return Zend_XmlRpc_Value
 149      * @static
 150      */
 151     public static function getXmlRpcValue($value, $type = self::AUTO_DETECT_TYPE)
 152     {
 153         switch ($type) {
 154             case self::AUTO_DETECT_TYPE:
 155                 // Auto detect the XML-RPC native type from the PHP type of $value
 156                 return self::_phpVarToNativeXmlRpc($value);
 157
 158             case self::XML_STRING:
 159                 // Parse the XML string given in $value and get the XML-RPC value in it
 160                 return self::_xmlStringToNativeXmlRpc($value);
 161
 162             case self::XMLRPC_TYPE_I4:
 163                 // fall through to the next case
 164             case self::XMLRPC_TYPE_INTEGER:
 165                 return new Zend_XmlRpc_Value_Integer($value);
 166
 167             case self::XMLRPC_TYPE_DOUBLE:
 168                 return new Zend_XmlRpc_Value_Double($value);
 169
 170             case self::XMLRPC_TYPE_BOOLEAN:
 171                 return new Zend_XmlRpc_Value_Boolean($value);
 172
 173             case self::XMLRPC_TYPE_STRING:
 174                 return new Zend_XmlRpc_Value_String($value);
 175
 176             case self::XMLRPC_TYPE_BASE64:
 177                 return new Zend_XmlRpc_Value_Base64($value);
 178
 179             case self::XMLRPC_TYPE_NIL:
 180                 return new Zend_XmlRpc_Value_Nil();
 181
 182             case self::XMLRPC_TYPE_DATETIME:
 183                 return new Zend_XmlRpc_Value_DateTime($value);
 184
 185             case self::XMLRPC_TYPE_ARRAY:
 186                 return new Zend_XmlRpc_Value_Array($value);
 187
 188             case self::XMLRPC_TYPE_STRUCT:
 189                 return new Zend_XmlRpc_Value_Struct($value);
 190
 191             default:
 192                 require_once 'Zend/XmlRpc/Value/Exception.php';
 193                 throw new Zend_XmlRpc_Value_Exception('Given type is not a '. __CLASS__ .' constant');
 194         }
 195     }
 196
 197
 198     /**
 199      * Transform a PHP native variable into a XML-RPC native value
 200      *
 201      * @param mixed $value The PHP variable for convertion
 202      *
 203      * @return Zend_XmlRpc_Value
 204      * @static
 205      */
 206     private static function _phpVarToNativeXmlRpc($value)
 207     {
 208         switch (gettype($value)) {
 209             case 'object':
 210                 // Check to see if it's an XmlRpc value
 211                 if ($value instanceof Zend_XmlRpc_Value) {
 212                     return $value;
 213                 }
 214
 215                 // Otherwise, we convert the object into a struct
 216                 $value = get_object_vars($value);
 217                 // Break intentionally omitted
 218             case 'array':
 219                 // Default native type for a PHP array (a simple numeric array) is 'array'
 220                 require_once 'Zend/XmlRpc/Value/Array.php';
 221                 $obj = 'Zend_XmlRpc_Value_Array';
 222
 223                 // Determine if this is an associative array
 224                 if (!empty($value) && is_array($value) && (array_keys($value) !== range(0, count($value) - 1))) {
 225                     require_once 'Zend/XmlRpc/Value/Struct.php';
 226                     $obj = 'Zend_XmlRpc_Value_Struct';
 227                 }
 228                 return new $obj($value);
 229
 230             case 'integer':
 231                 require_once 'Zend/XmlRpc/Value/Integer.php';
 232                 return new Zend_XmlRpc_Value_Integer($value);
 233
 234             case 'double':
 235                 require_once 'Zend/XmlRpc/Value/Double.php';
 236                 return new Zend_XmlRpc_Value_Double($value);
 237
 238             case 'boolean':
 239                 require_once 'Zend/XmlRpc/Value/Boolean.php';
 240                 return new Zend_XmlRpc_Value_Boolean($value);
 241
 242             case 'NULL':
 243             case 'null':
 244                 require_once 'Zend/XmlRpc/Value/Nil.php';
 245                 return new Zend_XmlRpc_Value_Nil();
 246
 247             case 'string':
 248                 // Fall through to the next case
 249             default:
 250                 // If type isn't identified (or identified as string), it treated as string
 251                 require_once 'Zend/XmlRpc/Value/String.php';
 252                 return new Zend_XmlRpc_Value_String($value);
 253         }
 254     }
 255
 256
 257     /**
 258      * Transform an XML string into a XML-RPC native value
 259      *
 260      * @param string|SimpleXMLElement $xml A SimpleXMLElement object represent the XML string
 261      *                                            It can be also a valid XML string for convertion
 262      *
 263      * @return Zend_XmlRpc_Value
 264      * @static
 265      */
 266     private static function _xmlStringToNativeXmlRpc($xml)
 267     {
 268         if (!$xml instanceof SimpleXMLElement) {
 269             try {
 270                 $xml = @new SimpleXMLElement($xml);
 271             } catch (Exception $e) {
 272                 // The given string is not a valid XML
 273                 require_once 'Zend/XmlRpc/Value/Exception.php';
 274                 throw new Zend_XmlRpc_Value_Exception('Failed to create XML-RPC value from XML string: '.$e->getMessage(),$e->getCode());
 275             }
 276         }
 277
 278         // Get the key (tag name) and value from the simple xml object and convert the value to an XML-RPC native value
 279         list($type, $value) = each($xml);
 280         if (!$type) {    // If no type was specified, the default is string
 281             $type = self::XMLRPC_TYPE_STRING;
 282         }
 283
 284         switch ($type) {
 285             // All valid and known XML-RPC native values
 286             case self::XMLRPC_TYPE_I4:
 287                 // Fall through to the next case
 288             case self::XMLRPC_TYPE_INTEGER:
 289                 require_once 'Zend/XmlRpc/Value/Integer.php';
 290                 $xmlrpc_val = new Zend_XmlRpc_Value_Integer($value);
 291                 break;
 292             case self::XMLRPC_TYPE_DOUBLE:
 293                 require_once 'Zend/XmlRpc/Value/Double.php';
 294                 $xmlrpc_val = new Zend_XmlRpc_Value_Double($value);
 295                 break;
 296             case self::XMLRPC_TYPE_BOOLEAN:
 297                 require_once 'Zend/XmlRpc/Value/Boolean.php';
 298                 $xmlrpc_val = new Zend_XmlRpc_Value_Boolean($value);
 299                 break;
 300             case self::XMLRPC_TYPE_STRING:
 301                 require_once 'Zend/XmlRpc/Value/String.php';
 302                 $xmlrpc_val = new Zend_XmlRpc_Value_String($value);
 303                 break;
 304             case self::XMLRPC_TYPE_DATETIME:  // The value should already be in a iso8601 format
 305                 require_once 'Zend/XmlRpc/Value/DateTime.php';
 306                 $xmlrpc_val = new Zend_XmlRpc_Value_DateTime($value);
 307                 break;
 308             case self::XMLRPC_TYPE_BASE64:    // The value should already be base64 encoded
 309                 require_once 'Zend/XmlRpc/Value/Base64.php';
 310                 $xmlrpc_val = new Zend_XmlRpc_Value_Base64($value ,true);
 311                 break;
 312             case self::XMLRPC_TYPE_NIL:    // The value should always be NULL
 313                 $xmlrpc_val = new Zend_XmlRpc_Value_Nil();
 314                 break;
 315             case self::XMLRPC_TYPE_ARRAY:
 316                 // PHP 5.2.4 introduced a regression in how empty($xml->value)
 317                 // returns; need to look for the item specifically
 318                 $data = null;
 319                 foreach ($value->children() as $key => $value) {
 320                     if ('data' == $key) {
 321                         $data = $value;
 322                         break;
 323                     }
 324                 }
 325
 326                 if (null === $data) {
 327                     require_once 'Zend/XmlRpc/Value/Exception.php';
 328                     throw new Zend_XmlRpc_Value_Exception('Invalid XML for XML-RPC native '. self::XMLRPC_TYPE_ARRAY .' type: ARRAY tag must contain DATA tag');
 329                 }
 330                 $values = array();
 331                 // Parse all the elements of the array from the XML string
 332                 // (simple xml element) to Zend_XmlRpc_Value objects
 333                 foreach ($data->value as $element) {
 334                     $values[] = self::_xmlStringToNativeXmlRpc($element);
 335                 }
 336                 require_once 'Zend/XmlRpc/Value/Array.php';
 337                 $xmlrpc_val = new Zend_XmlRpc_Value_Array($values);
 338                 break;
 339             case self::XMLRPC_TYPE_STRUCT:
 340                 $values = array();
 341                 // Parse all the memebers of the struct from the XML string
 342                 // (simple xml element) to Zend_XmlRpc_Value objects
 343                 foreach ($value->member as $member) {
 344                     // @todo? If a member doesn't have a <value> tag, we don't add it to the struct
 345                     // Maybe we want to throw an exception here ?
 346                     if (!isset($member->value) or !isset($member->name)) {
 347                         continue;
 348                         //throw new Zend_XmlRpc_Value_Exception('Member of the '. self::XMLRPC_TYPE_STRUCT .' XML-RPC native type must contain a VALUE tag');
 349                     }
 350                     $values[(string)$member->name] = self::_xmlStringToNativeXmlRpc($member->value);
 351                 }
 352                 require_once 'Zend/XmlRpc/Value/Struct.php';
 353                 $xmlrpc_val = new Zend_XmlRpc_Value_Struct($values);
 354                 break;
 355             default:
 356                 require_once 'Zend/XmlRpc/Value/Exception.php';
 357                 throw new Zend_XmlRpc_Value_Exception('Value type \''. $type .'\' parsed from the XML string is not a known XML-RPC native type');
 358                 break;
 359         }
 360         $xmlrpc_val->_setXML($xml->asXML());
 361
 362         return $xmlrpc_val;
 363     }
 364
 365
 366     private function _setXML($xml)
 367     {
 368         $this->_as_xml = $xml;
 369     }
 370
 371
 372     /**
 373      * Make sure a string will be safe for XML, convert risky characters to entities
 374      *
 375      * @param string $str
 376      * @return string
 377      */
 378     protected function _escapeXmlEntities($str)
 379     {
 380         return htmlspecialchars($str, ENT_QUOTES, 'UTF-8');
 381     }
 382
 383     /**
 384      * Convert XML entities into string values
 385      *
 386      * @param string $str
 387      * @return string
 388      */
 389     protected function _decodeXmlEntities($str)
 390     {
 391         return html_entity_decode($str, ENT_QUOTES, 'UTF-8');
 392     }
 393 }