Apache Zeta Components Manual :: File Source for itunes_module.php

Source for file itunes_module.php

Documentation is available at itunes_module.php

  1. <?php
  2. /**
  3.  * File containing the ezcFeedITunesModule class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @package Feed
  23.  * @version //autogentag//
  24.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  25.  * @filesource
  26.  */
  27.  
  28. /**
  29.  * Support for the iTunes module: data container, generator, parser.
  30.  *
  31.  * Specifications: {@link http://www.apple.com/itunes/store/podcaststechspecs.html}.
  32.  *
  33.  * Create example:
  34.  *
  35.  * <code>
  36.  * <?php
  37.  * // $feed is an ezcFeed object
  38.  * $item = $feed->add( 'item' );
  39.  * $module = $item->addModule( 'iTunes' );
  40.  * $category = $module->add( 'category' );
  41.  * $category->term = 'Category name';
  42.  * // add a sub-category
  43.  * $subCategory = $category->add( 'category' );
  44.  * $subCategory->term = 'Sub-category name';
  45.  * ?>
  46.  * </code>
  47.  *
  48.  * Parse example:
  49.  *
  50.  * <code>
  51.  * <?php
  52.  * // $feed is an ezcFeed object
  53.  * if ( isset( $feed->iTunes ) )
  54.  * {
  55.  *     $iTunes = $feed->iTunes;
  56.  *     if ( isset( $iTunes->category ) )
  57.  *     {
  58.  *         foreach ( $iTunes->category as $category )
  59.  *         {
  60.  *             echo $category->term;
  61.  *             if ( isset( $category->category ) )
  62.  *             {
  63.  *                 foreach ( $category->category as $subCategory )
  64.  *                 {
  65.  *                     echo $subCategory->term;
  66.  *                 }
  67.  *             }
  68.  *         }
  69.  *     }
  70.  * }
  71.  * ?>
  72.  * </code>
  73.  *
  74.  * @property ezcFeedPersonElement $author 
  75.  *                                 The author of a resource. Can appear at both
  76.  *                                 feed-level and item-level.
  77.  * @property ezcFeedTextElement $block 
  78.  *                               Prevents a feed or a feed item to appear. Can appear
  79.  *                               at both feed-level and item-level. Valid values are 'yes'
  80.  *                               and 'no', default 'no'.
  81.  * @property array(ezcFeedCategoryElement) $category 
  82.  *                                          Categories for a feed. Can appear at feed-level only.
  83.  *                                          Multiple categories can be specified, and categories
  84.  *                                          can have sub-categories. The ampersands (&) in categories
  85.  *                                          must be escaped to &amp;.
  86.  *                                          {@link http://www.apple.com/itunes/store/podcaststechspecs.html#categories Valid iTunes categories}
  87.  * @property ezcFeedTextElement $duration 
  88.  *                               The duration of a feed item. Can appear at item-level
  89.  *                               only. Can be specified as HH:MM:SS, H:MM:SS, MM:SS,
  90.  *                               M:SS or S (H = hours, M = minutes, S = seconds).
  91.  * @property ezcFeedTextElement $explicit 
  92.  *                               Specifies if a feed or feed-item contains explicit
  93.  *                               content. Can appear at both feed-level and item-level.
  94.  *                               Valid values are 'clean', 'no' and 'yes', default 'no'.
  95.  * @property ezcFeedImageElement $image 
  96.  *                                A link to an image for the feed. Can appear at both
  97.  *                                feed-level and item-level only. The
  98.  *                                {@link http://www.apple.com/itunes/store/podcaststechspecs.html iTunes specifications}
  99.  *                                says that image is supported at feed-level only, but there
  100.  *                                are many podcasts using image at item-level also, and there
  101.  *                                are software applications supporting image at item-level too.
  102.  *                                Use image at item-level at your own risk, as some software
  103.  *                                applications might not support it. The Feed component supports
  104.  *                                parsing and generating feeds with image at both feed-level and item-level.
  105.  * @property ezcFeedTextElement $keywords 
  106.  *                               A list of keywords for a feed or feed item. Can appear
  107.  *                               at both feed-level and item-level. The keywords should
  108.  *                               be separated by commas.
  109.  * @property ezcFeedLinkElement $newfeedurl 
  110.  *                               A new URL for the feed. Can appear at feed-level only. In
  111.  *                               XML it will appear as 'new-feed-url'.
  112.  * @property ezcFeedPersonElement $owner 
  113.  *                                 The owner of the feed. Can appear at feed-level only.
  114.  * @property ezcFeedTextElement $subtitle 
  115.  *                               Short description of a feed or feed item. Can appear
  116.  *                               at both feed-level and item-level.
  117.  * @property ezcFeedTextElement $summary 
  118.  *                               Longer description of a feed or feed item. Can appear
  119.  *                               at both feed-level and item-level.
  120.  *
  121.  * @package Feed
  122.  * @version //autogentag//
  123.  */
  124. {
  125.     /**
  126.      * Constructs a new ezcFeedITunesModule object.
  127.      *
  128.      * @param string $level The level of the data container ('feed' or 'item')
  129.      */
  130.     public function __construct$level 'feed' )
  131.     {
  132.         parent::__construct$level );
  133.     }
  134.  
  135.     /**
  136.      * Sets the property $name to $value.
  137.      *
  138.      * @throws ezcBasePropertyNotFoundException
  139.      *          if the property $name is not defined
  140.      *
  141.      * @param string $name The property name
  142.      * @param mixed $value The property value
  143.      * @ignore
  144.      */
  145.     public function __set$name$value )
  146.     {
  147.         if $this->isElementAllowed$name ) )
  148.         {
  149.             switch $name )
  150.             {
  151.                 case 'category':
  152.                     $node $this->add$name );
  153.                     $node->term $value;
  154.                     break;
  155.  
  156.                 case 'date':
  157.                     $node $this->add$name );
  158.                     $node->date $value;
  159.                     break;
  160.  
  161.                 case 'newfeedurl':
  162.                     $node $this->add$name );
  163.                     $node->href $value;
  164.                     break;
  165.  
  166.                 case 'author':
  167.                 case 'owner':
  168.                     $node $this->add$name );
  169.                     $node->name $value;
  170.                     break;
  171.  
  172.                 default:
  173.                     $node $this->add$name );
  174.                     $node->text $value;
  175.                     break;
  176.             }
  177.         }
  178.         else
  179.         {
  180.             parent::__set$name$value );
  181.         }
  182.     }
  183.  
  184.     /**
  185.      * Returns the value of property $name.
  186.      *
  187.      * @throws ezcBasePropertyNotFoundException
  188.      *          if the property $name is not defined
  189.      *
  190.      * @param string $name The property name
  191.      * @return mixed 
  192.      * @ignore
  193.      */
  194.     public function __get$name )
  195.     {
  196.         if $this->isElementAllowed$name ) )
  197.         {
  198.             return $this->properties[$name];
  199.         }
  200.         else
  201.         {
  202.             return parent::__get$name );
  203.         }
  204.     }
  205.  
  206.     /**
  207.      * Returns if the property $name is set.
  208.      *
  209.      * @param string $name The property name
  210.      * @return bool 
  211.      * @ignore
  212.      */
  213.     public function __isset$name )
  214.     {
  215.         if $this->isElementAllowed$name ) )
  216.         {
  217.             return isset$this->properties[$name);
  218.         }
  219.         else
  220.         {
  221.             return parent::__isset$name );
  222.         }
  223.     }
  224.  
  225.     /**
  226.      * Adds the module elements to the $xml XML document, in the container $root.
  227.      *
  228.      * @param DOMDocument $xml The XML document in which to add the module elements
  229.      * @param DOMNode $root The parent node which will contain the module elements
  230.      */
  231.     public function generateDOMDocument $xmlDOMNode $root )
  232.     {
  233.         switch $this->level )
  234.         {
  235.             case 'feed':
  236.                 $elements array'author''block''category',
  237.                                    'explicit''image''keywords',
  238.                                    'newfeedurl''owner''subtitle',
  239.                                    'summary' );
  240.                 break;
  241.  
  242.             case 'item':
  243.                 $elements array'author''block''duration',
  244.                                    'explicit''image''keywords',
  245.                                    'subtitle''summary' );
  246.                 break;
  247.         }
  248.  
  249.         foreach $elements as $element )
  250.         {
  251.             if isset$this->$element ) )
  252.             {
  253.                 $values $this->$element;
  254.  
  255.                 switch $element )
  256.                 {
  257.                     case 'category':
  258.                         foreach $this->category as $values )
  259.                         {
  260.                             $elementTag $xml->createElement$this->getNamespacePrefix(':' $element );
  261.                             $root->appendChild$elementTag );
  262.  
  263.                             // generate sub-categories
  264.                             if isset$values->category ) )
  265.                             {
  266.                                 $subCategory $values->category;
  267.                                 $subTag $xml->createElement$this->getNamespacePrefix(':' 'category' );
  268.                                 $this->addAttribute$xml$subTag'text'$subCategory->term );
  269.                                 $elementTag->appendChild$subTag );
  270.                             }
  271.  
  272.                             if isset$values->term ) )
  273.                             {
  274.                                 $this->addAttribute$xml$elementTag'text'$values->term );
  275.                             }
  276.                         }
  277.                         break;
  278.  
  279.                     case 'image':
  280.                         $elementTag $xml->createElement$this->getNamespacePrefix(':' $element );
  281.                         $root->appendChild$elementTag );
  282.  
  283.                         if isset$values->link ) )
  284.                         {
  285.                             $this->addAttribute$xml$elementTag'href'$values->link );
  286.                         }
  287.                         break;
  288.  
  289.                     case 'owner':
  290.                         $elementTag $xml->createElement$this->getNamespacePrefix(':' $element );
  291.                         $root->appendChild$elementTag );
  292.  
  293.                         foreach array'email''name' as $subElement )
  294.                         {
  295.                             if isset$values->$subElement ) )
  296.                             {
  297.                                 $tag $xml->createElement$this->getNamespacePrefix(':' $subElement );
  298.                                 $val $xml->createTextNode$values->$subElement );
  299.                                 $tag->appendChild$val );
  300.                                 $elementTag->appendChild$tag );
  301.                             }
  302.                         }
  303.  
  304.                         break;
  305.  
  306.                     case 'newfeedurl':
  307.                         $elementTag $xml->createElement$this->getNamespacePrefix(':' 'new-feed-url' );
  308.                         $root->appendChild$elementTag );
  309.  
  310.                         $elementTag->nodeValue $values->href;
  311.                         break;
  312.  
  313.                     default:
  314.                         $elementTag $xml->createElement$this->getNamespacePrefix(':' $element );
  315.                         $root->appendChild$elementTag );
  316.  
  317.                         $elementTag->nodeValue $values->__toString();
  318.                         break;
  319.                 }
  320.             }
  321.         }
  322.     }
  323.  
  324.     /**
  325.      * Parses the XML element $node and creates a feed element in the current
  326.      * module with name $name.
  327.      *
  328.      * @param string $name The name of the element belonging to the module
  329.      * @param DOMElement $node The XML child from which to take the values for $name
  330.      */
  331.     public function parse$nameDOMElement $node )
  332.     {
  333.         if $name === 'new-feed-url' )
  334.         {
  335.             $name 'newfeedurl';
  336.         }
  337.  
  338.         if $this->isElementAllowed$name ) )
  339.         {
  340.             $element $this->add$name );
  341.             $value $node->textContent;
  342.  
  343.             switch $name )
  344.             {
  345.                 case 'category':
  346.                     foreach $node->childNodes as $subNode )
  347.                     {
  348.                         if get_class$subNode === 'DOMElement' )
  349.                         {
  350.                             $subCategory $element->add$name );
  351.  
  352.                             if $subNode->hasAttribute'text' ) )
  353.                             {
  354.                                 $subCategory->term $subNode->getAttribute'text' );
  355.                             }
  356.                         }
  357.                     }
  358.  
  359.                     if $node->hasAttribute'text' ) )
  360.                     {
  361.                         $element->term $node->getAttribute'text' );
  362.                     }
  363.                     break;
  364.  
  365.                 case 'image':
  366.                     // no textContent in $node
  367.                     if $node->hasAttribute'href' ) )
  368.                     {
  369.                         $element->link $node->getAttribute'href' );
  370.                     }
  371.                     break;
  372.  
  373.                 case 'newfeedurl':
  374.                     $element->href $node->textContent;
  375.                     break;
  376.  
  377.                 case 'owner':
  378.                     $namespace self::getNamespace();
  379.  
  380.                     $nodes $node->getElementsByTagNameNS$namespace'email' );
  381.                     if $nodes->length >= )
  382.                     {
  383.                         $element->email $nodes->item)->textContent;
  384.                     }
  385.  
  386.                     $nodes $node->getElementsByTagNameNS$namespace'name' );
  387.                     if $nodes->length >= )
  388.                     {
  389.                         $element->name $nodes->item)->textContent;
  390.                     }
  391.                     break;
  392.  
  393.                 case 'author':
  394.                     $element->name $value;
  395.                     break;
  396.  
  397.                 default:
  398.                     $element->text $value;
  399.             }
  400.         }
  401.     }
  402.  
  403.     /**
  404.      * Returns true if the element $name is allowed in the current module at the
  405.      * current level (feed or item), and false otherwise.
  406.      *
  407.      * @param string $name The element name to check if allowed in the current module and level (feed or item)
  408.      * @return bool 
  409.      */
  410.     public function isElementAllowed$name )
  411.     {
  412.         switch $this->level )
  413.         {
  414.             case 'feed':
  415.                 if in_array$namearray'author''block''category',
  416.                                              'explicit''image''keywords',
  417.                                              'newfeedurl''owner''subtitle',
  418.                                              'summary' ) ) )
  419.                 {
  420.                     return true;
  421.                 }
  422.                 break;
  423.  
  424.             case 'item':
  425.                 if in_array$namearray'author''block''duration',
  426.                                              'explicit''image''keywords',
  427.                                              'subtitle''summary' ) ) )
  428.                 {
  429.                     return true;
  430.                 }
  431.                 break;
  432.         }
  433.         return false;
  434.     }
  435.  
  436.     /**
  437.      * Adds a new ezcFeedElement element with name $name to this module and
  438.      * returns it.
  439.      *
  440.      * @throws ezcFeedUnsupportedElementException
  441.      *          if trying to add an element which is not supported.
  442.      *
  443.      * @param string $name The element name
  444.      * @return ezcFeedElement 
  445.      */
  446.     public function add$name )
  447.     {
  448.         if $this->isElementAllowed$name ) )
  449.         {
  450.             switch $name )
  451.             {
  452.                 case 'category':
  453.                     $node new ezcFeedCategoryElement();
  454.                     $this->properties[$name][$node;
  455.                     break;
  456.  
  457.                 case 'newfeedurl':
  458.                     $node new ezcFeedLinkElement();
  459.                     $this->properties[$name$node;
  460.                     break;
  461.  
  462.                 case 'owner':
  463.                 case 'author':
  464.                     $node new ezcFeedPersonElement();
  465.                     $this->properties[$name$node;
  466.                     break;
  467.  
  468.                 case 'image':
  469.                     $node new ezcFeedImageElement();
  470.                     $this->properties[$name$node;
  471.                     break;
  472.  
  473.                 default:
  474.                     $node new ezcFeedTextElement();
  475.                     $this->properties[$name$node;
  476.                     break;
  477.             }
  478.             return $node;
  479.         }
  480.         else
  481.         {
  482.             throw new ezcFeedUnsupportedElementException$name );
  483.         }
  484.     }
  485.  
  486.     /**
  487.      * Returns the module name ('iTunes').
  488.      *
  489.      * @return string 
  490.      */
  491.     public static function getModuleName()
  492.     {
  493.         return 'iTunes';
  494.     }
  495.  
  496.     /**
  497.      * Returns the namespace for this module ('http://www.itunes.com/dtds/podcast-1.0.dtd').
  498.      *
  499.      * @return string 
  500.      */
  501.     public static function getNamespace()
  502.     {
  503.         return 'http://www.itunes.com/dtds/podcast-1.0.dtd';
  504.     }
  505.  
  506.     /**
  507.      * Returns the namespace prefix for this module ('itunes').
  508.      *
  509.      * @return string 
  510.      */
  511.     public static function getNamespacePrefix()
  512.     {
  513.         return 'itunes';
  514.     }
  515. }
  516. ?>
Documentation generated by phpDocumentor 1.4.3