Zeta Components - high quality PHP components

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:

• ATOM (ezcFeedAtom) - RFC4287
• RSS1 (ezcFeedRss1) - Specifications
• RSS2 (ezcFeedRss2) - Specifications

The following modules are supported by the Feed component:

• Content (ezcFeedContentModule) - Specifications
• CreativeCommons (ezcFeedCreativeCommonsModule) - Specifications
• DublinCore (ezcFeedDublinCoreModule) - Specifications
• Geo (ezcFeedGeoModule) - Specifications
• GeoRss (ezcFeedGeoRssModule) - Specifications
• iTunes (ezcFeedITunesModule) - Specifications

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
3.   $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.  
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.  
9.  $xml = $feed->generate( 'rss2' ); // or the feed type which is needed
10.  ?>

In the above example mySlashHandler extends ezcFeedModule.

The array returned is (default):

1.  array(
2.     'Content'         => 'ezcFeedContentModule',
3.     'CreativeCommons' => 'ezcFeedCreativeCommonsModule',
4.     'DublinCore'      => 'ezcFeedDublinCoreModule',
5.     'Geo'             => 'ezcFeedGeoModule',
6.     'GeoRss'          => 'ezcFeedGeoRssModule',
7.     'iTunes'          => 'ezcFeedITunesModule'
8.  );

If the function registerModule was used to add another supported module type to ezcFeed, it will show up in the returned array as well.

The array returned is (default):

1.  array(
2.     'content'         => 'Content',
3.     'creativeCommons' => 'CreativeCommons',
4.     'dc'              => 'DublinCore',
5.     'geo'             => 'Geo',
6.     'georss'          => 'GeoRss',
7.     'itunes'          => 'iTunes'
8.  );

If the function registerModule was used to add another supported module type to ezcFeed, it will show up in the returned array as well.

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.

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' );

Example of parsing an XML document stored in a string:

1.  // $xmlString contains a valid XML string
2.  $feed = ezcFeed::parseContent( $xmlString );

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' );
4.  // add properties for the Opml feed type to $feed

In the above example, myOpmlHandler extends ezcFeedProcessor and implements ezcFeedParser.

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' );
6.  // add properties for the Slash module to $slash

The $type value is used when calling generate() without specifying a feed type to output.

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.