## Apache Zeta Components Manual :: Docs For Class ezcFeed

### Feed::ezcFeed

### Class ezcFeed

Class defining a feed.

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

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:

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

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
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->itemas$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->itemas$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');
4. $feed=new ezcFeed ();
5. // add properties to $feed
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');
4. $feed=new ezcFeed ();
5. $item=$feed-> add ('item');
6. $slash=$item-> addModule ('Slash');
7. // add properties for the Slash module to $slash
9. $xml=$feed-> generate ('rss2');// or the feed type which is needed
10. ?>

In the above example mySlashHandler extends ezcFeedModule.

Source for this file: /Feed/src/feed.php

Version: | //autogentag//
Todo: | parse() and parseContent() should(?) handle common broken XML files (for example if the first line is not <?xml version="1.0"?>)

### Constants

`GENERATOR_URI = 'http://ezcomponents.org/docs/tutorials/Feed'` | The uri of the feed generator, to be included in the generated feeds.
`GENERATOR_VERSION = '//autogentag//'` | 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-id (optional, single).
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 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 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 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.
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 bool | `hasModule( $name )` Returns true if the module $name is loaded, false otherwise.
public void | `setModule( $name , $module )` Associates the module $module with the name $name.

### Methods

#### getSupportedModules

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

#### getSupportedModulesPrefixes

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

#### getSupportedTypes

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

#### parse

static 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

##### Exceptions:

Type | Description
--- | ---
`ezcBaseFileNotFoundException` | If the XML file at $uri could not be found.
`ezcFeedParseErrorException` | If the content at $uri is not a valid XML document.

#### parseContent

static 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

##### Exceptions:

Type | Description
--- | ---
`ezcFeedParseErrorException` | If $content is not a valid XML document.

#### registerFeed

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

##### Parameters:

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

#### registerModule

static 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');
3. $feed=new ezcFeed ('rss2');
4. $item=$feed-> add ('item');
5. $slash=$item-> addModule ('Slash');
6. // 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')

#### unregisterFeed

static 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

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

#### __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

##### Exceptions:

Type | Description
--- | ---
`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

##### Exceptions:

Type | Description
--- | ---
`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

##### Exceptions:

Type | Description
--- | ---
`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.

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

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

Documentation generated by phpDocumentor 1.4.3