Feed specifications
~~~~~~~~~~~~~~~~~~~

This document lists the various feed types supported by the Feed component,
general information about each feed type, and the related specifications
documents and RFCs.

.. contents:: Table of Contents
   :depth: 2


========
Overview
========

Feeds equivalence
=================

Feed elements
-------------

+----------------------------+-------------------------+----------------------------+---------------------------+
|         ezcFeed            |           ATOM          |            RSS1            |           RSS2            |
+============================+=========================+============================+===========================+
| |ezcFeed-author|_ *        | |ATOM-author|_ !*       | x                          | |RSS2-managingEditor|_ ?  |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-category|_ *      | |ATOM-category|_ ?*     | x                          | |RSS2-category|_ ?*       |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-cloud|_           | x                       | x                          | |RSS2-cloud|_ ?           |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-contributor|_ *   | |ATOM-contributor|_ ?*  | x                          | x                         |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-copyright|_       | |ATOM-rights|_ ?        | x                          | |RSS2-copyright|_ ?       |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-description|_     | |ATOM-subtitle|_ ?      | |RSS1-description|_ !      | |RSS2-description|_ !     |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-docs|_            | x                       | x                          | |RSS2-docs|_ ?            |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-generator|_       | |ATOM-generator|_ ?     | x                          | |RSS2-generator|_ ?       |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-icon|_            | |ATOM-icon|_ ?          | x                          | x                         |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-id|_              | |ATOM-id|_ !            | |RSS1-about|_ !            | |RSS2-id|_ ?              |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-image|_           | |ATOM-logo|_ ?          | |RSS1-image|_ ?            | |RSS2-image|_ ?           |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-item|_ *          | |ATOM-entry|_ ?*        | |RSS1-item|_ !*            | |RSS2-item|_ !*           |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-language|_        | |ATOM-language|_ ?      | |RSS1-language|_ ?         | |RSS2-language|_ ?        |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-link|_ *          | |ATOM-link|_ !*         | |RSS1-link|_ !             | |RSS2-link|_ !            |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-published|_       | x                       | x                          | |RSS2-pubDate|_ ?         |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-rating|_          | x                       | x                          | |RSS2-rating|_ ?          |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-skipDays|_        | x                       | x                          | |RSS2-skipDays|_ ?        |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-skipHours|_       | x                       | x                          | |RSS2-skipHours|_ ?       |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-textInput|_       | x                       | |RSS1-textinput|_ ?        | |RSS2-textInput|_ ?       |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-title|_           | |ATOM-title|_ !         | |RSS1-title|_ !            | |RSS2-title|_ !           |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-ttl|_             | x                       | x                          | |RSS2-ttl|_ ?             |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-updated|_         | |ATOM-updated|_ !       | x                          | |RSS2-lastBuildDate|_ ?   |
+----------------------------+-------------------------+----------------------------+---------------------------+
| |ezcFeed-webMaster|_       | x                       | x                          | |RSS2-webMaster|_ ?       |
+----------------------------+-------------------------+----------------------------+---------------------------+

| ! = required
| ? = optional
| * = can appear multiple times
| x = no equivalence

In order to generate all 3 feed types from the same ezcFeed data, these
elements must be added to an ezcFeed object:

- |ezcFeed-author|_
- |ezcFeed-description|_
- |ezcFeed-id|_
- at least one |ezcFeed-item|_ with all required elements
- |ezcFeed-link|_
- |ezcFeed-title|_
- |ezcFeed-updated|_


Item elements
-------------

+---------------------------------+-------------------------------+------------------------------+------------------------------+
|           ezcFeed               |            ATOM               |             RSS1             |            RSS2              |
+=================================+===============================+==============================+==============================+
| |ezcFeed-item-author|_ *        | |ATOM-entry-author|_ !*       | x                            | |RSS2-item-author|_ ?        |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-category|_ *      | |ATOM-entry-category|_ ?*     | x                            | |RSS2-item-category|_ ?*     |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-comments|_        | x                             | x                            | |RSS2-item-comments|_ ?      |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-content|_         | |ATOM-entry-content|_ ?       | x                            | x                            |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-contributor|_ *   | |ATOM-entry-contributor|_ ?*  | x                            | x                            |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-copyright|_       | |ATOM-entry-rights|_ ?        | x                            | x                            |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-description|_     | |ATOM-entry-summary|_ !       | |RSS1-item-description|_ !   | |RSS2-item-description|_ !   |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-enclosure|_ *     | |ATOM-entry-link|_ ?*         | x                            | |RSS2-item-enclosure|_ ?     |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-id|_              | |ATOM-entry-id|_ !            | |RSS1-item-about|_ !         | |RSS2-item-guid|_ ?          |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-language|_ ?      | |ATOM-entry-language|_ ?      | |RSS1-item-language|_ ?      | |RSS2-item-language|_ ?      |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-link|_ *          | |ATOM-entry-link|_ !*         | |RSS1-item-link|_ !          | |RSS2-item-link|_ !          |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-published|_       | |ATOM-entry-published|_ ?     | x                            | |RSS2-item-pubDate|_ ?       |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-source|_          | |ATOM-entry-source|_ ?        | x                            | |RSS2-item-source|_ ?        |
+---------------------------------+-------------------------------+------------------------------+------------------------------+
| |ezcFeed-item-title|_           | |ATOM-entry-title|_ !         | |RSS1-item-title|_ !         | |RSS2-item-title|_ !         |
+---------------------------------+-------------------------------+------------------------------++-----------------------------+
| |ezcFeed-item-updated|_         | |ATOM-entry-updated|_ !       | x                            | x                            |
+---------------------------------+-------------------------------+------------------------------+------------------------------+

| ! = required
| ? = optional
| * = can appear multiple times
| x = no equivalence

The language element for an item in any feed type is rendered in XML as an
*xml:lang* attribute for the item or entry XML element. Parsing an XML file
which contains *xml:lang* attributes for the item/entry XML elements will
result in the language attribute to be filled with the contents of the
*xml:lang* attribute.

In order to generate all 3 feed types from the same ezcFeed data, these
elements must be added to an ezcFeedEntryElement object:

- |ezcFeed-item-author|_
- |ezcFeed-item-description|_
- |ezcFeed-item-id|_
- |ezcFeed-item-link|_
- |ezcFeed-item-title|_
- |ezcFeed-item-updated|_

This is a minimal script to be able to generate all 3 feed types from the same
ezcFeed data::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed();

    $author = $feed->add( 'author' );
    $author->name = "Indiana Jones";
    $author->email = "indy@example.com";

    $feed->description = "This feed shows Indiana Jones movie releases";
    $feed->id = "http://indy.example.com/";

    $link = $feed->add( 'link' );
    $link->href = "http://indy.example.com/";

    $feed->title = "Indiana Jones movie releases";
    $feed->updated = time();

    // add a feed item
    $item = $feed->add( 'item' );

    $author = $item->add( 'author' );
    $author->name = "Indiana Jones";
    $author->email = "indy@example.com";

    $item->description = "Indy meets ****** and has a hell of an adventure";
    $item->id = "http://indy.example.com/4";

    $link = $item->add( 'link' );
    $link->href = "http://indy.example.com/4";

    $item->title = "Indiana Jones and the Kingdom of the Crystal Skull";
    $item->updated = time();

    $atom = $feed->generate( 'atom' );
    $rss1 = $feed->generate( 'rss1 );
    $rss2 = $feed->generate( 'rss2' );
    ?>


ezcFeed
=======

Feed elements
-------------

ezcFeed-author
``````````````

Type: array(ezcFeedPersonElement).

One author of the feed.

Required in `ATOM`_: one author must be present at feed-level if there is one
entry which does not have an author. Optional in `RSS2`_ (recommended). Ignored
for `RSS1`_ feeds.

Multiple authors can appear in `ATOM`_ (not recommended). Can appear only once
in `RSS2`_ feeds.

`ATOM`_ has required elements: *name*. Optional elements: *uri* (ignored in
`RSS2`_) and *email*.

In `RSS2`_ the generated XML element value will be ``email (name)``.

Create example::

    <?php
    // $feed is an ezcFeed object
    $author = $feed->add( 'author' );
    $author->name = 'Guybrush Threepwood';
    $author->email = 'guybrush@monkey-island.com';
    $author->uri = 'http://example.com/~guybrush'; // ATOM only
    ?>

The resulting ATOM XML element will be::

  <author>
    <name>Guybrush Threepwood</name>
    <email>guybrush@monkey-island.com</email>
    <uri>http://example.com/~guybrush</uri>
  </author>

The resulting RSS2 XML element will be::

  <managingEditor>guybrush@monkey-island.com (Guybrush Threepwood)</managingEditor>

Parse example::

    <?php
    $authors = array();

    // $feed is an ezcFeed object
    if ( isset( $feed->author ) )
    {
        foreach ( $feed->author as $author )
        {
            $authors[] = array(
              'name' => isset( $author->name ) ? $author->name : null,
              'uri' => isset( $author->uri ) ? $author->uri : null, // ATOM only
              'email' => isset( $author->email ) ? $author->email : null // ATOM only
              );
        }
    }
    ?>

Equivalents: `ezcFeed-author`_, `ATOM-author`_, RSS1-none,
`RSS2-managingEditor`_.


ezcFeed-category
````````````````

Type: array(ezcFeedCategoryElement).

A category for the feed.

Optional. Only `ATOM`_ and `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ feeds.

Multiple categories can appear in `ATOM`_ and `RSS2`_ feeds.

`ATOM`_ has one required attribute: *term*. It also has 2 optional attributes:
*scheme* (equivalent to `RSS2`_ *domain* attribute), *label*. The *label*
attribute will be ignored for `RSS2`_ feeds.

`RSS2`_ has one optional attribute: *domain* (equivalent to `ATOM`_ *scheme*
attribute).

Create example::

    <?php
    // $feed is an ezcFeed object
    $category = $feed->add( 'category' );
    $category->term = 'holiday';
    $category->scheme = 'http://example.com/categories/holiday'; // scheme = RSS2 domain
    $category->label = 'Holiday'; // ATOM only
    ?>

Parse example::

    <?php
    $categories = array();

    // $feed is an ezcFeed object
    if ( isset( $feed->category ) )
    {
        foreach ( $feed->category as $category )
        {
            $categories[] = array(
              'term' => isset( $category->term ) ? $category->term : null,
              'scheme' => isset( $category->scheme ) ? $category->scheme : null,
                  // scheme = RSS2 domain
              'label' => isset( $category->label ) ? $category->label : null // ATOM only
              );
        }
    }
    ?>

Equivalents: `ezcFeed-category`_, `ATOM-category`_, RSS1-none,
`RSS2-category`_.


ezcFeed-cloud
`````````````

Type: ezcFeedCloudElement.

Allows processes to register with a cloud to be notified of updates to the
channel, implementing a lightweight publish-subscribe protocol for RSS feeds.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_.

Can appear only once.

Has the required attributes: *domain*, *port*, *path*, *registerProcedure*,
*protocol*.

Create example::

    <?php
    // $feed is an ezcFeed object
    $cloud = $feed->add( 'cloud' );
    $cloud->domain = 'rpc.sys.com';
    $cloud->port = 80;
    $cloud->path = '/RPC2';
    $cloud->registerProcedure = 'myCloud.rssPleaseNotify';
    $cloud->protocol = 'xml-rpc';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->cloud ) )
    {
        $cloud = $feed->cloud;
        $domain = isset( $cloud->domain ) ? $cloud->domain : null;
        $port = isset( $cloud->port ) ? $cloud->port : null;
        $path = isset( $cloud->path ) ? $cloud->path : null;
        $procedure = isset( $cloud->registerProcedure ) ? $cloud->registerProcedure : null;
        $protocol = isset( $cloud->protocol ) ? $cloud->protocol : null;
    }
    ?>

Equivalents: `ezcFeed-cloud`_, ATOM-none, RSS1-none, `RSS2-cloud`_.


ezcFeed-contributor
```````````````````

Type: array(ezcFeedPersonElement).

One contributor of the feed.

Optional (not recommended). Only `ATOM`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `RSS2`_ feeds.

Multiple contributors can appear.

Required elements: *name*. Optional elements: *uri*, *email*.

Create example::

    <?php
    // $feed is an ezcFeed object
    $contributor = $feed->add( 'contributor' );
    $contributor->name = 'Guybrush Threepwood';
    $contributor->email = 'guybrush@monkey-island.com';
    $contributor->uri = 'http://example.com/~guybrush';
    ?>

Parse example::

    <?php
    $contributors = array();

    // $feed is an ezcFeed object
    if ( isset( $feed->contributor ) )
    {
        foreach ( $feed->contributor as $contributor )
        {
            $contributors[] = array(
              'name' => isset( $contributor->name ) ? $contributor->name : null,
              'uri' => isset( $contributor->uri ) ? $contributor->uri : null,
              'email' => isset( $contributor->email ) ? $contributor->email : null
              );
        }
    }
    ?>

Equivalents: `ezcFeed-contributor`_, `ATOM-contributor`_, RSS1-none,
RSS2-none.


ezcFeed-copyright
`````````````````

Type: ezcFeedTextElement.

Copyright information for the feed.

Optional. Only `ATOM`_ and `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ feeds.

Can appear only once.

`ATOM`_ has an optional attribute *type* with possible values ``text``
(default), ``html``, ``xhtml``. This attribute will be ignored for `RSS1`_ and
`RSS2`_ feeds.

`ATOM`_ has an optional attribute *xml:lang* which specifies the language of
the text. A list of allowed languages can be found here:
`RSS language codes`_. This attribute is accessed through ezcFeed as
*language*. This attribute will be ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->copyright = 'Copyright <company name>';
    $feed->copyright->type = 'text'; // ATOM only, ignored in RSS1 and RSS2
    $feed->copyright->language = 'de'; // ATOM only, ignored in RSS1 and RSS2
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->copyright ) )
    {
        $copyrightElement = $feed->copyright;
        $copyright = $copyrightElement->text;
        $type = isset( $copyrightElement->type ) ? $copyrightElement->type : null;  // ATOM only
        $language = isset( $copyrightElement->language ) ? $copyrightElement->language : null;  // ATOM only
    }
    ?>

Equivalents: `ezcFeed-copyright`_, `ATOM-rights`_, RSS1-none,
`RSS2-copyright`_.


ezcFeed-description
```````````````````

Type: ezcFeedTextElement.

A short description of the feed.

Required.

Can appear only once.

`ATOM`_ has an optional attribute *type* with possible values ``text``
(default), ``html``, ``xhtml``. This attribute will be ignored for `RSS1`_ and
`RSS2`_ feeds.

`ATOM`_ has an optional attribute *xml:lang* which specifies the language of
the text. A list of allowed languages can be found here:
`RSS language codes`_. This attribute is accessed through ezcFeed as
*language*. This attribute will be ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->description = 'Feed description';
    $feed->description->type = 'text'; // ATOM only, ignored in RSS1 and RSS2
    $feed->description->language = 'de'; // ATOM only, ignored in RSS1 and RSS2
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->description ) )
    {
        $descriptionElement = $feed->description;
        $description = $descriptionElement->text;
        $type = isset( $descriptionElement->type ) ? $descriptionElement->type : null; // ATOM only
        $language = isset( $descriptionElement->language ) ? $descriptionElement->language : null; // ATOM only
    }
    ?>

Equivalents: `ezcFeed-description`_, `ATOM-subtitle`_, `RSS1-description`_,
`RSS2-description`_.


ezcFeed-docs
````````````

Type: ezcFeedTextElement.

An URL that points to the documentation for the format used in the feed file.

Optional. Only `RSS2`_ feeds will have this element after generating the feed.
It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->docs = 'http://www.rssboard.org/rss-specification';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $docs = isset( $feed->docs ) ? $feed->docs->__toString() : null;
    ?>

Equivalents: `ezcFeed-docs`_, ATOM-none, RSS1-none, `RSS2-docs`_.


ezcFeed-generator
`````````````````

Type: ezcFeedGeneratorElement.

Indicates the software used to generate the feed.

Optional. Only `ATOM`_ and `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ feeds.

Can appear only once.

`ATOM`_ has 2 optional attributes: *url*, *version*. These attributes are
used in `RSS2`_ to generate the string ``name version (url)``. This element
and its attributes will be filled automatically by ezcFeed when generating
the feed with the values ``eZComponents Feed``,
``http://ezcomponents.org/docs/tutorials/Feed`` and ``<version>``
respectively, where the version is the current version of the Feed component
(``dev`` for pre-alpha1).

`RSS2`_ will get this value automatically when generating the feed:
``eZ Components Feed <version> (http://ezcomponents.org/docs/tutorials/Feed)``,
where the version is the current version of the Feed component (``dev`` for
pre-alpha1)

Create example - this is automatically done by ezcFeed when calling the
**generate()** method::

    <?php
    // $feed is an ezcFeed object
    $generator = $feed->add( 'generator' );
    $generator->name = 'eZ Components Feed';
    $generator->url = 'http://ezcomponents.org/docs/tutorials/Feed';
    $generator->version = '1.0';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->generator ) )
    {
        $name = isset( $feed->generator->name ) ? $feed->generator->name : null;
        $url = isset( $feed->generator->url ) ? $feed->generator->url : null; // ATOM only
        $version = isset( $feed->generator->version ) ? $feed->generator->version : null; // ATOM only
    }
    ?>

Equivalents: `ezcFeed-generator`_, `ATOM-generator`_, RSS1-none,
`RSS2-generator`_.


ezcFeed-icon
````````````

Type: ezcFeedImageElement.

An icon for a feed, similar with ``favicon.ico`` for websites.

Optional. Only `ATOM`_ feeds will have this element after generating the
feed. It will be ignored for `RSS1`_ and `RSS2`_ feeds.

Can appear only once.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->icon = 'http://example.com/favicon.ico';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $icon = isset( $feed->icon ) ? $feed->icon->__toString : null;
    ?>

Equivalents: `ezcFeed-icon`_, `ATOM-icon`_, RSS1-none, RSS2-none.


ezcFeed-id
``````````

Type: ezcFeedIdElement.

A universally unique and permanent URI for a feed. For example, it can be an
Internet domain name.

Required. `RSS1`_ and `ATOM`_ feeds will have this element after generating
the feed. It will be rendered as an *atom:link* element in `RSS2`_ feeds
(together with the *xmlns:atom* namespace).

Can appear only once.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->id = 'ID value';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $id = isset( $feed->id ) ? $feed->id->__toString() : null;
    ?>

Equivalents: `ezcFeed-id`_, `ATOM-id`_, `RSS1-about`_, `RSS2-id`_.


ezcFeed-image
`````````````

Type: ezcFeedImageElement.

An image associated with the feed.

Optional.

Can appear only once.

`RSS1`_ has the required attribute *about*, which should have the same value
as the *url* sub-element.

`RSS1`_ and `RSS2`_ have 3 required sub-elements: *title*, *link*, *url*
(same for both feed types). These attributes will be ignored for `ATOM`_ feeds.

`RSS2`_ has 3 optional sub-elements: *width*, *height*, *description*. These
attributes will be ignored for `RSS1`_ and `ATOM`_ feeds.

Create example::

    <?php
    // $feed is an ezcFeed object
    $image = $feed->add( 'image' );
    $image->link = 'http://example.com/target_for_image_click.html';
    $image->url = 'http://example.com/image.jpg'; // RSS1 and RSS2 only
    $image->title = 'Click here to go to the link'; // RSS1 and RSS2 only
    $image->width = 100; // RSS2 only
    $image->height = 200; // RSS2 only
    $image->description = 'This image is cool'; // RSS2 only
    $image->about = 'http://example.com/image.jpg'; // RSS1 only
    ?>

Parse example (`RSS1`_ and `RSS2`_)::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->image ) )
    {
        $image = $feed->image;
        $link = isset( $image->link ) ? $image->link : null;
        $url = isset( $image->url ) ? $image->url : null; // RSS1 and RSS2 only
        $title = isset( $image->title ) ? $image->title : null; // RSS1 and RSS2 only
        $width = isset( $image->width ) ? $image->width : null; // RSS2 only
        $height = isset( $image->height ) ? $image->height : null; // RSS2 only
        $description = isset( $image->description ) ? $image->description : null; // RSS2 only
        $about = isset( $image->about ) ? $image->about : null; // RSS1 only
    }
    ?>

Equivalents: `ezcFeed-image`_, `ATOM-logo`_, `RSS1-image`_, `RSS2-image`_.


ezcFeed-item
````````````

Type: array(ezcFeedEntryElement).

Feed entry.

Required for `RSS1`_ and `RSS2`_ feeds. Optional (recommended) for `ATOM`_
feeds.

Multiple entries can appear.

Create example::

    <?php
    // $feed is an ezcFeed object
    $item = $feed->add( 'item' );

    // set $item properties, for example:
    $item->title = 'Item title';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    foreach ( $feed->item as $item )
    {
        // get $item properties, for example:
        $title = isset( $item->title ) ? $item->title->__toString() : null;
    }
    ?>

Equivalents: `ezcFeed-item`_, `ATOM-entry`_, `RSS1-item`_, `RSS2-item`_.


ezcFeed-language
````````````````

Type: ezcFeedTextElement.

The language for the feed.

Optional (recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

In `ATOM`_ you can assign the language to each element instead.

A list of allowed languages can be found here: `RSS language codes`_.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->language = 'en';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $language = isset( $feed->language ) ? $feed->language->__toString() : null;
    ?>

Equivalents: `ezcFeed-language`_, ATOM-*xml:lang* for each element, RSS1-none,
`RSS2-language`_.


ezcFeed-link
````````````

Type: array(ezcFeedLinkElement).

An URL to the HTML website corresponding to the feed.

Required for all feed types. In `ATOM`_ a link back to the feed itself must be
present (with ``rel="self"``).

Multiple links can appear in `ATOM`_ (not recommended).

Required attributes: *href*. Optional attributes for `ATOM`_: *rel* (possible
values: ``alternate`` (default), ``enclosure``, ``related``, ``self``,
``via``), *type*, *hreflang*, *title*, *length*.

A maximum of one link with ``rel="alternate"`` can appear per *type* and
*hreflang*.

These attributes will be ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $feed is an ezcFeed object
    $link = $feed->add( 'link' );
    $link->href = 'http://example.com';
    $link->rel = 'self'; // ATOM only
    $link->type = 'text/html'; // ATOM only
    $link->hreflang = 'en'; // ATOM only
    $link->title = 'Link to the homepage'; // ATOM only
    $link->length = 12345;  // ATOM only
    ?>

Parse example::

    <?php
    $links = array();

    // $feed is an ezcFeed object
    foreach ( $feed->link as $link )
    {
        $links[] = array(
          'href' => isset( $link->href ) ? $link->href : null,
          'rel' => isset( $link->rel ) ? $link->rel : null, // ATOM only
          'type' => isset( $link->type ) ? $link->type : null, // ATOM only
          'hreflang' => isset( $link->hreflang ) ? $link->hreflang : null, // ATOM only
          'title' => isset( $link->title ) ? $link->title : null, // ATOM only
          'length' => isset( $link->length ) ? $link->length : null, // ATOM only
          );
    }
    ?>

Equivalents: `ezcFeed-link`_, `ATOM-link`_, `RSS1-link`_, `RSS2-link`_.


ezcFeed-published
`````````````````

Type: ezcFeedDateElement.

The time the feed was published.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Can be assigned with an integer timestamp, a string date or a DateTime object.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->published = time();
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $published = isset( $feed->published ) ? $feed->published->date->format( 'c' ) : null;
    ?>

Other formats can be used also instead of ``'c'``, see the documentation for
`date_format()`_.

Equivalents: `ezcFeed-published`_, ATOM-none, RSS1-none, `RSS2-pubDate`_.


ezcFeed-rating
``````````````

Type: ezcFeedTextElement.

The `PICS`_ rating for the channel.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->rating = '(PICS-1.1 "http://www.gcf.org/v2.5" labels 
                      on "1994.11.05T08:15-0500" 
                      exp "1995.12.31T23:59-0000" 
                      for "http://www.greatdocs.com/foo.html" 
                      by "George Sanderson, Jr." 
                      ratings (suds 0.5 density 0 color/hue 1))';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $rating = isset( $feed->rating ) ? $feed->rating->__toString() : null;
    ?>

Equivalents: `ezcFeed-rating`_, ATOM-none, RSS1-none, `RSS2-rating`_.


ezcFeed-skipDays
````````````````

Type: ezcFeedSkipDaysElement.

A hint for aggregators telling them which days they can skip when reading the
feed.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Can have up to 7 *day* elements, each with a value from ``Monday`` to ``Sunday``.

Create example::

    <?php
    // $feed is an ezcFeed object
    $skip = $feed->add( 'skipDays' );
    $skip->days = array( 'Saturday', 'Sunday' );
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $days = array( 'Monday' => false, /*...*/ 'Sunday' => false );
    foreach ( $feed->skipDays->days as $skip )
    {
        $days[$skip] = true;
    }
    ?>

Equivalents: `ezcFeed-skipDays`_, ATOM-none, RSS1-none, `RSS2-skipDays`_.


ezcFeed-skipHours
`````````````````

Type: ezcFeedSkipHoursElement.

A hint for aggregators telling them which hours they can skip when reading the
feed.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Can have up to 24 *hour* elements, each with an integer value from ``0``
(midnight) to ``23``. The value ``24`` can also be used for midnight.

Create example::

    <?php
    // $feed is an ezcFeed object
    $skip = $feed->add( 'skipHours' );
    $skip->hours = array( 1, 2, 3, 4, 5 );
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $hours = array( '0' => false, /*...*/ '24' => false );
    foreach ( $feed->skipHours->hours as $skip )
    {
        $hours[$skip] = true;
    }
    ?>

Equivalents: `ezcFeed-skipHours`_, ATOM-none, RSS1-none, `RSS2-skipHours`_.


ezcFeed-textInput
`````````````````

Type: ezcFeedTextInputElement.

Specifies a text input box that can be displayed with the feed.

Optional (not recommended). Only `RSS1`_ and `RSS2`_ feeds will have this
element after generating the feed. It will be ignored for `ATOM`_ feeds.

Can appear only once.

For `RSS1`_ it has the required attribute *about*, which should have the same
value as the *link* sub-element.

Has four required sub-elements: *title*, *description*, *name*, *link* (same
for `RSS1`_ and `RSS2`_).

Create example::

    <?php
    // $feed is an ezcFeed object
    $textInput = $feed->add( 'textInput' );
    $textInput->title = 'Text input title';
    $textInput->description = 'Text input description';
    $textInput->name = 'Text input name';
    $textInput->link = 'Text input link';
    $textInput->about = 'Text input link'; // RSS1 only, ignored in RSS2
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->textInput ) )
    {
        $textInput = $feed->textInput;
        $title = isset( $textInput->title ) ? $textInput->title : null;
        $description = isset( $textInput->description ) ? $textInput->description : null;
        $name = isset( $textInput->name ) ? $textInput->name : null;
        $link = isset( $textInput->link ) ? $textInput->link : null;
        $about = isset( $textInput->about ) ? $textInput->about : null; // RSS1 only
    }
    ?>

Equivalents: `ezcFeed-textInput`_, ATOM-none, `RSS1-textinput`_,
`RSS2-textInput`_.


ezcFeed-title
`````````````

Type: ezcFeedTextElement.

Human readable title for the feed. For example, it can be the same as the
website title.

Required.

Can appear only once.

`ATOM`_ has an optional attribute *type* with possible values ``text``
(default), ``html``, ``xhtml``. This attribute will be ignored for `RSS1`_ and
`RSS2`_ feeds.

`ATOM`_ has an optional attribute *xml:lang* which specifies the language of
the text. A list of allowed languages can be found here:
`RSS language codes`_. This attribute is accessed through ezcFeed as *language*.
This attribute will be ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->title = 'Feed title';
    $feed->title->type = 'text'; // ATOM only, ignored in RSS1 and RSS2
    $feed->title->language = 'de'; // ATOM only, ignored in RSS1 and RSS2
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->title ) )
    {
        $element = $feed->title;
        $title = isset( $element->text ) ? $element->text : null;
        $type = isset( $element->type ) ? $element->type : null; // ATOM only
        $language = isset( $element->language ) ? $element->language : null; // ATOM only
    }
    ?>

Equivalents: `ezcFeed-title`_, `ATOM-title`_, `RSS1-title`_, `RSS2-title`_.


ezcFeed-ttl
```````````

Type: ezcFeedTextElement.

Number of minutes that indicates how long a channel can be cached before
refreshing from the source.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->ttl = '60'; // minutes
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $ttl = isset( $feed->ttl ) ? $feed->ttl->__toString() : null;
    ?>

Equivalents: `ezcFeed-ttl`_, ATOM-none, RSS1-none, `RSS2-ttl`_.


ezcFeed-updated
```````````````

Type: ezcFeedDateElement.

The last time the feed was updated.

Required for `ATOM`_. Optional for `RSS2`_. It will be ignored for `RSS1`_
feeds. ezcFeed will add automatically the *updated* element with the value the
current time in `ATOM`_ and `RSS2`_ feeds.

Can appear only once.

Can be assigned with an integer timestamp, a string date or a DateTime object.

Create example::

    <?php
    // $feed is an ezcFeed object
    $feed->updated = 'Tue, 10 Jun 2003 04:00:00 GMT';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    $updated = isset( $feed->updated ) ? $feed->updated->date->format( 'c' ) : null;
    ?>

Other formats can be used also instead of ``'c'``, see the documentation for
`date_format()`_.

Equivalents: `ezcFeed-updated`_, `ATOM-updated`_, RSS1-none, `RSS2-lastBuildDate`_.


ezcFeed-webMaster
`````````````````

Type: ezcFeedPersonElement.

The email address of the webmaster responsible for the feed.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

It is a good practice to include the name and email of the webmaster,
for example ``john.doe@example.com (John Doe)``.

Create example::

    <?php
    // $feed is an ezcFeed object
    $webMaster = $feed->add( 'webMaster' );
    $webMaster->name = 'John Doe';
    $webMaster->email = 'john.doe@example.com';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->webMaster ) )
    {
        $name = isset( $feed->webMaster->name ) ? $feed->webMaster->name : null;
    }
    ?>

Equivalents: `ezcFeed-webMaster`_, ATOM-none, RSS1-none, `RSS2-webMaster`_.


Item elements
-------------

ezcFeed-item-author
```````````````````

Type: array(ezcFeedPersonElement).

One author of the feed entry.

Required in `ATOM`_: one author must be present in each entry in case the feed
does not contain an author. Optional in `RSS2`_ (recommended). Ignored for
`RSS1`_ feeds.

Multiple authors can appear in `ATOM`_ (not recommended). Can appear only once
in `RSS2`_ feeds.

`ATOM`_ has required elements: *name*. Optional elements: *uri* (ignored in
`RSS2`_) and *email*.

In `RSS2`_ the generated XML element value will be ``email (name)``.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $author = $item->add( 'author' );
    $author->name = 'Guybrush Threepwood';
    $author->email = 'guybrush@monkey-island.com';
    $author->uri = 'http://example.com/~guybrush'; // ATOM only
    ?>

The resulting ATOM XML element will be::

  <author>
    <name>Guybrush Threepwood</name>
    <email>guybrush@monkey-island.com</email>
    <uri>http://example.com/~guybrush</uri>
  </author>

The resulting RSS2 XML element will be::

  <author>guybrush@monkey-island.com (Guybrush Threepwood)</author>
  
Parse example::

    <?php
    $authors = array();

    // $item is an ezcFeedEntryElement object
    if ( isset( $item->author ) )
    {
        foreach ( $item->author as $author )
        {
            $authors[] = array(
              'name' => isset( $author->name ) ? $author->name : null,
              'uri' => isset( $author->uri ) ? $author->uri : null, // ATOM only
              'email' => isset( $author->email ) ? $author->email : null // ATOM only
              );
        }
    }
    ?>

Equivalents: `ezcFeed-item-author`_, `ATOM-entry-author`_, RSS1-none,
`RSS2-item-author`_.


ezcFeed-item-category
`````````````````````

Type: array(ezcFeedCategoryElement).

A category for the feed entry.

Optional. Only `ATOM`_ and `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ feeds.

Multiple categories can appear in `ATOM`_ and `RSS2`_ feeds.

`ATOM`_ has one required attribute: *term*. Optional attributes: *scheme*
(*domain* in `RSS2`_) and *label* (ignored in `RSS2`_).

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $category = $item->add( 'category' );
    $category->term = 'holiday';
    $category->scheme = 'http://example.com/categories/holiday'; // scheme = RSS2 domain
    $category->label = 'Holiday'; // ATOM only
    ?>

Parse example::

    <?php
    $categories = array();

    // $item is an ezcFeedEntryElement object
    if ( isset( $item->category ) )
    {
        foreach ( $item->category as $category )
        {
            $categories[] = array(
              'term' => isset( $category->term ) ? $category->term : null,
              'scheme' => isset( $category->scheme ) ? $category->scheme : null, // scheme = RSS2 domain
              'label' => isset( $category->label ) ? $category->label : null // ATOM only
              );
        }
    }
    ?>

Equivalents: `ezcFeed-item-category`_, `ATOM-entry-category`_, RSS1-none,
`RSS2-item-category`_.


ezcFeed-item-comments
`````````````````````

Type: ezcFeedTextElement.

A link to a webpage for comments.

Optional (not recommended). Only `RSS2`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `ATOM`_ feeds.

Can appear only once.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->comments = 'http://www.example.com/comments.php';
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    $comments = isset( $item->comments ) ? $item->comments->__toString() : null;
    ?>

Equivalents: `ezcFeed-item-comments`_, ATOM-none, RSS1-none,
`RSS2-item-comments`_.


ezcFeed-item-content
````````````````````

Type: ezcFeedContentElement.

A short description for the feed item.

Optional (not recommended). Only `ATOM`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `RSS2`_ feeds. Can be
substituted with |ezcFeed-item-description|_ (recommended).

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``, or other mime values, depending on the data it contains.

Has an optional attribute *src* which specifies the URI where the full content
is located.

Has an optional attribute *xml:lang* which specifies the language of the text.
This attribute is accessed through ezcFeed as *language*. A list of allowed
languages can be found here: `RSS language codes`_.

If *src* is present, the *type* attribute, if present, is the media type of the
content.

Otherwise, if the type attribute ends in ``+xml`` or ``/xml``, then an XML
document of this type is contained inline.

Otherwise, if the type attribute starts with ``text``, then an escaped document
of this type is contained inline.

Otherwise, a base64 encoded document of the indicated media type is contained
inline.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->content = 'Content';
    $item->content->type = 'text';
    $item->content->language = 'de';
    $item->content->src = 'http://example.com/content_src.html';
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    if ( isset( $item->content ) )
    {
        $contentElement = $item->content;
        $content = $descriptionElement->text;
        $type = isset( $contentElement->type ) ? $contentElement->type : null;
        $language = isset( $contentElement->language ) ? $contentElement->language : null;
        $src = isset( $contentElement->src ) ? $contentElement->src : null;
    }
    ?>

Equivalents: `ezcFeed-item-content`_/`ezcFeed-item-description`_,
`ATOM-entry-content`_, RSS1-none, RSS2-none.


ezcFeed-item-contributor
````````````````````````

Type: array(ezcFeedPersonElement).

One contributor of the feed entry.

Optional (not recommended). Only `ATOM`_ feeds will have this element after
generating the feed. It will be ignored for `RSS1`_ and `RSS2`_ feeds.

Multiple contributors can appear.

Required elements: *name*. Optional elements: *uri*, *email*.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $contributor = $item->add( 'contributor' );
    $contributor->name = 'Guybrush Threepwood';
    $contributor->uri = 'http://example.com/~guybrush';
    $contributor->email = 'guybrush@monkey-island.com';
    ?>

Parse example::

    <?php
    $contributors = array();

    // $item is an ezcFeedEntryElement object
    if ( isset( $item->contributor ) )
    {
        foreach ( $item->contributor as $contributor )
        {
            $contributors[] = array(
              'name' => isset( $contributor->name ) ? $contributor->name : null,
              'uri' => isset( $contributor->uri ) ? $contributor->uri : null,
              'email' => isset( $contributor->email ) ? $contributor->email : null
              );
        }
    }
    ?>

Equivalents: `ezcFeed-item-contributor`_, `ATOM-entry-contributor`_,
RSS1-none, RSS2-none.


ezcFeed-item-copyright
``````````````````````

Type: ezcFeedTextElement.

Copyright information for the feed entry.

Optional. Only `ATOM`_ feeds will have this element after generating the feed.
It will be ignored for `RSS1`_ and `RSS2`_ feeds. For `RSS2`_ the copyright is
specified for the whole feed, not for any feed items (see
`ezcFeed-copyright`_).

Can appear only once.

`ATOM`_ has an optional attribute *type* with possible values ``text``
(default), ``html``, ``xhtml``. This attribute will be ignored for `RSS1`_ and
`RSS2`_ feeds.

`ATOM`_ has an optional attribute *xml:lang* which specifies the language of
the text. A list of allowed languages can be found here:
`RSS language codes`_. This attribute is accessed through ezcFeed as
*language*. This attribute will be ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->copyright = 'Copyright <company name>';
    $item->copyright->type = 'text'; // ATOM only
    $item->copyright->language = 'de'; // ATOM only
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    if ( isset( $item->copyright ) )
    {
        $copyrightElement = $item->copyright;
        $copyright = $copyrightElement->text;
        $type = isset( $copyrightElement->type ) ? $copyrightElement->type : null; // ATOM only
        $language = isset( $copyrightElement->language ) ? $copyrightElement->language : null; // ATOM only
    }
    ?>

Equivalents: `ezcFeed-item-copyright`_, `ATOM-entry-rights`_, RSS1-none,
RSS2-none (`RSS2-copyright`_ for the whole feed).


ezcFeed-item-description
````````````````````````

Type: ezcFeedTextElement.

A short description of the feed item.

Required. In `ATOM`_ it can be substituted with `ATOM-entry-content`_ (not
recommended) (see `ezcFeed-item-content`_).

Can appear only once.

`ATOM`_ has an optional attribute *type* with possible values ``text``
(default), ``html``, ``xhtml``. This attribute will be ignored for `RSS1`_ and
`RSS2`_ feeds.

`ATOM`_ has an optional attribute *xml:lang* which specifies the language of
the text. A list of allowed languages can be found here:
`RSS language codes`_. This attribute is accessed through ezcFeed as
*language*. This attribute will ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->description = 'Feed description';
    $item->description->type = 'text'; // ATOM only, ignored in RSS1 and RSS2
    $item->description->language = 'de'; // ATOM only, ignored in RSS1 and RSS2
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    if ( isset( $item->description ) )
    {
        $desc = $item->description;
        $description = $desc->text;
        $type = isset( $desc->type ) ? $desc->type : null; // ATOM only
        $language = isset( $desc->language ) ? $desc->language : null; // ATOM only
    }
    ?>

Equivalents: `ezcFeed-item-description`_, `ATOM-entry-summary`_,
`RSS1-item-description`_, `RSS2-item-description`_.


ezcFeed-item-enclosure
``````````````````````

Type: array(ezcFeedEnclosureElement).

A link to a multimedia file attached to the feed item.

Optional. Only `RSS2`_ feeds will have this element after generating the feed.
It will be ignored for `RSS1`_. For `ATOM`_ feeds the enclosure elements will
be converted to |ATOM-entry-link|_ elements with the attribute
``rel="enclosure"``.

Can appear only once in `RSS2`_ and multiple times in `ATOM`_ (as
|ATOM-entry-link|_).

Has 3 required attributes: *url*, *length*, *type*.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $enclosure = $item->add( 'enclosure' );  
    $enclosure->url = 'http://example.com/media/episode_001.mp3';
    $enclosure->length = 49099054; // bytes
    $enclosure->type = 'audio/x-mp3';
    ?>

`RSS2`_ output::

  <enclosure url="http://example.com/media/episode_001.mp3"
             length="49099054"
             type="audio/x-mp3"/>

`ATOM`_ output::

  <link href="http://example.com/media/episode_001.mp3"
        rel="enclosure"
        length="49099054"
        type="audio/x-mp3"/>

Parse example (`RSS2`_)::

    <?php
    // $item is an ezcFeedEntryElement object
    if ( isset( $item->enclosure ) )
    {
        $enclosure = $item->enclosure[0];
        $url = isset( $enclosure->url ) ? $enclosure->url : null;
        $length = isset( $enclosure->length ) ? $enclosure->length : null;
        $type = isset( $enclosure->type ) ? $enclosure->type : null;
    }
    ?>

Equivalents: `ezcFeed-item-enclosure`_, ATOM-none (`ATOM-entry-link`_ for
similar functionality), RSS1-none, `RSS2-item-enclosure`_.


ezcFeed-item-id
```````````````

Type: ezcFeedIdElement.

A unique identifier in respect to other *id* values of entries in the feed. It
identifies the entry.

Required for `ATOM`_ and `RSS1`_. Optional for `RSS2`_ (recommended).

`RSS2`_ has the optional attribute *isPermLink*. This attribute is ignored for
`RSS1`_ and `ATOM`_.

Can appear only once.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->id = 'ID value';
    $item->id->isPermLink = false; // RSS2 only, it will be ignored for RSS1 and ATOM
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    if ( isset( $item->id ) )
    {
        $id = isset( $feed->id->id ) : $feed->id->id : null;
        $isPermLink = isset( $feed->id->isPermLink ) ? $feed->id->isPermLink : null; // RSS2 only
    }
    ?>

Equivalents: `ezcFeed-item-id`_, `ATOM-entry-id`_, `RSS1-item-about`_,
`RSS2-item-guid`_.


ezcFeed-item-link
`````````````````

Type: array(ezcFeedLinkElement).

A link to a resource related to the feed entry.

Required.

Multiple links can appear in `ATOM`_ (not recommended). Can appear only once
in `RSS1`_ and `RSS2`_ feeds.

Enclosures of media files (used mainly for podcasts) can be added with this
element. In `RSS2`_ use `ezcFeed-item-enclosure`_. `RSS1`_ does not support
enclosures.

`ATOM`_ has required attributes: *href*. Optional attributes: *rel* (possible
values: ``alternate`` (default), ``enclosure``, ``related``, ``self``,
``via``), *type*, *hreflang*, *title*, *length*.

A maximum of one link with ``rel="alternate"`` can appear per *type* and
*hreflang*.

Recommended only one ``rel="enclosure"`` link to keep compatibility with
`RSS2`_ |RSS2-item-enclosure|_.

These attributes are ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $link = $item->add( 'link' );
    $link->href = 'http://example.com';
    $link->rel = 'self'; // ATOM only
    $link->type = 'text/html'; // ATOM only
    $link->hreflang = 'en'; // ATOM only
    $link->title = 'Link to the article'; // ATOM only
    $link->length = '20:14';  // ATOM only
    ?>

Parse example::

    <?php
    $links = array();

    // $item is an ezcFeedEntryElement object
    foreach ( $item->link as $link )
    {
        $links[] = array(
          'href' => isset( $link->href ) ? $link->href : null,
          'rel' => isset( $link->rel ) ? $link->rel : null, // ATOM only
          'type' => isset( $link->type ) ? $link->type : null, // ATOM only
          'hreflang' => isset( $link->hreflang ) ? $link->hreflang : null, // ATOM only
          'title' => isset( $link->title ) ? $link->title : null, // ATOM only
          'length' => isset( $link->length ) ? $link->length : null, // ATOM only
          );
    }
    ?>

Equivalents: `ezcFeed-item-link`_/`ezcFeed-item-enclosure`_,
`ATOM-entry-link`_, `RSS1-item-link`_, `RSS2-item-link`_/
`RSS2-item-enclosure`_.


ezcFeed-item-published
``````````````````````

Type: ezcFeedDateElement.

The time the feed item was published.

Optional (recommended). Only `ATOM`_ and `RSS2`_ feeds will have this
element after generating the feed. It will be ignored for `RSS1`_ feeds.

Can appear only once.

Can be assigned with an integer timestamp, a string date or a DateTime object.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->published = time();
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    $published = isset( $item->published ) ? $item->published->date->format( 'c' ) : null;
    ?>

Equivalents: `ezcFeed-item-published`_, `ATOM-entry-published`_, RSS1-none,
`RSS2-item-pubDate`_.


ezcFeed-item-source
```````````````````

Type: ezcFeedSourceElement.

The source (another feed) of the feed item.

Optional (not recommended). Only `ATOM`_ and `RSS2`_ feeds will have this
element after generating the feed. It will be ignored for `RSS1`_ feeds.

For `ATOM`_ feeds, all `ATOM`_ feed-level elements can be added, minus the
|ezcFeed-item|_ element. `RSS2`_ feeds have the attributes *source* and *url*.

Can appear only once.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $source = $item->add( 'source' );
    $source->source = 'Source feed name'; // RSS2 only, ignored for ATOM
    $source->url = 'http://source.feed.url/'; // RSS2 only, ignored for ATOM

    $author = $source->add( 'author' ); // ATOM only, ignored for RSS2
    $author->name = 'Author of the source feed';
    $author->email = 'Email address of the author of the source feed';

    // more elements which pertain to ATOM feeds can be added
    ?>

Parse example::

    <?php
    // $item is an ezcFeedSourceElement object
    if ( isset( $item->source ) )
    {
        $source = $item->source;

        $rss2SourceName = isset( $source->source ) ? $source->source : null;
        $rss2SourceUrl = isset( $source->url ) ? $source->url : null;

        $atomSourceTitle = isset( $source->title ) ? $source->title->__toString() : null;
    }
    ?>

Equivalents: `ezcFeed-item-source`_, `ATOM-entry-source`_, RSS1-none,
`RSS2-item-source`_.


ezcFeed-item-title
``````````````````

Type: ezcFeedTextElement.

Human readable title for the feed item.

Required.

Can appear only once.

`ATOM`_ has an optional attribute *type* with possible values ``text``
(default), ``html``, ``xhtml``. This attribute will be ignored for `RSS1`_ and
`RSS2`_ feeds.

`ATOM`_ has an optional attribute *xml:lang* which specifies the language of
the text. A list of allowed languages can be found here:
`RSS language codes`_. This attribute is accessed through ezcFeed as
*language*. This attribute will be ignored for `RSS1`_ and `RSS2`_ feeds.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->title = 'Feed title';
    $item->title->type = 'text'; // ATOM only, ignored in RSS1 and RSS2
    $item->title->language = 'de'; // ATOM only, ignored in RSS1 and RSS2
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    if ( isset( $item->title ) )
    {
        $titleElement = $item->title;
        $title = $titleElement->text;
        $type = isset( $titleElement->type ) ? $titleElement->type : null; // ATOM only
        $language = isset( $titleElement->language ) ? $titleElement->language : null; // ATOM only
    }
    ?>

Equivalents: `ezcFeed-item-title`_, `ATOM-entry-title`_, `RSS1-item-title`_,
`RSS2-item-title`_.


ezcFeed-item-updated
````````````````````

Type: ezcFeedDateElement.

The last time the feed entry was updated.

Required. Only `ATOM`_ feeds will have this element after generating the
feed. It will be ignored for `RSS1`_ and `RSS2`_ feeds.

Can appear only once.

Can be assigned with an integer timestamp, a string date or a DateTime object.

Create example::

    <?php
    // $item is an ezcFeedEntryElement object
    $item->updated = 'Tue, 10 Jun 2003 04:00:00 GMT';
    ?>

Parse example::

    <?php
    // $item is an ezcFeedEntryElement object
    $updated = isset( $item->updated ) ? $item->updated->date->format( 'c' ) : null;
    ?>

Equivalents: `ezcFeed-item-updated`_, `ATOM-entry-updated`_, RSS1-none,
RSS2-none.


==========
Feed types
==========

ATOM
====

Specifications
--------------

`RFC 4287`_


Content type
------------

All ATOM feeds should be identified with the ``application/atom+xml`` content
type.


Structure
---------

General information:
 - All elements must be in the http://www.w3.org/2005/Atom namespace
 - The top level element is called *feed*
 - All timestamps must conform to `RFC 3339`_ (eg. ``2003-12-13T18:30:02Z``)
 - Unless otherwise specified, all values must be plain text
 - *xml:lang* may be used to identify the language of text (the property
   *language* for the ATOM elements |ATOM-rights|_, |ATOM-subtitle|_,
   |ATOM-title|_, |ATOM-entry-content|_, |ATOM-entry-rights|_,
   |ATOM-entry-summary|_, |ATOM-entry-title|_).
 - *xml:base* may be used to control how relative URIs are resolved (not
   recommended)

Sample ATOM feed:

.. include:: tutorial/atom_example.xml
   :literal:


Feed elements
-------------

ATOM-author
```````````

One author of the feed.

Required: one author must be present unless all items contain at least one
author.

Multiple authors can appear.

Required elements: *name*. Optional elements: *uri*, *email*.

Example::

  <author>
    <name>John Doe</name>
    <uri>http://example.com/~johndoe</uri>
    <email>JohnDoe@example.com</email>
  </author>

Equivalents: `ezcFeed-author`_, `ATOM-author`_, RSS1-none,
`RSS2-managingEditor`_.


ATOM-category
`````````````

A category for the feed.

Optional.

Multiple categories can appear.

Has one required attribute: *term*. Has 2 optional attributes: *scheme*,
*label*.

Equivalents: `ezcFeed-category`_, `ATOM-category`_, RSS1-none,
`RSS2-category`_.


ATOM-contributor
````````````````

One contributor of the feed.

Optional (not recommended).

Multiple contributors can appear.

Required elements: *name*. Optional elements: *uri*, *email*.

Example::

  <contributor>
    <name>John Doe</name>
    <uri>http://example.com/~johndoe</uri>
    <email>JohnDoe@example.com</email>
  </contributor>

Equivalents: `ezcFeed-contributor`_, `ATOM-contributor`_, RSS1-none,
RSS2-none.


ATOM-entry
``````````

Feed entry.

Optional (recommended).

Multiple entries can appear.

Equivalents: `ezcFeed-item`_, `ATOM-entry`_, `RSS1-item`_, `RSS2-item`_.


ATOM-generator
``````````````

Indicates the software used to generate the feed.

Optional.

Can appear only once.

Has 2 optional attributes: *url*, *version*.

Equivalents: `ezcFeed-generator`_, `ATOM-generator`_, RSS1-none,
`RSS2-generator`_.


ATOM-icon
`````````

An icon for a feed, similar with ``favicon.ico`` for websites.

Optional.

Can appear only once.

Equivalents: `ezcFeed-icon`_, `ATOM-icon`_, RSS1-none, RSS2-none.


ATOM-id
```````

A universally unique and permanent URI for a feed. For example, it can be an
Internet domain name.

Required.

Can appear only once.

Equivalents: `ezcFeed-id`_, `ATOM-id`_, `RSS1-about`_, `RSS2-id`_.


ATOM-link
`````````

An URL to the HTML website corresponding to the feed.

Required: a link back to the feed itself must be present (with ``rel="self"``).

Multiple links can appear.

Required attributes: *href*. Optional attributes: *rel* (possible values:
``alternate`` (default), ``enclosure``, ``related``, ``self``, ``via``),
*type*, *hreflang*, *title*, *length*.

A maximum of one link with ``rel="alternate"`` can appear per *type* and
*hreflang*.

Equivalents: `ezcFeed-link`_, `ATOM-link`_, `RSS1-link`_, `RSS2-link`_.


ATOM-logo
`````````

An image associated with the feed. The value is an URL to an image.

Optional.

Can appear only once.

Equivalents: `ezcFeed-image`_, `ATOM-logo`_, `RSS1-image`_, `RSS2-image`_.


ATOM-rights
```````````

Copyright information for the feed.

Optional.

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-copyright`_, `ATOM-rights`_, RSS1-none,
`RSS2-copyright`_.


ATOM-subtitle
`````````````

A short description of the feed.

Optional (recommended).

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-description`_, `ATOM-subtitle`_, `RSS1-description`_,
`RSS2-description`_.


ATOM-title
``````````

Human readable title for the feed. For example, it can be the same as the
website title.

Required.

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-title`_, `ATOM-title`_, `RSS1-title`_, `RSS2-title`_.


ATOM-updated
````````````

The last time the feed was updated.

Required.

Can appear only once.

Must conform to `RFC 3339`_ (eg. ``2003-12-13T18:30:02Z``).

Equivalents: `ezcFeed-updated`_, `ATOM-updated`_, RSS1-none, `RSS2-lastBuildDate`_.


Item elements
-------------

ATOM-entry-author
`````````````````

One author of the feed entry.

Required: one author must be present in each entry in case the feed does not
contain an author.

Multiple authors can appear.

Required elements: *name*. Optional elements: *uri*, *email*.

Example::

  <author>
    <name>John Doe</name>
    <uri>http://example.com/~johndoe</uri>
    <email>JohnDoe@example.com</email>
  </author>

Equivalents: `ezcFeed-item-author`_, `ATOM-entry-author`_, RSS1-none,
`RSS2-item-author`_.


ATOM-entry-category
```````````````````

A category for the feed entry.

Optional.

Multiple categories can appear.

Has one required attribute: *term*. Has 2 optional attributes: *scheme*,
*label*.

Equivalents: `ezcFeed-item-category`_, `ATOM-entry-category`_, RSS1-none,
`RSS2-item-category`_.


ATOM-entry-content
``````````````````

A short description for the feed item.

Optional (not recommended). It is required if |ATOM-entry-summary|_ is
absent). Can be substituted with |ATOM-entry-summary|_ (recommended).

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``, or other mime values, depending on the data it contains.

Has an optional attribute *src* which specifies the URI where the full content
is located.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here:
`RSS language codes`_.

If *src* is present, the *type* attribute, if present, is the media type of the
content.

Otherwise, if the type attribute ends in ``+xml`` or ``/xml``, then an XML
document of this type is contained inline.

Otherwise, if the type attribute starts with ``text``, then an escaped document
of this type is contained inline.

Otherwise, a base64 encoded document of the indicated media type is contained
inline.

Equivalents: `ezcFeed-item-description`_, `ATOM-entry-summary`_/
`ATOM-entry-content`_, `RSS1-item-description`_, `RSS2-item-description`_.


ATOM-entry-contributor
``````````````````````

One contributor of the feed entry.

Optional (not recommended).

Multiple contributors can appear.

Required elements: *name*. Optional elements: *uri*, *email*.

Example::

  <contributor>
    <name>John Doe</name>
    <uri>http://example.com/~johndoe</uri>
    <email>JohnDoe@example.com</email>
  </contributor>

Equivalents: `ezcFeed-item-contributor`_, `ATOM-entry-contributor`_,
RSS1-none, RSS2-none.


ATOM-entry-id
`````````````

A unique identifier in respect to other *id* values of entries in the feed. It
identifies the entry.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-id`_, `ATOM-entry-id`_, `RSS1-item-about`_,
`RSS2-item-guid`_.


ATOM-entry-link
```````````````

A link to a resource related to the feed entry.

Required.

Multiple links can appear.

Required attributes: *href*. Optional attributes: *rel* (possible values:
``alternate`` (default), ``enclosure``, ``related``, ``self``, ``via``),
*type*, *hreflang*, *title*, *length*.

A maximum of one link with ``rel="alternate"`` can appear per *type* and
*hreflang*.

Recommended only one ``rel="enclosure"`` link to keep compatibility with RSS2
|RSS2-item-enclosure|_.

Equivalents: `ezcFeed-item-link`_/`ezcFeed-item-enclosure`_,
`ATOM-entry-link`_, `RSS1-item-link`_, `RSS2-item-link`_/
`RSS2-item-enclosure`_.


ATOM-entry-published
````````````````````

The time the feed item was published.

Optional (recommended).

Can appear only once.

Must conform to `RFC 3339`_ (eg. ``2003-12-13T18:30:02Z``).

Equivalents: `ezcFeed-item-published`_, `ATOM-entry-published`_, RSS1-none,
`RSS2-item-pubDate`_.


ATOM-entry-rights
`````````````````

Copyright information for the feed entry.

Optional.

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-item-copyright`_, `ATOM-entry-rights`_, RSS1-none,
RSS2-none (`RSS2-copyright`_ for the whole feed).


ATOM-entry-summary
``````````````````

A short description for the feed item.

Required. Can be substituted with |ATOM-entry-content|_ (not recommended).

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-item-description`_, `ATOM-entry-summary`_/
`ATOM-entry-content`_, `RSS1-item-description`_, `RSS2-item-description`_.


ATOM-entry-source
`````````````````

The source feed of the feed item.

Optional (not recommended).

Can appear only once.

Can have the same elements which are present at feed-level in ATOM, minus the
|ATOM-entry|_ element:

- |ATOM-author|_
- |ATOM-category|_
- |ATOM-contributor|_
- |ATOM-rights|_
- |ATOM-subtitle|_
- |ATOM-generator|_
- |ATOM-icon|_
- |ATOM-id|_
- |ATOM-logo|_
- |ATOM-link|_
- |ATOM-title|_
- |ATOM-updated|_

Equivalents: `ezcFeed-item-source`_, `ATOM-entry-source`_, RSS1-none,
`RSS2-item-source`_.


ATOM-entry-title
````````````````

A title for the feed item.

Required.

Can appear only once.

Has an optional attribute *type* with possible values ``text`` (default),
``html``, ``xhtml``.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-item-title`_, `ATOM-entry-title`_, `RSS1-item-title`_,
`RSS2-item-title`_.


ATOM-entry-updated
``````````````````

The last time the feed entry was updated.

Required.

Can appear only once.

Must conform to `RFC 3339`_ (eg. ``2003-12-13T18:30:02Z``).

Equivalents: `ezcFeed-item-updated`_, `ATOM-entry-updated`_, RSS1-none,
RSS2-none.


RSS1
====

Specifications
--------------

RSS1 = RDF Site Summary
RDF = Resource Description Framework

`RSS1 specifications`_


Content type
------------

All RSS1 feeds should be identified with the ``application/rss+xml`` content
type (not a standard yet).


Structure
---------

Sample RSS1 feed:

.. include:: tutorial/rss1_example.xml
   :literal:


Feed elements
-------------

RSS1-about
``````````

A universally unique and permanent URI for a feed. For example, it can be an
Internet domain name.

Required.

Can appear only once.

Equivalents: `ezcFeed-id`_, `ATOM-id`_, `RSS1-about`_, `RSS2-id`_.


RSS1-description
````````````````

A short description of the feed.

Required.

Can appear only once.

Equivalents: `ezcFeed-description`_, `ATOM-subtitle`_, `RSS1-description`_,
`RSS2-description`_.


RSS1-image
``````````

An image associated with the feed.

Optional.

Can appear only once.

Has the required attribute *about*, which should have the same value as the
*url* sub-element.

Has 3 required sub-elements: *title*, *link*, *url*.

Equivalents: `ezcFeed-image`_, `ATOM-logo`_, `RSS1-image`_, `RSS2-image`_.


RSS1-item
`````````

A feed entry.

Required.

Multiple entries can appear.

Equivalents: `ezcFeed-item`_, `ATOM-entry`_, `RSS1-item`_, `RSS2-item`_.


RSS1-link
`````````

The URL to the HTML website corresponding to the feed.

Required.

Can appear only once.

Equivalents: `ezcFeed-link`_, `ATOM-link`_, `RSS1-link`_, `RSS2-link`_.


RSS1-textinput
``````````````

Specifies a text input box that can be displayed with the feed.

Optional (not recommended).

Can appear only once.

Has the required attribute *about*, which should have the same value as the
*link* sub-element.

Has four required sub-elements: *title*, *description*, *name*, *link*.

Equivalents: `ezcFeed-textInput`_, ATOM-none, `RSS1-textinput`_,
`RSS2-textInput`_.


RSS1-title
``````````

Human readable title for the feed. For example, it can be the same as the
website title.

Required.

Can appear only once.

Equivalents: `ezcFeed-title`_, `ATOM-title`_, `RSS1-title`_, `RSS2-title`_.


Item elements
-------------

RSS1-item-about
```````````````

A unique identifier in respect to other *about* values in the feed. It
identifies the item. Should be identical to the *link* value of the item, if
possible.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-id`_, `ATOM-entry-id`_, `RSS1-item-about`_,
`RSS2-item-guid`_.


RSS1-item-description
`````````````````````

A short description of the feed item.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-description`_, `ATOM-entry-summary`_,
`RSS1-item-description`_, `RSS2-item-description`_.


RSS1-item-link
``````````````

The URL to the HTML website corresponding to the feed item.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-link`_, `ATOM-entry-link`_, `RSS1-item-link`_,
`RSS2-item-link`_.


RSS1-item-title
```````````````

A title for the feed item.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-title`_, `ATOM-entry-title`_, `RSS1-item-title`_,
`RSS2-item-title`_.


RSS2
====

Specifications
--------------

RSS2 = Really Simple Syndication

`RSS2 specifications`_


Content type
------------

All RSS2 feeds should be identified with the ``application/rss+xml`` content
type (not a standard yet).


Structure
---------

Sample RSS2 feed:

.. include:: tutorial/rss2_example.xml
   :literal:


Feed elements
-------------

RSS2-category
`````````````

A category for the feed.

Optional.

Multiple categories can appear.

Has one optional attribute: *domain*.

The value of the category element must be specified.

Equivalents: `ezcFeed-category`_, `ATOM-category`_, RSS1-none,
`RSS2-category`_.


RSS2-cloud
``````````

Allows processes to register with a cloud to be notified of updates to the
channel, implementing a lightweight publish-subscribe protocol for RSS feeds.

Optional (not recommended).

Can appear only once.

Has the required attributes: *domain*, *port*, *path*, *registerProcedure*,
*protocol*.

Example::

  <cloud domain="rpc.sys.com" port="80" path="/RPC2" registerProcedure="myCloud.rssPleaseNotify" protocol="xml-rpc" />

Equivalents: `ezcFeed-cloud`_, ATOM-none, RSS1-none, `RSS2-cloud`_.


RSS2-copyright
``````````````

Copyright information for the feed.

Optional.

Can appear only once.

Equivalents: `ezcFeed-copyright`_, `ATOM-rights`_, RSS1-none,
`RSS2-copyright`_.


RSS2-description
````````````````

A short description of the feed.

Required.

Can appear only once.

Equivalents: `ezcFeed-description`_, `ATOM-subtitle`_, `RSS1-description`_,
`RSS2-description`_.


RSS2-docs
`````````

An URL that points to the documentation for the format used in the RSS file. It
is usually http://www.rssboard.org/rss-specification.

Optional.

Can appear only once.

Equivalents: `ezcFeed-docs`_, ATOM-none, RSS1-none, `RSS2-docs`_.


RSS2-generator
``````````````

Indicates the software used to generate the feed.

Optional.

Can appear only once.

Equivalents: `ezcFeed-generator`_, `ATOM-generator`_, RSS1-none,
`RSS2-generator`_.


RSS2-id
```````

Most `feed validator`_ applications will recommend to include in an RSS2 feed
a link to the location of the feed. For example, if the XML document
containing the RSS2 feed is located at 'http://example.com/rss/', then this
URL should be contained in the feed itself in an *atom:link* element, since
RSS2 does not offer a mechanism to specify self-links.

Use the `ezcFeed-id`_ to specify this self-link::

    $feed->id = 'http://example.com/rss/';

This will be rendered in XML as::

    <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
    ...
    <atom:link href="http://example.com/" rel="self" type="application/rss+xml"/>

Optional (although recommended because `ezcFeed-id`_ is recommended). The
*id* feed element does not appear in the `RSS2 specifications`_, but it is
added to comply with `feed validator`_ recommendations and it is rendered as
an `ATOM`_ element as discussed above.

Can appear only once.

Equivalents: `ezcFeed-id`_, `ATOM-id`_, `RSS1-about`_, `RSS2-id`_.


RSS2-image
``````````

An image associated with the feed.

Optional.

Can appear only once.

Has 3 required sub-elements: *title*, *link*, *url*.

Has 3 optional sub-elements: *width*, *height*, *description*.

Equivalents: `ezcFeed-image`_, `ATOM-logo`_, `RSS1-image`_, `RSS2-image`_.


RSS2-item
`````````

Feed entry.

Required.

Multiple entries can appear.

Equivalents: `ezcFeed-item`_, `ATOM-entry`_, `RSS1-item`_, `RSS2-item`_.


RSS2-language
`````````````

The language for the feed.

Optional (recommended).

Can appear only once.

A list of allowed languages can be found here: `RSS language codes`_.

Equivalents: `ezcFeed-language`_, ATOM-*xml:lang* for each element, RSS1-none,
`RSS2-language`_.


RSS2-lastBuildDate
``````````````````

The last time the feed was updated.

Optional (recommended).

Can appear only once.

Must conform to `RFC 822`_ (eg. ``Sat, 07 Sep 2002 09:42:31 GMT``).

Equivalents: `ezcFeed-updated`_, `ATOM-updated`_, RSS1-none,
`RSS2-lastBuildDate`_.


RSS2-link
`````````

The URL to the HTML website corresponding to the feed.

Required.

Can appear only once.

Equivalents: `ezcFeed-link`_, `ATOM-link`_, `RSS1-link`_, `RSS2-link`_.


RSS2-managingEditor
```````````````````

One author of the feed.

Optional (recommended).

Can appear only once.

It is a good practice to include the name and email of the managing editor,
for example ``john.doe@example.com (John Doe)``.

Equivalents: `ezcFeed-author`_, `ATOM-author`_, RSS1-none,
`RSS2-managingEditor`_.


RSS2-pubDate
````````````

The time the feed was published.

Optional (not recommended).

Can appear only once.

Must conform to `RFC 822`_ (eg. ``Sat, 07 Sep 2002 09:42:31 GMT``).

Equivalents: `ezcFeed-published`_, ATOM-none, RSS1-none, `RSS2-pubDate`_.


RSS2-rating
```````````

The `PICS`_ rating for the channel.

Optional (not recommended).

Can appear only once.

Equivalents: `ezcFeed-rating`_, ATOM-none, RSS1-none, `RSS2-rating`_.


RSS2-skipDays
`````````````

A hint for aggregators telling them which days they can skip when reading the
feed.

Optional (not recommended).

Can appear only once.

Can have up to 7 *day* elements, each with a value from ``Monday`` to ``Sunday``.

Equivalents: `ezcFeed-skipDays`_, ATOM-none, RSS1-none, `RSS2-skipDays`_.


RSS2-skipHours
``````````````

A hint for aggregators telling them which hours they can skip when reading the
feed.

Optional (not recommended).

Can appear only once.

Can have up to 24 *hour* elements, each with an integer value from ``0``
(midnight) to ``23``. The value ``24`` can also be used for midnight.

Equivalents: `ezcFeed-skipHours`_, ATOM-none, RSS1-none, `RSS2-skipHours`_.


RSS2-textInput
``````````````

Specifies a text input box that can be displayed with the feed.

Optional (not recommended).

Can appear only once.

Has four required sub-elements: *title*, *description*, *name*, *link*.

Equivalents: `ezcFeed-textInput`_, ATOM-none, `RSS1-textinput`_,
`RSS2-textInput`_.


RSS2-title
``````````

Human readable title for the feed. For example, it can be the same as the
website title.

Required.

Can appear only once.

Equivalents: `ezcFeed-title`_, `ATOM-title`_, `RSS1-title`_, `RSS2-title`_.


RSS2-ttl
````````

Number of minutes that indicates how long a channel can be cached before
refreshing from the source.

Optional (not recommended).

Can appear only once.

Equivalents: `ezcFeed-ttl`_, ATOM-none, RSS1-none, `RSS2-ttl`_.


RSS2-webMaster
``````````````

The email address of the webmaster responsible for the feed.

Optional (not recommended).

Can appear only once.

It is a good practice to include the name and email of the webmaster,
for example ``john.doe@example.com (John Doe)</webMaster>``.

Equivalents: `ezcFeed-webMaster`_, ATOM-none, RSS1-none, `RSS2-webMaster`_.


Item elements
-------------

RSS2-item-author
````````````````

The email address of the person who created the feed item.

Optional (recommended).

Can appear only once.

It is a good practice to include the name and email of the author, for
example ``john.doe@example.com (John Doe)</author>``.

Equivalents: `ezcFeed-item-author`_, `ATOM-entry-author`_, RSS1-none,
`RSS2-item-author`_.


RSS2-item-category
``````````````````

A category for the feed.

Optional.

Multiple categories can appear.

Has one optional attribute: *domain*.

The value of the category element must be specified.

Equivalents: `ezcFeed-item-category`_, `ATOM-entry-category`_, RSS1-none,
`RSS2-item-category`_.


RSS2-item-comments
``````````````````

A link to a webpage for comments.

Optional (not recommended).

Can appear only once.

Equivalents: `ezcFeed-item-comments`_, ATOM-none, RSS1-none,
`RSS2-item-comments`_.


RSS2-item-description
`````````````````````

A short description of the feed item.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-description`_, `ATOM-entry-summary`_,
`RSS1-item-description`_, `RSS2-item-description`_.


RSS2-item-enclosure
```````````````````

A link to a multimedia file attached to the feed item.

Optional.

Can appear only once.

Has 3 required attributes: *url*, *length*, *type*.

Equivalents: `ezcFeed-item-enclosure`_, ATOM-none (`ATOM-entry-link`_ for
similar functionality), RSS1-none, `RSS2-item-enclosure`_.


RSS2-item-guid
``````````````

A unique identifier in respect to other *guid* values of items in the feed. It
identifies the item.

Optional (recommended).

Can appear only once.

Has an optional attribute *isPermaLink* with possible values ``true`` or
``false`` (default), which specifies if the *guid* value is an URL.

Equivalents: `ezcFeed-item-id`_, `ATOM-entry-id`_, `RSS1-item-about`_,
`RSS2-item-guid`_.


RSS2-item-link
``````````````

The URL to the HTML website corresponding to the feed item.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-link`_, `ATOM-entry-link`_, `RSS1-item-link`_,
`RSS2-item-link`_.


RSS2-item-pubDate
`````````````````

The time the feed item was published.

Optional (recommended).

Can appear only once.

Must conform to `RFC 822`_ (eg. ``Sat, 07 Sep 2002 09:42:31 GMT``).

Equivalents: `ezcFeed-item-published`_, `ATOM-entry-published`_, RSS1-none,
`RSS2-item-pubDate`_.


RSS2-item-source
````````````````

The source feed of the feed item.

Optional (not recommended).

Can appear only once.

Has 2 optional attributes: *source*, *url*.

Equivalents: `ezcFeed-item-source`_, `ATOM-entry-source`_, RSS1-none,
`RSS2-item-source`_.


RSS2-item-title
```````````````

A title for the feed item.

Required.

Can appear only once.

Equivalents: `ezcFeed-item-title`_, `ATOM-entry-title`_, `RSS1-item-title`_,
`RSS2-item-title`_.


=======
Modules
=======

Content
=======

Specifications
--------------

`Content specifications`_


Feed elements
-------------


Item elements
-------------

Content-item-encoded
````````````````````

Type: ezcFeedContentElement.

HTML-encoded text.

Optional.

Can appear only once.

Create example::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed( 'rss2' );
    $item = $feed->add( 'item' );
    $module = $item->addModule( 'Content' );
    $module->encoded = 'text content';
    ?>

Parse example::

    <?php
    // $item is a feed item (ezcFeedEntryElement)
    $text = $item->Content->encoded->__toString();
    ?>


CreativeCommons
===============

Specifications
--------------

`CreativeCommons specifications`_


Feed elements
-------------

CreativeCommons-license
```````````````````````

Type: ezcFeedTextElement.

An URL to a license description.

Optional.

Can appear only once.

A list of possible licenses are found on the `CreativeCommons licenses`_ page,
but other licenses can be used as well.

Create example::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed( 'rss2' );
    $module = $feed->addModule( 'CreativeCommons' );
    $module->license = 'text content';
    ?>

Parse example::

    <?php
    // $item is a feed object (ezcFeed)
    $text = $feed->CreativeCommons->license->__toString();
    ?>


Item elements
-------------

CreativeCommons-item-license
````````````````````````````

Type: ezcFeedTextElement.

An URL to a license description.

Optional.

Can appear only once.

A list of possible licenses are found on the `CreativeCommons licenses`_ page,
but other licenses can be used as well.

Create example::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed( 'rss2' );
    $item = $feed->add( 'item' );
    $module = $item->addModule( 'CreativeCommons' );
    $module->license = 'text content';
    ?>

Parse example::

    <?php
    // $item is a feed item (ezcFeedEntryElement)
    $text = $item->CreativeCommons->license->__toString();
    ?>


DublinCore
==========

Specifications
--------------

`DublinCore specifications`_


Feed elements
-------------

DublinCore-contributor
``````````````````````

Type: array(ezcFeedPersonElement).

An entity responsible for making contributions to the resource. Usually the
name of a person, organization or service.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.

Create example::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed( 'rss2' );
    $module = $feed->addModule( 'DublinCore' );
    $element = $module->add( 'contributor' );
    $element->name = 'Contributor name';
    $element->language = 'no'; // optional language specification
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    foreach ( $feed->DublinCore->contributor as $element )
    {
        echo $element->name;
        echo $element->language;
    }
    ?>


DublinCore-coverage
```````````````````

Type: array(ezcFeedTextElement).

The spatial or temporal topic of the resource, the spatial applicability of
the resource, or the jurisdiction under which the resource is relevant. A
recommended practice is to use a controlled vocabulary such as `TGN`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-creator
``````````````````

Type: array(ezcFeedPersonElement).

An entity responsible for making the resource. Usually the name of a person or
organization.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-date
```````````````

Type: array(ezcFeedDateElement).

A point or period of time associated with an event in the lifecycle of the
resource. Usual date format is `ISO 8601`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-description
``````````````````````

Type: array(ezcFeedTextElement).

A description of the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-format
`````````````````

Type: array(ezcFeedTextElement).

The file format, physical medium, or dimensions of the resource. Recommended
best practices is to use a controlled vocabulary such as the list of
`Internet Media Types`_ (MIME).

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-identifier
`````````````````````

Type: array(ezcFeedIdElement).

An unambiguous reference to the resource within a given context.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-language
```````````````````

Type: array(ezcFeedTextElement).

A language of the resource. Recommended best practice is to use a controlled
vocabulary such as `RFC 4646`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-publisher
````````````````````

Type: array(ezcFeedPersonElement).

An entity responsible for making the resource available. Usually the name of a
person, organization or service.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore--relation
````````````````````

Type: array(ezcFeedTextElement).

A related resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-rights
`````````````````

Type: array(ezcFeedTextElement).

Information about rights held in and over the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-source
`````````````````

Type: array(ezcFeedSourceElement).

A related resource from which the described resource is derived.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-subject
``````````````````

Type: array(ezcFeedTextElement).

The topic of the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-title
````````````````

Type: array(ezcFeedTextElement).

The name given to the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-type
```````````````

Type: array(ezcFeedTextElement).

The nature or genre of the resource. Recommended best practice is to use a
controlled vocabulary such as the `DCMI Type Vocabulary`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


Item elements
-------------

DublinCore-item-contributor
```````````````````````````

Type: array(ezcFeedPersonElement).

An entity responsible for making contributions to the resource. Usually the
name of a person, organization or service.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.

Create example::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed();
    $item = $feed->add( 'item' );
    $module = $item->addModule( 'DublinCore' );
    $element = $module->add( 'contributor' );
    $element->name = 'Contributor name';
    $element->language = 'no'; // optional language specification
    ?>

Parse example::

    <?php
    // $item is a feed item (ezcFeedEntryElement) object
    foreach ( $item->DublinCore->contributor as $element )
    {
        echo $element->name;
        echo $element->language;
    }
    ?>


DublinCore-item-coverage
````````````````````````

Type: array(ezcFeedTextElement).

The spatial or temporal topic of the resource, the spatial applicability of
the resource, or the jurisdiction under which the resource is relevant. A
recommended practice is to use a controlled vocabulary such as `TGN`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-creator
```````````````````````

Type: array(ezcFeedPersonElement).

An entity responsible for making the resource. Usually the name of a person or
organization.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-date
````````````````````

Type: array(ezcFeedDateElement).

A point or period of time associated with an event in the lifecycle of the
resource. Usual date format is `ISO 8601`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-description
```````````````````````````

Type: array(ezcFeedTextElement).

A description of the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-format
``````````````````````

Type: array(ezcFeedTextElement).

The file format, physical medium, or dimensions of the resource. Recommended
best practices is to use a controlled vocabulary such as the list of
`Internet Media Types`_ (MIME).

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-identifier
``````````````````````````

Type: array(ezcFeedIdElement).

An unambiguous reference to the resource within a given context.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-language
````````````````````````

Type: array(ezcFeedTextElement).

A language of the resource. Recommended best practice is to use a controlled
vocabulary such as `RFC 4646`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-publisher
`````````````````````````

Type: array(ezcFeedPersonElement).

An entity responsible for making the resource available. Usually the name of a
person, organization or service.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-relation
````````````````````````

Type: array(ezcFeedTextElement).

A related resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-rights
``````````````````````

Type: array(ezcFeedTextElement).

Information about rights held in and over the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-source
``````````````````````

Type: array(ezcFeedSourceElement).

A related resource from which the described resource is derived.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-subject
```````````````````````

Type: array(ezcFeedTextElement).

The topic of the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-title
`````````````````````

Type: array(ezcFeedTextElement).

The name given to the resource.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


DublinCore-item-type
````````````````````

Type: array(ezcFeedTextElement).

The nature or genre of the resource. Recommended best practice is to use a
controlled vocabulary such as the `DCMI Type Vocabulary`_.

Optional.

Can appear multiple times.

Has an optional attribute *xml:lang* which specifies the language of the text.
A list of allowed languages can be found here: `RSS language codes`_. This
attribute is accessed as *language*.


Geo
===

Specifications
--------------

`Geo specifications`_


Feed elements
-------------


Item elements
-------------

Geo-item-alt
````````````

Type: ezcFeedTextElement.

Altitude in decimal meters above the local reference ellipsoid.

Optional.

Can appear only once.

Create example::

    <?php
    // use eZ Components autoload mechanism
    require_once 'tutorial_autoload.php';

    $feed = new ezcFeed( 'rss2' );
    $item = $feed->add( 'item' );
    $module = $item->addModule( 'Geo' );
    $module->alt = 509.2;
    ?>

Parse example::

    <?php
    $locations = array();

    // $feed is an ezcFeed object
    foreach ( $feed->item as $item )
    {
        if ( isset( $item->Geo ) )
        {
            $locations[] = array(
              'title' => $item->title->__toString(),
              'alt' => isset( $item->Geo->alt ) ? $item->Geo->alt->__toString() : null,
              'lat' => isset( $item->Geo->lat ) ? $item->Geo->lat->__toString() : null,
              'long' => isset( $item->Geo->long ) ? $item->Geo->long->__toString() : null
              );
        }
    }
    ?>


Geo-item-lat
````````````

Type: ezcFeedTextElement.

`WGS84`_ latitude on the globe as decimal degrees (eg. 25.03358300).

Optional.

Can appear only once.


Geo-item-long
`````````````

Type: ezcFeedTextElement.

`WGS84`_ longitude on the globe as decimal degrees (eg. 121.56430000).

Optional.

Can appear only once.


iTunes
======

Specifications
--------------

`iTunes specifications`_


Recommendations
---------------

- All values should be plain text (no markup or HTML)
- Values are limited to 255 characters, except for *summary* which can be up
  to 4000 characters
- Whitespace in values is significant, i.e. it will show in `iTunes`_, so
  don't add leading or trailing whitespace to your values
- CDATA sections are strongly discouraged


Feed elements
-------------

iTunes-author
`````````````

Type: ezcFeedPersonElement.

The author of a podcast.

Optional.

Can appear only once.

If missing, `iTunes`_ will use the |ezcFeed-author|_ element from the feed.


iTunes-block
````````````

Type: ezcFeedTextElement.

Prevents a podcast to appear in the podcast listing.

Optional.

Can appear only once.

Valid values are ``yes`` and ``no``, default ``no``.


iTunes-category
```````````````

Type: array(ezcFeedCategoryElement).

Categories for a podcast.

Optional.

Can appear multiple times. Categories can have sub-categories (*category* in
ezcFeedCategory).

The category name is specified in the attribute *text* (*term* in
ezcFeedCategoryElement).

The ampersands (``&``) in categories must be escaped to ``&amp;``.

Valid values for categories are found in the `iTunes categories`_ section of
the `iTunes specifications`_. A maximum of 3 categories are recommended.

Create example::

    <?php
    // $feed is an ezcFeed object
    $iTunes = $feed->addModule( 'iTunes' );

    // add the podcast in one or more categories + sub-categories
    $category = $iTunes->add( 'category' );
    $category->term = 'iTunes category';
    $subCategory = $category->add( 'category' );
    $subCategory->term = 'iTunes sub-category';
    ?>

Parse example::

    <?php
    // $feed is an ezcFeed object
    if ( isset( $feed->iTunes ) )
    {
        $iTunes = $feed->iTunes;
        if ( isset( $iTunes->category ) )
        {
            foreach ( $iTunes->category as $category )
            {
                echo $category->term;
                if ( isset( $category->category ) )
                {
                    foreach ( $category->category as $subCategory )
                    {
                        echo $subCategory->term;
                    }
                }
            }
        }
    }
    ?>


iTunes-explicit
```````````````

Type: ezcFeedTextElement.

Specifies if a podcast contains explicit content.

Optional.

Can appear only once.

Valid values are ``clean``, ``no`` and ``yes``, default ``no``.


iTunes-image
````````````

Type: ezcFeedImageElement.

A link to an image for the podcast.

Optional.

Can appear only once.

The URL to the image is specified in the attribute *href*.

If missing, `iTunes`_ will use the |ezcFeed-image|_ element from the feed.


iTunes-keywords
```````````````

Type: ezcFeedTextElement.

A list of keywords for a podcast.

Optional.

Can appear only once.

The keywords should be separated by commas. A maximum of 12 keywords is
recommended.


iTunes-new-feed-url
```````````````````

Type: ezcFeedLinkElement.

A new URL for the podcast.

Optional.

Can appear only once.

Accessed as *newfeedurl*.

Recommendation: the old URL of the podcast should redirect to the new URL.


iTunes-owner
````````````

Type: ezcFeedPersonElement.

The owner of the podcast.

Optional.

Can appear only once.

Has the sub-elements *email* and *name*.


iTunes-subtitle
```````````````

Type: ezcFeedTextElement.

Short description of the podcast.

Optional.

Can appear only once.


iTunes-summary
``````````````

Type: ezcFeedTextElement.

Longer description of a podcast.

Optional.

Can appear only once.

If missing, `iTunes`_ will use the |ezcFeed-description|_ element from the
feed.


Item elements
-------------

iTunes-item-author
``````````````````

Type: ezcFeedPersonElement.

The author of a podcast entry.

Optional.

Can appear only once.


iTunes-item-block
`````````````````

Type: ezcFeedTextElement.

Prevents a podcast entry to appear in the podcast listing.

Optional.

Can appear only once.

Valid values are ``yes`` and ``no``, default ``no``.


iTunes-item-duration
````````````````````

Type: ezcFeedTextElement.

The duration of a podcast entry.

Optional.

Can appear only once.

Can be specified as ``S``, ``M:SS``, ``MM:SS``, ``H:MM:SS`` or ``HH:MM:SS``
(H = hours, M = minutes, S = seconds).


iTunes-item-explicit
````````````````````

Type: ezcFeedTextElement.

Specifies if a podcast entry contains explicit content.

Optional.

Can appear only once.

Valid values are ``clean``, ``no`` and ``yes``, default ``no``.


iTunes-item-image
`````````````````

Type: ezcFeedImageElement.

A link to an image for the podcast entry.

Optional.

Can appear only once.

The URL to the image is specified in the attribute *href*.

NOTE: The `iTunes specifications`_ say that image is supported at
podcast-level only, but there are many podcasts using image at podcast entry
(item) level also, and there are software applications supporting that too.
Use *image* at item-level at your own risk, as some software applications
might not support it. The Feed component supports parsing and generating
feeds with image at both podcast-level and item-level.


iTunes-item-keywords
````````````````````

Type: ezcFeedTextElement.

A list of keywords for a podcast entry.

Optional.

Can appear only once.

The keywords should be separated by commas. A maximum of 12 keywords is
recommended.


iTunes-item-subtitle
````````````````````

Type: ezcFeedTextElement.

Short description of a podcast entry.

Optional.

Can appear only once.


iTunes-item-summary
```````````````````

Type: ezcFeedTextElement.

Longer description of a podcast entry.

Optional.

Can appear only once.

If missing, `iTunes`_ will use the |ezcFeed-item-description|_ element from
the feed.


=========
Resources
=========

Feed
====

- `RFC 4287`_ ATOM specifications.
- `RSS1 specifications`_.
- `RSS2 specifications`_.


Modules
=======

- `Content specifications`_.
- `CreativeCommons specifications`_.
- `DublinCore specifications`_.
- `Geo specifications`_.
- `iTunes specifications`_.


.. _RSS1 specifications: http://web.resource.org/rss/1.0/spec
.. _RSS2 specifications: http://www.rssboard.org/rss-specification
.. _RFC 4287: http://atompub.org/rfc4287.html

.. _Content specifications: http://purl.org/rss/1.0/modules/content/
.. _CreativeCommons specifications: http://backend.userland.com/creativeCommonsRssModule
.. _DublinCore specifications: http://dublincore.org/documents/dces/
.. _Geo specifications: http://www.w3.org/2003/01/geo/
.. _iTunes specifications: http://www.apple.com/itunes/store/podcaststechspecs.html

.. _RFC 3339: http://www.faqs.org/rfcs/rfc3339.html
.. _RFC 822: http://www.faqs.org/rfcs/rfc822.html
.. _PICS: http://www.w3.org/PICS/
.. _TGN: http://www.getty.edu/research/tools/vocabulary/tgn/index.html
.. _ISO 8601: http://www.w3.org/TR/NOTE-datetime
.. _Internet Media Types: http://www.iana.org/assignments/media-types/
.. _RFC 4646: http://www.faqs.org/rfcs/rfc4646.html
.. _DCMI Type Vocabulary: http://dublincore.org/documents/dcmi-type-vocabulary/
.. _RSS language codes: http://www.rssboard.org/rss-language-codes
.. _iTunes categories: http://www.apple.com/itunes/store/podcaststechspecs.html#categories
.. _iTunes: http://www.apple.com/itunes/
.. _CreativeCommons licenses: http://creativecommons.org/licenses/
.. _WGS84: http://en.wikipedia.org/wiki/WGS84
.. _date_format(): http://php.net/manual/en/function.date-format.php

.. _feed validator: http://validator.w3.org/feed/

.. |ezcFeed-author| replace:: author
.. |ezcFeed-category| replace:: category
.. |ezcFeed-cloud| replace:: cloud
.. |ezcFeed-contributor| replace:: contributor
.. |ezcFeed-copyright| replace:: copyright
.. |ezcFeed-description| replace:: description
.. |ezcFeed-docs| replace:: docs
.. |ezcFeed-generator| replace:: generator
.. |ezcFeed-icon| replace:: icon
.. |ezcFeed-id| replace:: id
.. |ezcFeed-image| replace:: image
.. |ezcFeed-item| replace:: item
.. |ezcFeed-language| replace:: language
.. |ezcFeed-link| replace:: link
.. |ezcFeed-published| replace:: published
.. |ezcFeed-rating| replace:: rating
.. |ezcFeed-skipDays| replace:: skipDays
.. |ezcFeed-skipHours| replace:: skipHours
.. |ezcFeed-textInput| replace:: textInput
.. |ezcFeed-title| replace:: title
.. |ezcFeed-ttl| replace:: ttl
.. |ezcFeed-updated| replace:: updated
.. |ezcFeed-webMaster| replace:: webMaster

.. |ezcFeed-item-author| replace:: author
.. |ezcFeed-item-category| replace:: category
.. |ezcFeed-item-comments| replace:: comments
.. |ezcFeed-item-content| replace:: content
.. |ezcFeed-item-contributor| replace:: contributor
.. |ezcFeed-item-copyright| replace:: copyright
.. |ezcFeed-item-description| replace:: description
.. |ezcFeed-item-enclosure| replace:: enclosure
.. |ezcFeed-item-id| replace:: id
.. |ezcFeed-item-link| replace:: link
.. |ezcFeed-item-published| replace:: published
.. |ezcFeed-item-source| replace:: source
.. |ezcFeed-item-title| replace:: title
.. |ezcFeed-item-updated| replace:: updated

.. |ATOM-author| replace:: author
.. |ATOM-category| replace:: category
.. |ATOM-contributor| replace:: contributor
.. |ATOM-entry| replace:: entry
.. |ATOM-generator| replace:: generator
.. |ATOM-icon| replace:: icon
.. |ATOM-id| replace:: id
.. |ATOM-link| replace:: link
.. |ATOM-logo| replace:: logo
.. |ATOM-rights| replace:: rights
.. |ATOM-subtitle| replace:: subtitle
.. |ATOM-title| replace:: title
.. |ATOM-updated| replace:: updated

.. |ATOM-entry-author| replace:: author
.. |ATOM-entry-category| replace:: category
.. |ATOM-entry-content| replace:: content
.. |ATOM-entry-contributor| replace:: contributor
.. |ATOM-entry-id| replace:: id
.. |ATOM-entry-link| replace:: link
.. |ATOM-entry-published| replace:: published
.. |ATOM-entry-rights| replace:: rights
.. |ATOM-entry-source| replace:: source
.. |ATOM-entry-summary| replace:: summary
.. |ATOM-entry-title| replace:: title
.. |ATOM-entry-updated| replace:: updated

.. |RSS1-about| replace:: about
.. |RSS1-description| replace:: description
.. |RSS1-image| replace:: image
.. |RSS1-item| replace:: item
.. |RSS1-link| replace:: link
.. |RSS1-textinput| replace:: textinput
.. |RSS1-title| replace:: title

.. |RSS1-item-about| replace:: about
.. |RSS1-item-description| replace:: description
.. |RSS1-item-link| replace:: link
.. |RSS1-item-title| replace:: title

.. |RSS2-cloud| replace:: cloud
.. |RSS2-category| replace:: category
.. |RSS2-copyright| replace:: copyright
.. |RSS2-description| replace:: description
.. |RSS2-docs| replace:: docs
.. |RSS2-generator| replace:: generator
.. |RSS2-image| replace:: image
.. |RSS2-item| replace:: item
.. |RSS2-language| replace:: language
.. |RSS2-lastBuildDate| replace:: lastBuildDate
.. |RSS2-link| replace:: link
.. |RSS2-managingEditor| replace:: managingEditor
.. |RSS2-pubDate| replace:: pubDate
.. |RSS2-rating| replace:: rating
.. |RSS2-skipDays| replace:: skipDays
.. |RSS2-skipHours| replace:: skipHours
.. |RSS2-textInput| replace:: textInput
.. |RSS2-title| replace:: title
.. |RSS2-ttl| replace:: ttl
.. |RSS2-webMaster| replace:: webMaster

.. |RSS2-item-author| replace:: author
.. |RSS2-item-category| replace:: category
.. |RSS2-item-comments| replace:: comments
.. |RSS2-item-description| replace:: description
.. |RSS2-item-enclosure| replace:: enclosure
.. |RSS2-item-guid| replace:: guid
.. |RSS2-item-link| replace:: link
.. |RSS2-item-pubDate| replace:: pubDate
.. |RSS2-item-source| replace:: source
.. |RSS2-item-title| replace:: title


..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79 nocin