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  * @version    $Id: Base.php 22662 2010-07-24 17:37:36Z mabe $

    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                ($majorVersion === null ? 'NULL' : $majorVersion) .

   379                ' '. ($minorVersion === null ? '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 }