Zend/Gdata/App/Base.php

   1 <?php
   2
   3 /**
   4  * Zend Framework
   5  *
   6  * LICENSE
   7  *
   8  * This source file is subject to the new BSD license that is bundled
   9  * with this package in the file LICENSE.txt.
  10  * It is also available through the world-wide-web at this URL:
  11  * http://framework.zend.com/license/new-bsd
  12  * If you did not receive a copy of the license and are unable to
  13  * obtain it through the world-wide-web, please send an email
  14  * to license@zend.com so we can send you a copy immediately.
  15  *
  16  * @category   Zend
  17  * @package    Zend_Gdata
  18  * @subpackage App
  19  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  20  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21
  22  */
  23
  24 /**
  25  * @see Zend_Gdata_App_Util
  26  */
  27 require_once 'Zend/Gdata/App/Util.php';
  28
  29 /**
  30  * Abstract class for all XML elements
  31  *
  32  * @category   Zend
  33  * @package    Zend_Gdata
  34  * @subpackage App
  35  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  36  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  37  */
  38 abstract class Zend_Gdata_App_Base
  39 {
  40
  41     /**
  42      * @var string The XML element name, including prefix if desired
  43      */
  44     protected $_rootElement = null;
  45
  46     /**
  47      * @var string The XML namespace prefix
  48      */
  49     protected $_rootNamespace = 'atom';
  50
  51     /**
  52      * @var string The XML namespace URI - takes precedence over lookup up the
  53      * corresponding URI for $_rootNamespace
  54      */
  55     protected $_rootNamespaceURI = null;
  56
  57     /**
  58      * @var array Leftover elements which were not handled
  59      */
  60     protected $_extensionElements = array();
  61
  62     /**
  63      * @var array Leftover attributes which were not handled
  64      */
  65     protected $_extensionAttributes = array();
  66
  67     /**
  68      * @var string XML child text node content
  69      */
  70     protected $_text = null;
  71
  72     /**
  73      * @var array Memoized results from calls to lookupNamespace() to avoid
  74      *      expensive calls to getGreatestBoundedValue(). The key is in the
  75      *      form 'prefix-majorVersion-minorVersion', and the value is the
  76      *      output from getGreatestBoundedValue().
  77      */
  78     protected static $_namespaceLookupCache = array();
  79
  80     /**
  81      * List of namespaces, as a three-dimensional array. The first dimension
  82      * represents the namespace prefix, the second dimension represents the
  83      * minimum major protocol version, and the third dimension is the minimum
  84      * minor protocol version. Null keys are NOT allowed.
  85      *
  86      * When looking up a namespace for a given prefix, the greatest version
  87      * number (both major and minor) which is less than the effective version
  88      * should be used.
  89      *
  90      * @see lookupNamespace()
  91      * @see registerNamespace()
  92      * @see registerAllNamespaces()
  93      * @var array
  94      */
  95    protected $_namespaces = array(
  96         'atom'      => array(
  97             1 => array(
  98                 0 => 'http://www.w3.org/2005/Atom'
  99                 )
 100             ),
 101         'app'       => array(
 102             1 => array(
 103                 0 => 'http://purl.org/atom/app#'
 104                 ),
 105             2 => array(
 106                 0 => 'http://www.w3.org/2007/app'
 107                 )
 108             )
 109         );
 110
 111     public function __construct()
 112     {
 113     }
 114
 115     /**
 116      * Returns the child text node of this element
 117      * This represents any raw text contained within the XML element
 118      *
 119      * @return string Child text node
 120      */
 121     public function getText($trim = true)
 122     {
 123         if ($trim) {
 124             return trim($this->_text);
 125         } else {
 126             return $this->_text;
 127         }
 128     }
 129
 130     /**
 131      * Sets the child text node of this element
 132      * This represents any raw text contained within the XML element
 133      *
 134      * @param string $value Child text node
 135      * @return Zend_Gdata_App_Base Returns an object of the same type as 'this' to provide a fluent interface.
 136      */
 137     public function setText($value)
 138     {
 139         $this->_text = $value;
 140         return $this;
 141     }
 142
 143     /**
 144      * Returns an array of all elements not matched to data model classes
 145      * during the parsing of the XML
 146      *
 147      * @return array All elements not matched to data model classes during parsing
 148      */
 149     public function getExtensionElements()
 150     {
 151         return $this->_extensionElements;
 152     }
 153
 154     /**
 155      * Sets an array of all elements not matched to data model classes
 156      * during the parsing of the XML.  This method can be used to add arbitrary
 157      * child XML elements to any data model class.
 158      *
 159      * @param array $value All extension elements
 160      * @return Zend_Gdata_App_Base Returns an object of the same type as 'this' to provide a fluent interface.
 161      */
 162     public function setExtensionElements($value)
 163     {
 164         $this->_extensionElements = $value;
 165         return $this;
 166     }
 167
 168     /**
 169      * Returns an array of all extension attributes not transformed into data
 170      * model properties during parsing of the XML.  Each element of the array
 171      * is a hashed array of the format:
 172      *     array('namespaceUri' => string, 'name' => string, 'value' => string);
 173      *
 174      * @return array All extension attributes
 175      */
 176     public function getExtensionAttributes()
 177     {
 178         return $this->_extensionAttributes;
 179     }
 180
 181     /**
 182      * Sets an array of all extension attributes not transformed into data
 183      * model properties during parsing of the XML.  Each element of the array
 184      * is a hashed array of the format:
 185      *     array('namespaceUri' => string, 'name' => string, 'value' => string);
 186      * This can be used to add arbitrary attributes to any data model element
 187      *
 188      * @param array $value All extension attributes
 189      * @return Zend_Gdata_App_Base Returns an object of the same type as 'this' to provide a fluent interface.
 190      */
 191     public function setExtensionAttributes($value)
 192     {
 193         $this->_extensionAttributes = $value;
 194         return $this;
 195     }
 196
 197     /**
 198      * Retrieves a DOMElement which corresponds to this element and all
 199      * child properties.  This is used to build an entry back into a DOM
 200      * and eventually XML text for sending to the server upon updates, or
 201      * for application storage/persistence.
 202      *
 203      * @param DOMDocument $doc The DOMDocument used to construct DOMElements
 204      * @return DOMElement The DOMElement representing this element and all
 205      * child properties.
 206      */
 207     public function getDOM($doc = null, $majorVersion = 1, $minorVersion = null)
 208     {
 209         if ($doc === null) {
 210             $doc = new DOMDocument('1.0', 'utf-8');
 211         }
 212         if ($this->_rootNamespaceURI != null) {
 213             $element = $doc->createElementNS($this->_rootNamespaceURI, $this->_rootElement);
 214         } elseif ($this->_rootNamespace !== null) {
 215             if (strpos($this->_rootElement, ':') === false) {
 216                 $elementName = $this->_rootNamespace . ':' . $this->_rootElement;
 217             } else {
 218                 $elementName = $this->_rootElement;
 219             }
 220             $element = $doc->createElementNS($this->lookupNamespace($this->_rootNamespace), $elementName);
 221         } else {
 222             $element = $doc->createElement($this->_rootElement);
 223         }
 224         if ($this->_text != null) {
 225             $element->appendChild($element->ownerDocument->createTextNode($this->_text));
 226         }
 227         foreach ($this->_extensionElements as $extensionElement) {
 228             $element->appendChild($extensionElement->getDOM($element->ownerDocument));
 229         }
 230         foreach ($this->_extensionAttributes as $attribute) {
 231             $element->setAttribute($attribute['name'], $attribute['value']);
 232         }
 233         return $element;
 234     }
 235
 236     /**
 237      * Given a child DOMNode, tries to determine how to map the data into
 238      * object instance members.  If no mapping is defined, Extension_Element
 239      * objects are created and stored in an array.
 240      *
 241      * @param DOMNode $child The DOMNode needed to be handled
 242      */
 243     protected function takeChildFromDOM($child)
 244     {
 245         if ($child->nodeType == XML_TEXT_NODE) {
 246             $this->_text = $child->nodeValue;
 247         } else {
 248             $extensionElement = new Zend_Gdata_App_Extension_Element();
 249             $extensionElement->transferFromDOM($child);
 250             $this->_extensionElements[] = $extensionElement;
 251         }
 252     }
 253
 254     /**
 255      * Given a DOMNode representing an attribute, tries to map the data into
 256      * instance members.  If no mapping is defined, the name and value are
 257      * stored in an array.
 258      *
 259      * @param DOMNode $attribute The DOMNode attribute needed to be handled
 260      */
 261     protected function takeAttributeFromDOM($attribute)
 262     {
 263         $arrayIndex = ($attribute->namespaceURI != '')?(
 264                 $attribute->namespaceURI . ':' . $attribute->name):
 265                 $attribute->name;
 266         $this->_extensionAttributes[$arrayIndex] =
 267                 array('namespaceUri' => $attribute->namespaceURI,
 268                       'name' => $attribute->localName,
 269                       'value' => $attribute->nodeValue);
 270     }
 271
 272     /**
 273      * Transfers each child and attribute into member variables.
 274      * This is called when XML is received over the wire and the data
 275      * model needs to be built to represent this XML.
 276      *
 277      * @param DOMNode $node The DOMNode that represents this object's data
 278      */
 279     public function transferFromDOM($node)
 280     {
 281         foreach ($node->childNodes as $child) {
 282             $this->takeChildFromDOM($child);
 283         }
 284         foreach ($node->attributes as $attribute) {
 285             $this->takeAttributeFromDOM($attribute);
 286         }
 287     }
 288
 289     /**
 290      * Parses the provided XML text and generates data model classes for
 291      * each know element by turning the XML text into a DOM tree and calling
 292      * transferFromDOM($element).  The first data model element with the same
 293      * name as $this->_rootElement is used and the child elements are
 294      * recursively parsed.
 295      *
 296      * @param string $xml The XML text to parse
 297      */
 298     public function transferFromXML($xml)
 299     {
 300         if ($xml) {
 301             // Load the feed as an XML DOMDocument object
 302             @ini_set('track_errors', 1);
 303             $doc = new DOMDocument();
 304             $success = @$doc->loadXML($xml);
 305             @ini_restore('track_errors');
 306             if (!$success) {
 307                 require_once 'Zend/Gdata/App/Exception.php';
 308                 throw new Zend_Gdata_App_Exception("DOMDocument cannot parse XML: $php_errormsg");
 309             }
 310             $element = $doc->getElementsByTagName($this->_rootElement)->item(0);
 311             if (!$element) {
 312                 require_once 'Zend/Gdata/App/Exception.php';
 313                 throw new Zend_Gdata_App_Exception('No root <' . $this->_rootElement . '> element');
 314             }
 315             $this->transferFromDOM($element);
 316         } else {
 317             require_once 'Zend/Gdata/App/Exception.php';
 318             throw new Zend_Gdata_App_Exception('XML passed to transferFromXML cannot be null');
 319         }
 320     }
 321
 322     /**
 323      * Converts this element and all children into XML text using getDOM()
 324      *
 325      * @return string XML content
 326      */
 327     public function saveXML()
 328     {
 329         $element = $this->getDOM();
 330         return $element->ownerDocument->saveXML($element);
 331     }
 332
 333     /**
 334      * Alias for saveXML() returns XML content for this element and all
 335      * children
 336      *
 337      * @return string XML content
 338      */
 339     public function getXML()
 340     {
 341         return $this->saveXML();
 342     }
 343
 344     /**
 345      * Alias for saveXML()
 346      *
 347      * Can be overridden by children to provide more complex representations
 348      * of entries.
 349      *
 350      * @return string Encoded string content
 351      */
 352     public function encode()
 353     {
 354         return $this->saveXML();
 355     }
 356
 357     /**
 358      * Get the full version of a namespace prefix
 359      *
 360      * Looks up a prefix (atom:, etc.) in the list of registered
 361      * namespaces and returns the full namespace URI if
 362      * available. Returns the prefix, unmodified, if it's not
 363      * registered.
 364      *
 365      * @param string $prefix The namespace prefix to lookup.
 366      * @param integer $majorVersion The major protocol version in effect.
 367      *        Defaults to '1'.
 368      * @param integer $minorVersion The minor protocol version in effect.
 369      *        Defaults to null (use latest).
 370      * @return string
 371      */
 372     public function lookupNamespace($prefix,
 373                                     $majorVersion = 1,
 374                                     $minorVersion = null)
 375     {
 376         // Check for a memoized result
 377         $key = $prefix . ' ' .
 378                (is_null($majorVersion) ? 'NULL' : $majorVersion) .
 379                ' '. (is_null($minorVersion) ? 'NULL' : $minorVersion);
 380         if (array_key_exists($key, self::$_namespaceLookupCache))
 381           return self::$_namespaceLookupCache[$key];
 382         // If no match, return the prefix by default
 383         $result = $prefix;
 384
 385         // Find tuple of keys that correspond to the namespace we should use
 386         if (isset($this->_namespaces[$prefix])) {
 387             // Major version search
 388             $nsData = $this->_namespaces[$prefix];
 389             $foundMajorV = Zend_Gdata_App_Util::findGreatestBoundedValue(
 390                     $majorVersion, $nsData);
 391             // Minor version search
 392             $nsData = $nsData[$foundMajorV];
 393             $foundMinorV = Zend_Gdata_App_Util::findGreatestBoundedValue(
 394                     $minorVersion, $nsData);
 395             // Extract NS
 396             $result = $nsData[$foundMinorV];
 397         }
 398
 399         // Memoize result
 400         self::$_namespaceLookupCache[$key] = $result;
 401
 402         return $result;
 403     }
 404
 405     /**
 406      * Add a namespace and prefix to the registered list
 407      *
 408      * Takes a prefix and a full namespace URI and adds them to the
 409      * list of registered namespaces for use by
 410      * $this->lookupNamespace().
 411      *
 412      * WARNING: Currently, registering a namespace will NOT invalidate any
 413      *          memoized data stored in $_namespaceLookupCache. Under normal
 414      *          use, this behavior is acceptable. If you are adding
 415      *          contradictory data to the namespace lookup table, you must
 416      *          call flushNamespaceLookupCache().
 417      *
 418      * @param  string $prefix The namespace prefix
 419      * @param  string $namespaceUri The full namespace URI
 420      * @param integer $majorVersion The major protocol version in effect.
 421      *        Defaults to '1'.
 422      * @param integer $minorVersion The minor protocol version in effect.
 423      *        Defaults to null (use latest).
 424      * @return void
 425      */
 426     public function registerNamespace($prefix,
 427                                       $namespaceUri,
 428                                       $majorVersion = 1,
 429                                       $minorVersion = 0)
 430     {
 431         $this->_namespaces[$prefix][$majorVersion][$minorVersion] =
 432         $namespaceUri;
 433     }
 434
 435     /**
 436      * Flush namespace lookup cache.
 437      *
 438      * Empties the namespace lookup cache. Call this function if you have
 439      * added data to the namespace lookup table that contradicts values that
 440      * may have been cached during a previous call to lookupNamespace().
 441      */
 442     public static function flushNamespaceLookupCache()
 443     {
 444         self::$_namespaceLookupCache = array();
 445     }
 446
 447     /**
 448      * Add an array of namespaces to the registered list.
 449      *
 450      * Takes an array in the format of:
 451      * namespace prefix, namespace URI, major protocol version,
 452      * minor protocol version and adds them with calls to ->registerNamespace()
 453      *
 454      * @param array $namespaceArray An array of namespaces.
 455      * @return void
 456      */
 457     public function registerAllNamespaces($namespaceArray)
 458     {
 459         foreach($namespaceArray as $namespace) {
 460                 $this->registerNamespace(
 461                     $namespace[0], $namespace[1], $namespace[2], $namespace[3]);
 462         }
 463     }
 464
 465
 466     /**
 467      * Magic getter to allow access like $entry->foo to call $entry->getFoo()
 468      * Alternatively, if no getFoo() is defined, but a $_foo protected variable
 469      * is defined, this is returned.
 470      *
 471      * TODO Remove ability to bypass getFoo() methods??
 472      *
 473      * @param string $name The variable name sought
 474      */
 475     public function __get($name)
 476     {
 477         $method = 'get'.ucfirst($name);
 478         if (method_exists($this, $method)) {
 479             return call_user_func(array(&$this, $method));
 480         } else if (property_exists($this, "_${name}")) {
 481             return $this->{'_' . $name};
 482         } else {
 483             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 484             throw new Zend_Gdata_App_InvalidArgumentException(
 485                     'Property ' . $name . ' does not exist');
 486         }
 487     }
 488
 489     /**
 490      * Magic setter to allow acces like $entry->foo='bar' to call
 491      * $entry->setFoo('bar') automatically.
 492      *
 493      * Alternatively, if no setFoo() is defined, but a $_foo protected variable
 494      * is defined, this is returned.
 495      *
 496      * TODO Remove ability to bypass getFoo() methods??
 497      *
 498      * @param string $name
 499      * @param string $value
 500      */
 501     public function __set($name, $val)
 502     {
 503         $method = 'set'.ucfirst($name);
 504         if (method_exists($this, $method)) {
 505             return call_user_func(array(&$this, $method), $val);
 506         } else if (isset($this->{'_' . $name}) || ($this->{'_' . $name} === null)) {
 507             $this->{'_' . $name} = $val;
 508         } else {
 509             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 510             throw new Zend_Gdata_App_InvalidArgumentException(
 511                     'Property ' . $name . '  does not exist');
 512         }
 513     }
 514
 515     /**
 516      * Magic __isset method
 517      *
 518      * @param string $name
 519      */
 520     public function __isset($name)
 521     {
 522         $rc = new ReflectionClass(get_class($this));
 523         $privName = '_' . $name;
 524         if (!($rc->hasProperty($privName))) {
 525             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 526             throw new Zend_Gdata_App_InvalidArgumentException(
 527                     'Property ' . $name . ' does not exist');
 528         } else {
 529             if (isset($this->{$privName})) {
 530                 if (is_array($this->{$privName})) {
 531                     if (count($this->{$privName}) > 0) {
 532                         return true;
 533                     } else {
 534                         return false;
 535                     }
 536                 } else {
 537                     return true;
 538                 }
 539             } else {
 540                 return false;
 541             }
 542         }
 543     }
 544
 545     /**
 546      * Magic __unset method
 547      *
 548      * @param string $name
 549      */
 550     public function __unset($name)
 551     {
 552         if (isset($this->{'_' . $name})) {
 553             if (is_array($this->{'_' . $name})) {
 554                 $this->{'_' . $name} = array();
 555             } else {
 556                 $this->{'_' . $name} = null;
 557             }
 558         }
 559     }
 560
 561     /**
 562      * Magic toString method allows using this directly via echo
 563      * Works best in PHP >= 4.2.0
 564      *
 565      * @return string The text representation of this object
 566      */
 567     public function __toString()
 568     {
 569         return $this->getText();
 570     }
 571
 572 }