Zeta Components - high quality PHP components

• Tutorial
• API
• Specifications

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.

Overview

Feeds equivalence

Feed elements

! = 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:

• author

• description

• id

• at least one item with all required elements

• link

• title

• updated

Item elements

! = 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:

• author

• description

• id

• link

• title

• updated

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

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed();
7. $author = $feed->add( 'author' );
8. $author->name = "Indiana Jones";
9. $author->email = "indy@example.com";
11. $feed->description = "This feed shows Indiana Jones movie releases";
12. $feed->id = "http://indy.example.com/";
14. $link = $feed->add( 'link' );
15. $link->href = "http://indy.example.com/";
17. $feed->title = "Indiana Jones movie releases";
18. $feed->updated = time();
20. // add a feed item
21. $item = $feed->add( 'item' );
23. $author = $item->add( 'author' );
24. $author->name = "Indiana Jones";
25. $author->email = "indy@example.com";
27. $item->description = "Indy meets ****** and has a hell of an adventure";
28. $item->id = "http://indy.example.com/4";
30. $link = $item->add( 'link' );
31. $link->href = "http://indy.example.com/4";
33. $item->title = "Indiana Jones and the Kingdom of the Crystal Skull";
34. $item->updated = time();
36. $atom = $feed->generate( 'atom' );
37. $rss1 = $feed->generate( 'rss1 );
38. $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:

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

The resulting ATOM XML element will be:

The resulting RSS2 XML element will be:

Parse example:

1. <?php
2. $authors = array();
4. // $feed is an ezcFeed object
5. if ( isset( $feed->author ) )
6. {
7.     foreach ( $feed->author as $author )
8.     {
9.         $authors[] = array(
10.           'name' => isset( $author->name ) ? $author->name : null,
11.           'uri' => isset( $author->uri ) ? $author->uri : null, // ATOM only
12.           'email' => isset( $author->email ) ? $author->email : null // ATOM only
13.           );
14.     }
15. }
?>

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:

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

Parse example:

1. <?php
2. $categories = array();
4. // $feed is an ezcFeed object
5. if ( isset( $feed->category ) )
6. {
7.     foreach ( $feed->category as $category )
8.     {
9.         $categories[] = array(
10.           'term' => isset( $category->term ) ? $category->term : null,
11.           'scheme' => isset( $category->scheme ) ? $category->scheme : null,
12.               // scheme = RSS2 domain
13.           'label' => isset( $category->label ) ? $category->label : null // ATOM only
14.           );
15.     }
16. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->cloud ) )
4. {
5.     $cloud = $feed->cloud;
6.     $domain = isset( $cloud->domain ) ? $cloud->domain : null;
7.     $port = isset( $cloud->port ) ? $cloud->port : null;
8.     $path = isset( $cloud->path ) ? $cloud->path : null;
9.     $procedure = isset( $cloud->registerProcedure ) ? $cloud->registerProcedure : null;
10.     $protocol = isset( $cloud->protocol ) ? $cloud->protocol : null;
11. }
?>

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:

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

Parse example:

1. <?php
2. $contributors = array();
4. // $feed is an ezcFeed object
5. if ( isset( $feed->contributor ) )
6. {
7.     foreach ( $feed->contributor as $contributor )
8.     {
9.         $contributors[] = array(
10.           'name' => isset( $contributor->name ) ? $contributor->name : null,
11.           'uri' => isset( $contributor->uri ) ? $contributor->uri : null,
12.           'email' => isset( $contributor->email ) ? $contributor->email : null
13.           );
14.     }
15. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->copyright ) )
4. {
5.     $copyrightElement = $feed->copyright;
6.     $copyright = $copyrightElement->text;
7.     $type = isset( $copyrightElement->type ) ? $copyrightElement->type : null;  // ATOM only
8.     $language = isset( $copyrightElement->language ) ? $copyrightElement->language : null;  // ATOM only
9. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->description ) )
4. {
5.     $descriptionElement = $feed->description;
6.     $description = $descriptionElement->text;
7.     $type = isset( $descriptionElement->type ) ? $descriptionElement->type : null; // ATOM only
8.     $language = isset( $descriptionElement->language ) ? $descriptionElement->language : null; // ATOM only
9. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->generator ) )
4. {
5.     $name = isset( $feed->generator->name ) ? $feed->generator->name : null;
6.     $url = isset( $feed->generator->url ) ? $feed->generator->url : null; // ATOM only
7.     $version = isset( $feed->generator->version ) ? $feed->generator->version : null; // ATOM only
8. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example (RSS1 and RSS2):

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->image ) )
4. {
5.     $image = $feed->image;
6.     $link = isset( $image->link ) ? $image->link : null;
7.     $url = isset( $image->url ) ? $image->url : null; // RSS1 and RSS2 only
8.     $title = isset( $image->title ) ? $image->title : null; // RSS1 and RSS2 only
9.     $width = isset( $image->width ) ? $image->width : null; // RSS2 only
10.     $height = isset( $image->height ) ? $image->height : null; // RSS2 only
11.     $description = isset( $image->description ) ? $image->description : null; // RSS2 only
12.     $about = isset( $image->about ) ? $image->about : null; // RSS1 only
13. }
?>

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:

1. <?php
2. // $feed is an ezcFeed object
3. $item = $feed->add( 'item' );
5. // set $item properties, for example:
6. $item->title = 'Item title';
?>

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. foreach ( $feed->item as $item )
4. {
5.     // get $item properties, for example:
6.     $title = isset( $item->title ) ? $item->title->__toString() : null;
7. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

1. <?php
2. $links = array();
4. // $feed is an ezcFeed object
5. foreach ( $feed->link as $link )
6. {
7.     $links[] = array(
8.       'href' => isset( $link->href ) ? $link->href : null,
9.       'rel' => isset( $link->rel ) ? $link->rel : null, // ATOM only
10.       'type' => isset( $link->type ) ? $link->type : null, // ATOM only
11.       'hreflang' => isset( $link->hreflang ) ? $link->hreflang : null, // ATOM only
12.       'title' => isset( $link->title ) ? $link->title : null, // ATOM only
13.       'length' => isset( $link->length ) ? $link->length : null, // ATOM only
14.       );
15. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

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

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:

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

Parse example:

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

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:

1. <?php
2. // $feed is an ezcFeed object
3. $textInput = $feed->add( 'textInput' );
4. $textInput->title = 'Text input title';
5. $textInput->description = 'Text input description';
6. $textInput->name = 'Text input name';
7. $textInput->link = 'Text input link';
8. $textInput->about = 'Text input link'; // RSS1 only, ignored in RSS2
?>

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->textInput ) )
4. {
5.     $textInput = $feed->textInput;
6.     $title = isset( $textInput->title ) ? $textInput->title : null;
7.     $description = isset( $textInput->description ) ? $textInput->description : null;
8.     $name = isset( $textInput->name ) ? $textInput->name : null;
9.     $link = isset( $textInput->link ) ? $textInput->link : null;
10.     $about = isset( $textInput->about ) ? $textInput->about : null; // RSS1 only
11. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->title ) )
4. {
5.     $element = $feed->title;
6.     $title = isset( $element->text ) ? $element->text : null;
7.     $type = isset( $element->type ) ? $element->type : null; // ATOM only
8.     $language = isset( $element->language ) ? $element->language : null; // ATOM only
9. }
?>

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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. $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:

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

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->webMaster ) )
4. {
5.     $name = isset( $feed->webMaster->name ) ? $feed->webMaster->name : null;
6. }
?>

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:

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

The resulting ATOM XML element will be:

The resulting RSS2 XML element will be:

Parse example:

1. <?php
2. $authors = array();
4. // $item is an ezcFeedEntryElement object
5. if ( isset( $item->author ) )
6. {
7.     foreach ( $item->author as $author )
8.     {
9.         $authors[] = array(
10.           'name' => isset( $author->name ) ? $author->name : null,
11.           'uri' => isset( $author->uri ) ? $author->uri : null, // ATOM only
12.           'email' => isset( $author->email ) ? $author->email : null // ATOM only
13.           );
14.     }
15. }
?>

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:

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

Parse example:

1. <?php
2. $categories = array();
4. // $item is an ezcFeedEntryElement object
5. if ( isset( $item->category ) )
6. {
7.     foreach ( $item->category as $category )
8.     {
9.         $categories[] = array(
10.           'term' => isset( $category->term ) ? $category->term : null,
11.           'scheme' => isset( $category->scheme ) ? $category->scheme : null, // scheme = RSS2 domain
12.           'label' => isset( $category->label ) ? $category->label : null // ATOM only
13.           );
14.     }
15. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. $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 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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. if ( isset( $item->content ) )
4. {
5.     $contentElement = $item->content;
6.     $content = $descriptionElement->text;
7.     $type = isset( $contentElement->type ) ? $contentElement->type : null;
8.     $language = isset( $contentElement->language ) ? $contentElement->language : null;
9.     $src = isset( $contentElement->src ) ? $contentElement->src : null;
10. }
?>

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:

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

Parse example:

1. <?php
2. $contributors = array();
4. // $item is an ezcFeedEntryElement object
5. if ( isset( $item->contributor ) )
6. {
7.     foreach ( $item->contributor as $contributor )
8.     {
9.         $contributors[] = array(
10.           'name' => isset( $contributor->name ) ? $contributor->name : null,
11.           'uri' => isset( $contributor->uri ) ? $contributor->uri : null,
12.           'email' => isset( $contributor->email ) ? $contributor->email : null
13.           );
14.     }
15. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. if ( isset( $item->copyright ) )
4. {
5.     $copyrightElement = $item->copyright;
6.     $copyright = $copyrightElement->text;
7.     $type = isset( $copyrightElement->type ) ? $copyrightElement->type : null; // ATOM only
8.     $language = isset( $copyrightElement->language ) ? $copyrightElement->language : null; // ATOM only
9. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. if ( isset( $item->description ) )
4. {
5.     $desc = $item->description;
6.     $description = $desc->text;
7.     $type = isset( $desc->type ) ? $desc->type : null; // ATOM only
8.     $language = isset( $desc->language ) ? $desc->language : null; // ATOM only
9. }
?>

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 link elements with the attribute rel="enclosure".

Can appear only once in RSS2 and multiple times in ATOM (as link).

Has 3 required attributes: url, length, type.

Create example:

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

RSS2 output:

ATOM output:

Parse example (RSS2):

1. <?php
2. // $item is an ezcFeedEntryElement object
3. if ( isset( $item->enclosure ) )
4. {
5.     $enclosure = $item->enclosure[0];
6.     $url = isset( $enclosure->url ) ? $enclosure->url : null;
7.     $length = isset( $enclosure->length ) ? $enclosure->length : null;
8.     $type = isset( $enclosure->type ) ? $enclosure->type : null;
9. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. if ( isset( $item->id ) )
4. {
5.     $id = isset( $feed->id->id ) : $feed->id->id : null;
6.     $isPermLink = isset( $feed->id->isPermLink ) ? $feed->id->isPermLink : null; // RSS2 only
7. }
?>

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 enclosure.

These attributes are ignored for RSS1 and RSS2 feeds.

Create example:

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

Parse example:

1. <?php
2. $links = array();
4. // $item is an ezcFeedEntryElement object
5. foreach ( $item->link as $link )
6. {
7.     $links[] = array(
8.       'href' => isset( $link->href ) ? $link->href : null,
9.       'rel' => isset( $link->rel ) ? $link->rel : null, // ATOM only
10.       'type' => isset( $link->type ) ? $link->type : null, // ATOM only
11.       'hreflang' => isset( $link->hreflang ) ? $link->hreflang : null, // ATOM only
12.       'title' => isset( $link->title ) ? $link->title : null, // ATOM only
13.       'length' => isset( $link->length ) ? $link->length : null, // ATOM only
14.       );
15. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. $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 item element. RSS2 feeds have the attributes source and url.

Can appear only once.

Create example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. $source = $item->add( 'source' );
4. $source->source = 'Source feed name'; // RSS2 only, ignored for ATOM
5. $source->url = 'http://source.feed.url/'; // RSS2 only, ignored for ATOM
7. $author = $source->add( 'author' ); // ATOM only, ignored for RSS2
8. $author->name = 'Author of the source feed';
9. $author->email = 'Email address of the author of the source feed';
11. // more elements which pertain to ATOM feeds can be added
?>

Parse example:

1. <?php
2. // $item is an ezcFeedSourceElement object
3. if ( isset( $item->source ) )
4. {
5.     $source = $item->source;
7.     $rss2SourceName = isset( $source->source ) ? $source->source : null;
8.     $rss2SourceUrl = isset( $source->url ) ? $source->url : null;
10.     $atomSourceTitle = isset( $source->title ) ? $source->title->__toString() : null;
11. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. if ( isset( $item->title ) )
4. {
5.     $titleElement = $item->title;
6.     $title = $titleElement->text;
7.     $type = isset( $titleElement->type ) ? $titleElement->type : null; // ATOM only
8.     $language = isset( $titleElement->language ) ? $titleElement->language : null; // ATOM only
9. }
?>

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:

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

Parse example:

1. <?php
2. // $item is an ezcFeedEntryElement object
3. $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 rights, subtitle, title, content, rights, summary, title).

• xml:base may be used to control how relative URIs are resolved (not recommended)

Sample ATOM feed:

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:

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:

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:

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 summary is absent). Can be substituted with 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:

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 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 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 entry element:

• author

• category

• contributor

• rights

• subtitle

• generator

• icon

• id

• logo

• link

• title

• 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:

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:

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:

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:

This will be rendered in XML as:

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:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed( 'rss2' );
6. $item = $feed->add( 'item' );
7. $module = $item->addModule( 'Content' );
8. $module->encoded = 'text content';
?>

Parse example:

1. <?php
2. // $item is a feed item (ezcFeedEntryElement)
3. $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:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed( 'rss2' );
6. $module = $feed->addModule( 'CreativeCommons' );
7. $module->license = 'text content';
?>

Parse example:

1. <?php
2. // $item is a feed object (ezcFeed)
3. $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:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed( 'rss2' );
6. $item = $feed->add( 'item' );
7. $module = $item->addModule( 'CreativeCommons' );
8. $module->license = 'text content';
?>

Parse example:

1. <?php
2. // $item is a feed item (ezcFeedEntryElement)
3. $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:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed( 'rss2' );
6. $module = $feed->addModule( 'DublinCore' );
7. $element = $module->add( 'contributor' );
8. $element->name = 'Contributor name';
9. $element->language = 'no'; // optional language specification
?>

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. foreach ( $feed->DublinCore->contributor as $element )
4. {
5.     echo $element->name;
6.     echo $element->language;
7. }
?>

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:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed();
6. $item = $feed->add( 'item' );
7. $module = $item->addModule( 'DublinCore' );
8. $element = $module->add( 'contributor' );
9. $element->name = 'Contributor name';
10. $element->language = 'no'; // optional language specification
?>

Parse example:

1. <?php
2. // $item is a feed item (ezcFeedEntryElement) object
3. foreach ( $item->DublinCore->contributor as $element )
4. {
5.     echo $element->name;
6.     echo $element->language;
7. }
?>

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:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed( 'rss2' );
6. $item = $feed->add( 'item' );
7. $module = $item->addModule( 'Geo' );
8. $module->alt = 509.2;
?>

Parse example:

1. <?php
2. $locations = array();
4. // $feed is an ezcFeed object
5. foreach ( $feed->item as $item )
6. {
7.     if ( isset( $item->Geo ) )
8.     {
9.         $locations[] = array(
10.           'title' => $item->title->__toString(),
11.           'alt' => isset( $item->Geo->alt ) ? $item->Geo->alt->__toString() : null,
12.           'lat' => isset( $item->Geo->lat ) ? $item->Geo->lat->__toString() : null,
13.           'long' => isset( $item->Geo->long ) ? $item->Geo->long->__toString() : null
14.           );
15.     }
16. }
?>

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 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 &.

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

Create example:

1. <?php
2. // $feed is an ezcFeed object
3. $iTunes = $feed->addModule( 'iTunes' );
5. // add the podcast in one or more categories + sub-categories
6. $category = $iTunes->add( 'category' );
7. $category->term = 'iTunes category';
8. $subCategory = $category->add( 'category' );
9. $subCategory->term = 'iTunes sub-category';
?>

Parse example:

1. <?php
2. // $feed is an ezcFeed object
3. if ( isset( $feed->iTunes ) )
4. {
5.     $iTunes = $feed->iTunes;
6.     if ( isset( $iTunes->category ) )
7.     {
8.         foreach ( $iTunes->category as $category )
9.         {
10.             echo $category->term;
11.             if ( isset( $category->category ) )
12.             {
13.                 foreach ( $category->category as $subCategory )
14.                 {
15.                     echo $subCategory->term;
16.                 }
17.             }
18.         }
19.     }
20. }
?>

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 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 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 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.