## 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. */
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. class ezcFeedITunesModule extends ezcFeedModule
125. {
126. /**
127. * Constructs a new ezcFeedITunesModule object.
128. *
129. * @param string $level The level of the data container ('feed' or 'item')
130. */
131. public function __construct ( $level = 'feed' )
132. {
133. parent:: __construct ( $level );
134. }
136. /**
137. * Sets the property $name to $value.
138. *
139. * @throws ezcBasePropertyNotFoundException
140. * if the property $name is not defined
141. *
142. * @param string $name The property name
143. * @param mixed $value The property value
144. * @ignore
145. */
146. public function __set( $name, $value )
147. {
148. if ( $this-> isElementAllowed ( $name ) )
149. {
150. switch ( $name )
151. {
152. case 'category':
153. $node = $this-> add ( $name );
154. $node->term = $value;
155. break;
157. case 'date':
158. $node = $this-> add ( $name );
159. $node->date = $value;
160. break;
162. case 'newfeedurl':
163. $node = $this-> add ( $name );
164. $node->href = $value;
165. break;
167. case 'author':
168. case 'owner':
169. $node = $this-> add ( $name );
170. $node->name = $value;
171. break;
173. default:
174. $node = $this-> add ( $name );
175. $node->text = $value;
176. break;
177. }
178. }
179. else
180. {
181. parent::__set( $name, $value );
182. }
183. }
185. /**
186. * Returns the value of property $name.
187. *
188. * @throws ezcBasePropertyNotFoundException
189. * if the property $name is not defined
190. *
191. * @param string $name The property name
192. * @return mixed
193. * @ignore
194. */
195. public function __get( $name )
196. {
197. if ( $this-> isElementAllowed ( $name ) )
198. {
199. return $this-> properties [$name];
200. }
201. else
202. {
203. return parent::__get( $name );
204. }
205. }
207. /**
208. * Returns if the property $name is set.
209. *
210. * @param string $name The property name
211. * @return bool
212. * @ignore
213. */
214. public function __isset( $name )
215. {
216. if ( $this-> isElementAllowed ( $name ) )
217. {
218. return isset( $this-> properties [$name] );
219. }
220. else
221. {
222. return parent::__isset( $name );
223. }
224. }
226. /**
227. * Adds the module elements to the $xml XML document, in the container $root.
228. *
229. * @param DOMDocument $xml The XML document in which to add the module elements
230. * @param DOMNode $root The parent node which will contain the module elements
231. */
232. public function generate ( DOMDocument $xml, DOMNode $root )
233. {
234. switch ( $this-> level )
235. {
236. case 'feed':
237. $elements = array( 'author', 'block', 'category',
238. 'explicit', 'image', 'keywords',
239. 'newfeedurl', 'owner', 'subtitle',
240. 'summary' );
241. break;
243. case 'item':
244. $elements = array( 'author', 'block', 'duration',
245. 'explicit', 'image', 'keywords',
246. 'subtitle', 'summary' );
247. break;
248. }
250. foreach ( $elements as $element )
251. {
252. if ( isset( $this->$element ) )
253. {
254. $values = $this->$element;
256. switch ( $element )
257. {
258. case 'category':
259. foreach ( $this->category as $values )
260. {
261. $elementTag = $xml->createElement( $this-> getNamespacePrefix () . ':' . $element );
262. $root->appendChild( $elementTag );
264. // generate sub-categories
265. if ( isset( $values->category ) )
266. {
267. $subCategory = $values->category;
268. $subTag = $xml->createElement( $this-> getNamespacePrefix () . ':' . 'category' );
269. $this->addAttribute( $xml, $subTag, 'text', $subCategory->term );
270. $elementTag->appendChild( $subTag );
271. }
273. if ( isset( $values->term ) )
274. {
275. $this->addAttribute( $xml, $elementTag, 'text', $values->term );
276. }
277. }
278. break;
280. case 'image':
281. $elementTag = $xml->createElement( $this-> getNamespacePrefix () . ':' . $element );
282. $root->appendChild( $elementTag );
284. if ( isset( $values->link ) )
285. {
286. $this->addAttribute( $xml, $elementTag, 'href', $values->link );
287. }
288. break;
290. case 'owner':
291. $elementTag = $xml->createElement( $this-> getNamespacePrefix () . ':' . $element );
292. $root->appendChild( $elementTag );
294. foreach ( array( 'email', 'name' ) as $subElement )
295. {
296. if ( isset( $values->$subElement ) )
297. {
298. $tag = $xml->createElement( $this-> getNamespacePrefix () . ':' . $subElement );
299. $val = $xml->createTextNode( $values->$subElement );
300. $tag->appendChild( $val );
301. $elementTag->appendChild( $tag );
302. }
303. }
305. break;
307. case 'newfeedurl':
308. $elementTag = $xml->createElement( $this-> getNamespacePrefix () . ':' . 'new-feed-url' );
309. $root->appendChild( $elementTag );
311. $elementTag->nodeValue = $values->href;
312. break;
314. default:
315. $elementTag = $xml->createElement( $this-> getNamespacePrefix () . ':' . $element );
316. $root->appendChild( $elementTag );
318. $elementTag->nodeValue = $values->__toString();
319. break;
320. }
321. }
322. }
323. }
325. /**
326. * Parses the XML element $node and creates a feed element in the current
327. * module with name $name.
328. *
329. * @param string $name The name of the element belonging to the module
330. * @param DOMElement $node The XML child from which to take the values for $name
331. */
332. public function parse ( $name, DOMElement $node )
333. {
334. if ( $name === 'new-feed-url' )
335. {
336. $name = 'newfeedurl';
337. }
339. if ( $this-> isElementAllowed ( $name ) )
340. {
341. $element = $this-> add ( $name );
342. $value = $node->textContent;
344. switch ( $name )
345. {
346. case 'category':
347. foreach ( $node->childNodes as $subNode )
348. {
349. if ( get_class ( $subNode ) === 'DOMElement' )
350. {
351. $subCategory = $element->add( $name );
353. if ( $subNode->hasAttribute( 'text' ) )
354. {
355. $subCategory->term = $subNode->getAttribute( 'text' );
356. }
357. }
358. }
360. if ( $node->hasAttribute( 'text' ) )
361. {
362. $element->term = $node->getAttribute( 'text' );
363. }
364. break;
366. case 'image':
367. // no textContent in $node
368. if ( $node->hasAttribute( 'href' ) )
369. {
370. $element->link = $node->getAttribute( 'href' );
371. }
372. break;
374. case 'newfeedurl':
375. $element->href = $node->textContent;
376. break;
378. case 'owner':
379. $namespace = self::getNamespace();
381. $nodes = $node->getElementsByTagNameNS( $namespace, 'email' );
382. if ( $nodes->length >= 1 )
383. {
384. $element->email = $nodes->item( 0 )->textContent;
385. }
387. $nodes = $node->getElementsByTagNameNS( $namespace, 'name' );
388. if ( $nodes->length >= 1 )
389. {
390. $element->name = $nodes->item( 0 )->textContent;
391. }
392. break;
394. case 'author':
395. $element->name = $value;
396. break;
398. default:
399. $element->text = $value;
400. }
401. }
402. }
404. /**
405. * Returns true if the element $name is allowed in the current module at the
406. * current level (feed or item), and false otherwise.
407. *
408. * @param string $name The element name to check if allowed in the current module and level (feed or item)
409. * @return bool
410. */
411. public function isElementAllowed ( $name )
412. {
413. switch ( $this-> level )
414. {
415. case 'feed':
416. if ( in_array ( $name, array( 'author', 'block', 'category',
417. 'explicit', 'image', 'keywords',
418. 'newfeedurl', 'owner', 'subtitle',
419. 'summary' ) ) )
420. {
421. return true;
422. }
423. break;
425. case 'item':
426. if ( in_array ( $name, array( 'author', 'block', 'duration',
427. 'explicit', 'image', 'keywords',
428. 'subtitle', 'summary' ) ) )
429. {
430. return true;
431. }
432. break;
433. }
434. return false;
435. }
437. /**
438. * Adds a new ezcFeedElement element with name $name to this module and
439. * returns it.
440. *
441. * @throws ezcFeedUnsupportedElementException
442. * if trying to add an element which is not supported.
443. *
444. * @param string $name The element name
445. * @return ezcFeedElement
446. */
447. public function add ( $name )
448. {
449. if ( $this-> isElementAllowed ( $name ) )
450. {
451. switch ( $name )
452. {
453. case 'category':
454. $node = new ezcFeedCategoryElement ();
455. $this-> properties [$name][] = $node;
456. break;
458. case 'newfeedurl':
459. $node = new ezcFeedLinkElement ();
460. $this-> properties [$name] = $node;
461. break;
463. case 'owner':
464. case 'author':
465. $node = new ezcFeedPersonElement ();
466. $this-> properties [$name] = $node;
467. break;
469. case 'image':
470. $node = new ezcFeedImageElement ();
471. $this-> properties [$name] = $node;
472. break;
474. default:
475. $node = new ezcFeedTextElement ();
476. $this-> properties [$name] = $node;
477. break;
478. }
479. return $node;
480. }
481. else
482. {
483. throw new ezcFeedUnsupportedElementException ( $name );
484. }
485. }
487. /**
488. * Returns the module name ('iTunes').
489. *
490. * @return string
491. */
492. public static function getModuleName ()
493. {
494. return 'iTunes';
495. }
497. /**
498. * Returns the namespace for this module ('http://www.itunes.com/dtds/podcast-1.0.dtd').
499. *
500. * @return string
501. */
502. public static function getNamespace ()
503. {
504. return 'http://www.itunes.com/dtds/podcast-1.0.dtd';
505. }
507. /**
508. * Returns the namespace prefix for this module ('itunes').
509. *
510. * @return string
511. */
512. public static function getNamespacePrefix ()
513. {
514. return 'itunes';
515. }
516. }
517. ?>

Documentation generated by phpDocumentor 1.4.3