Feed: ezcFeed
[ ]
[ Specifications ]
[ ]
[ ]
[ ]
[ ]
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. ?>
Example of creating a feed with a user-defined type:
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. ?>
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-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
| Class | Description |
ezcFeedUnsupportedTypeException |
if the feed type $type is not supported |
add
Adds a new ezcFeedElement element with name $name and returns it.
Parameters
| Name |
Type |
Description |
$name |
string |
The element name |
Throws
| Class | Description |
ezcFeedUnsupportedElementException |
if the element $name is not supported |
addModule
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
| Class | 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
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
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
| Class | 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
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
| Class | Description |
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
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
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: Mon, 10 Nov 2008