Path

ez components / documentation / api reference / 2009.1.2 / feed


eZ Components 2009.1.2

Feed: ezcFeed

[ Tutorial ] [ Specifications ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcFeed

Class defining a feed. [source]
A feed has a type (eg. RSS1, RSS2 or ATOM). The feed type defines which processor is used to parse and generate that type.
The following feed processors are supported by the Feed component: A new processor can be defined by creating a class which extends the class ezcFeedProcessor and implements the interface ezcFeedParser. The new class needs to be added to the supported feed types list by calling the function registerFeed.
The following modules are supported by the Feed component: A new module can be defined by creating a class which extends the class ezcFeedModule. The new class needs to be added to the supported modules list by calling registerModule.
A feed object can be created in different ways:
  • by calling the constructor (with the optional feed type). Example:
1.   $feed new ezcFeed();
  • by parsing an existing XML file or URL. The feed type of the resulting ezcFeed object will be autodetected. Example:
1.   $feed ezcFeed::parse'http://www.example.com/rss2.xml' )// URL
2.     $feed ezcFeed::parse'http://username:password@www.example.com/rss2.xml' )// URL with HTTP authentication
2.     $feed ezcFeed::parse'/tmp/rss2.xml' )// local file
  • by parsing an XML document stored in a string variable. The feed type of the resulting ezcFeed object will be autodetected. Example:
1.   $feed ezcFeed::parseContent$xmlString );
Parsing a feed (in the following examples $feed is an existing ezcFeed object):
  • get a value from the feed object. Example:
1.  $title $feed->title->__toString();
  • iterate over the items in the feed. Example:
1.  <?php
2.  // retrieve the titles from the feed items
3.   foreach $feed->item as $item )
4.  {
5.      $titles[$item->title->__toString();
6.  }
  • parse a module. Example of parsing the Geo module (ezcFeedGeoModule):
 1.  <?php
 2.  $locations array();
 3.  foreach $feed->item as $item )
 4.  {
 5.      if isset$item->Geo ) )
 6.      {
 7.          $locations[array(
 8.              'title' => $item->title->__toString(),
 9.              'alt' => isset$item->Geo->alt $item->Geo->alt->__toString(null,
10.              'lat' => isset$item->Geo->lat $item->Geo->lat->__toString(null,
11.              'long' => isset$item->Geo->long $item->Geo->long->__toString(null
12.              );
13.      }
14.  }
15.  ?>
  • iterate over the loaded modules in a feed item. Example:
1.  <?php
2.  // display the names and namespaces of the modules loaded in the feed item $item
3.   foreach $item->getModules(as $moduleName => $module )
4.  {
5.      echo $moduleName ':' $module->getNamespace();
6.  }
7.  ?>
Generating a feed:
  • create a feed object. Example:
1.  $feed new ezcFeed();
  • set a value to the feed object. Example:
1.  $feed->title 'News';
  • add a new item to the feed. Example:
1.  <?php
2.  $item $feed->add'item' );
3.  $item->title 'Item title';
4.  ?>
  • add a new module to the feed item. Example:
1.  <?php
2.  $item $feed->add'item' );
3.  $module $item->addModule'Content' );
4.  $content->encoded 'text content which will be encoded';
5.  ?>
  • generate an XML document from the ezcFeed object. The result string should be saved to a file, and a link to a file made accessible to users of the application. Example:
1.  <?php
2.  $xmlAtom $feed->generate'atom' );
3.  $xmlRss1 $feed->generate'rss1' );
4.  $xmlRss2 $feed->generate'rss2' );
5.  ?>
Note: Assigning values to feed elements should be done in a way that will not break the resulting XML document. In other words, encoding of special characters to HTML entities is not done by default, and the developer is responsible with calling htmlentities() himself when assigning values to feed elements. Example: if the feed title contains the "&" character, it is the responsability of the developer to encode it properly as "&amp;".
Example of creating a feed with a user-defined type:
1.  <?php
2.  ezcFeed::registerFeed'opml''myOpmlHandler');
3.  
4.  $feed new ezcFeed();
5.  // add properties to $feed
6.  
6.  
7.  $xml $feed->generate'opml' );
8.  ?>
In the above example, myOpmlHandler extends ezcFeedProcessor and implements ezcFeedParser.
Example of creating a feed with a user-defined module:
 1.  <?php
 2.  ezcFeed::registerModule'Slash''mySlashHandler''slash');
 3.  
 4.  $feed new ezcFeed();
 5.  $item $feed->add'item' );
 6.  $slash $item->addModule'Slash' );
 7.  // add properties for the Slash module to $slash
 8.  
 8.  
 9.  $xml $feed->generate'rss2' )// or the feed type which is needed
10.   ?>
In the above example mySlashHandler extends ezcFeedModule.

Constants

GENERATOR_URI = 'http://ezcomponents.org/docs/tutorials/Feed' The uri of the feed generator, to be included in the generated feeds.
GENERATOR_VERSION = '1.2.1' The version of the feed generator, to be included in the generated feeds.

Properties

array(ezcFeedPersonElement) read/write  $author
Author(s) of the feed. Equivalents: ATOM-author (required, multiple), RSS1-none, RSS2-managingEditor (optional, recommended, single).
array(ezcFeedCategoryElement) read/write  $category
Categories for the feed. Equivalents: ATOM-category (optional, multiple), RSS1-none, RSS2-category (optional, multiple).
ezcFeedCloudElement read/write  $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. Equivalents: ATOM-none, RSS1-none, RSS2-cloud (optional, not recommended, single).
array(ezcFeedPersonElement) read/write  $contributor
Contributor(s) for the feed. Equivalents: ATOM-contributor (optional, not recommended, multiple), RSS1-none, RSS2-none.
ezcFeedTextElement read/write  $copyright
Copyright information for the feed. Equivalents: ATOM-rights (optional, single), RSS1-none, RSS2-copyright (optional, single).
ezcFeedTextElement read/write  $description
A short description of the feed. Equivalents: ATOM-subtitle (required, single), RSS1-description (required, single), RSS2-description (required, single).
ezcFeedTextElement read/write  $docs
An URL that points to the documentation for the format used in the feed file. Equivalents: ATOM-none, RSS1-none, RSS2-docs (optional, not recommended, single) - usual value is http://www.rssboard.org/rss-specification.
ezcFeedGeneratorElement read/write  $generator
Indicates the software used to generate the feed. Equivalents: ATOM-generator (optional, single), RSS1-none, RSS2-generator (optional, single).
ezcFeedImageElement read/write  $icon
An icon for a feed, similar with favicon.ico for websites. Equivalents: ATOM-icon (optional, not recommended, single), RSS1-none, RSS2-none.
ezcFeedIdElement read/write  $id
A universally unique and permanent identifier for a feed. For example, it can be an Internet domain name. Equivalents: ATOM-id (required, single), RSS1-about (required, single), RSS2-none.
ezcFeedImageElement read/write  $image
An image associated with the feed. Equivalents: ATOM-logo (optional, single), RSS1-image (optional, single), RSS2-image (optional, single).
array(ezcFeedEntryElement) read  $item
Feed items (entries). Equivalents: ATOM-entry (optional, recommended, multiple), RSS1-item (required, multiple), RSS2-item (required, multiple).
ezcFeedTextElement read/write  $language
The language for the feed. Equivalents: ATOM-xml:lang attribute for title, description, copyright, content, comments (optional, single) - accessed as language through ezcFeed, RSS1-none, RSS2-language (optional, single).
array(ezcFeedLinkElement) read/write  $link
URLs to the HTML websites corresponding to the channel. Equivalents: ATOM-link (required one link with rel='self', multiple), RSS1-link (required, single), RSS2-link (required, single).
ezcFeedDateElement read/write  $published
The time the feed was published. Equivalents: ATOM-none, RSS1-none, RSS2-pubDate (optional, not recommended, single).
ezcFeedTextElement read/write  $rating
The PICS rating for the channel. Equivalents: ATOM-none, RSS1-none, RSS2-rating (optional, not recommended, single).
ezcFeedSkipDaysElement read/write  $skipDays
A hint for aggregators telling them which days they can skip when reading the feed. Equivalents: ATOM-none, RSS1-none, RSS2-skipDays (optional, not recommended, single).
ezcFeedSkipHoursElement read/write  $skipHours
A hint for aggregators telling them which hours they can skip when reading the feed. Equivalents: ATOM-none, RSS1-none, RSS2-skipHours (optional, not recommended, single).
ezcFeedTextInputElement read/write  $textInput
Specifies a text input box that can be displayed with the feed. Equivalents: ATOM-none, RSS1-textinput (optional, not recommended, single), RSS2-textInput (optional, not recommended, single).
ezcFeedTextElement read/write  $title
Human readable title for the feed. For example, it can be the same as the website title. Equivalents: ATOM-title (required, single), RSS1-title (required, single), RSS2-title (required, single).
ezcFeedTextElement read/write  $ttl
Number of minutes that indicates how long a channel can be cached before refreshing from the source. Equivalents: ATOM-none, RSS1-none, RSS2-ttl (optional, not recommended, single).
ezcFeedDateElement read/write  $updated
The last time the feed was updated. Equivalents: ATOM-updated (required, single), RSS1-none, RSS2-lastBuildDate (optional, recommended, single).
ezcFeedPersonElement read/write  $webMaster
The email address of the webmaster responsible for the feed. Equivalents: ATOM-none, RSS1-none, RSS2-webMaster (optional, not recommended, single).

Method Summary

public ezcFeed __construct( [$type = null] )
Creates a new feed object.
public ezcFeedElement|null add( $name )
Adds a new ezcFeedElement element with name $name and returns it.
public ezcFeedModule addModule( $name )
Adds a new module to this item and returns it.
public string generate( [$type = null] )
Generates and returns an XML document of type $type from the current object.
public string getContentType( )
Returns the feed content type of this feed object (eg. 'application/rss+xml').
public string getFeedType( )
Returns the feed type of this feed object (eg. 'rss2').
public ezcFeedModule getModule( $name )
Returns the loaded module $name.
public array(ezcFeedModule) getModules( )
Returns an array with all the modules loaded at feed-level.
public static array(string=>string) getSupportedModules( )
Returns the supported feed modules.
public static array(string=>string) getSupportedModulesPrefixes( )
Returns the supported feed modules prefixes.
public static array(string) getSupportedTypes( )
Returns the supported feed types.
public bool hasModule( $name )
Returns true if the module $name is loaded, false otherwise.
public static ezcFeed parse( $uri )
Parses the XML document in the $uri and returns an ezcFeed object with the type autodetected from the XML document.
public static ezcFeed parseContent( $content )
Parses the XML document stored in $content and returns an ezcFeed object with the type autodetected from the XML document.
public static void registerFeed( $name, $class )
Adds the feed type $name to the supported list of feed types.
public static void registerModule( $name, $class, $namespacePrefix )
Adds the module $name to the supported list of modules.
public void setModule( $name, $module )
Associates the module $module with the name $name.
public static void unregisterFeed( $name )
Removes a previously registered feed type from the list of supported feed types.
public static void unregisterModule( $name )
Removes a previously registered module from the list of supported modules.

Methods

__construct

ezcFeed __construct( [string $type = null] )
Creates a new feed object.
The $type value is used when calling generate() without specifying a feed type to output.

Parameters

Name Type Description
$type string The type of feed to create

Throws

ClassDescription
ezcFeedUnsupportedTypeException if the feed type $type is not supported

add

ezcFeedElement|null add( string $name )
Adds a new ezcFeedElement element with name $name and returns it.

Parameters

Name Type Description
$name string The element name

Throws

ClassDescription
ezcFeedUnsupportedElementException if the element $name is not supported

addModule

ezcFeedModule addModule( string $name )
Adds a new module to this item and returns it.

Parameters

Name Type Description
$name string The name of the module to add

generate

string generate( [string $type = null] )
Generates and returns an XML document of type $type from the current object.
If the type was defined when creating the ezcFeed object, then that type will be used if no type is specified when calling generate().
If no type was specified when calling the constructor and no type was specified when calling generate then an exception will be thrown.

Parameters

Name Type Description
$type string The feed type to generate

Throws

ClassDescription
ezcFeedUnsupportedTypeException if the feed type $type is not supported

getContentType

string getContentType( )
Returns the feed content type of this feed object (eg. 'application/rss+xml').

getFeedType

string getFeedType( )
Returns the feed type of this feed object (eg. 'rss2').

getModule

ezcFeedModule getModule( string $name )
Returns the loaded module $name.

Parameters

Name Type Description
$name string The name of the module to return

getModules

array(ezcFeedModule) getModules( )
Returns an array with all the modules loaded at feed-level.

getSupportedModules

array(string=>string) getSupportedModules( )
Returns the supported feed modules.
The array returned is (default):
1.  array(
2.     'Content'         => 'ezcFeedContentModule',
3.     'CreativeCommons' => 'ezcFeedCreativeCommonsModule',
4.     'DublinCore'      => 'ezcFeedDublinCoreModule',
5.     'Geo'             => 'ezcFeedGeoModule',
6.     'iTunes'          => 'ezcFeedITunesModule'
7.  );
If the function registerModule was used to add another supported module type to ezcFeed, it will show up in the returned array as well.

getSupportedModulesPrefixes

array(string=>string) getSupportedModulesPrefixes( )
Returns the supported feed modules prefixes.
The array returned is (default):
1.  array(
2.     'content'         => 'Content',
3.     'creativeCommons' => 'CreativeCommons',
4.     'dc'              => 'DublinCore',
5.     'geo'             => 'Geo',
6.     'itunes'          => 'iTunes'
7.  );
If the function registerModule was used to add another supported module type to ezcFeed, it will show up in the returned array as well.

getSupportedTypes

array(string) getSupportedTypes( )
Returns the supported feed types.
The array returned is (default):
1.  array(
2.     'rss1' => 'ezcFeedRss1',
3.     'rss2' => 'ezcFeedRss2',
4.     'atom' => 'ezcFeedAtom'
5.  );
If the function registerFeed was used to add another supported feed type to ezcFeed, it will show up in the returned array as well.

hasModule

bool hasModule( string $name )
Returns true if the module $name is loaded, false otherwise.

Parameters

Name Type Description
$name string The name of the module to check if loaded for this item

parse

ezcFeed parse( string $uri )
Parses the XML document in the $uri and returns an ezcFeed object with the type autodetected from the XML document.
Example of parsing an XML document stored at an URL:
1.  $feed ezcFeed::parse'http://www.example.com/rss2.xml' );
Example of parsing an XML document protected with HTTP authentication:
1.  $feed ezcFeed::parse'http://username:password@www.example.com/rss2.xml' );
If trying to parse an XML document protected with HTTP authentication without providing a valid username and password, the exception ezcFeedParseErrorException will be thrown.
Example of parsing an XML document stored in a local file:
1.  $feed ezcFeed::parse'/tmp/feed.xml' );

Parameters

Name Type Description
$uri string An URI which stores an XML document

Throws

ClassDescription
ezcBaseFileNotFoundException If the XML file at $uri could not be found.
ezcFeedParseErrorException If the content at $uri is not a valid XML document.

parseContent

ezcFeed parseContent( string $content )
Parses the XML document stored in $content and returns an ezcFeed object with the type autodetected from the XML document.
Example of parsing an XML document stored in a string:
1.  // $xmlString contains a valid XML string
2.   $feed ezcFeed::parseContent$xmlString );

Parameters

Name Type Description
$content string A string variable which stores an XML document

Throws

ClassDescription
ezcFeedParseErrorException If $content is not a valid XML document.

registerFeed

void registerFeed( string $name, string $class )
Adds the feed type $name to the supported list of feed types.
After registering a feed type, it can be used to create or parse feed documents.
Example of creating a feed with a user-defined type:
1.  ezcFeed::registerFeed'opml''myOpmlHandler');
2.  
3.  $feed new ezcFeed'opml' );
3.  // add properties for the Opml feed type to $feed
In the above example, myOpmlHandler extends ezcFeedProcessor and implements ezcFeedParser.

Parameters

Name Type Description
$name string The feed type (eg. 'opml' )
$class string The handler class for this feed type (eg. 'myOpmlHandler')

registerModule

void registerModule( string $name, string $class, string $namespacePrefix )
Adds the module $name to the supported list of modules.
After registering a module, it can be used to create or parse feed documents.
Example of creating a feed with a user-defined module:
1.  ezcFeed::registerModule'Slash''mySlashHandler''slash');
2.  
3.  $feed new ezcFeed'rss2' );
4.  $item $feed->add'item' );
5.  $slash $item->addModule'Slash' );
5.  // add properties for the Slash module to $slash

Parameters

Name Type Description
$name string The module name (eg. 'Slash' )
$class string The handler class for this module (eg. 'mySlashHandler')
$namespacePrefix string The XML namespace prefix for this module (eg. 'slash')

setModule

void setModule( string $name, ezcFeedModule $module )
Associates the module $module with the name $name.

Parameters

Name Type Description
$name string The name of the module associate
$module ezcFeedModule The module to set under the name $name

unregisterFeed

void unregisterFeed( string $name )
Removes a previously registered feed type from the list of supported feed types.

Parameters

Name Type Description
$name string The name of the feed type to remove (eg. 'opml')

unregisterModule

void unregisterModule( string $name )
Removes a previously registered module from the list of supported modules.

Parameters

Name Type Description
$name string The name of the module to remove (eg. 'Slash')

Last updated: Tue, 01 Sep 2009