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:
The following modules are supported by the Feed component:
A feed object can be created in different ways:
Parsing a feed (in the following examples $feed is an existing ezcFeed object):
Generating a feed:
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 "&".
Example of creating a feed with a user-defined type:
In the above example, myOpmlHandler extends ezcFeedProcessor and implements ezcFeedParser.
Example of creating a feed with a user-defined module:
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"?>) |
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. |
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). |
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. |
Returns the supported feed modules.
The array returned is (default):
If the function registerModule was used to add another supported module type to ezcFeed, it will show up in the returned array as well.
Returns the supported feed modules prefixes.
The array returned is (default):
If the function registerModule was used to add another supported module type to ezcFeed, it will show up in the returned array as well.
Returns the supported feed types.
The array returned is (default):
If the function registerFeed was used to add another supported feed type to ezcFeed, it will show up in the returned array as well.
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:
Example of parsing an XML document protected with HTTP authentication:
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:
Name | Type | Description |
---|---|---|
$uri |
string | An URI which stores an XML document |
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. |
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:
Name | Type | Description |
---|---|---|
$content |
string | A string variable which stores an XML document |
Type | Description |
---|---|
ezcFeedParseErrorException |
If $content is not a valid XML document. |
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:
In the above example, myOpmlHandler extends ezcFeedProcessor and implements ezcFeedParser.
Name | Type | Description |
---|---|---|
$name |
string | The feed type (eg. 'opml' ) |
$class |
string | The handler class for this feed type (eg. 'myOpmlHandler') |
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:
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') |
Removes a previously registered feed type from the list of supported feed types.
Name | Type | Description |
---|---|---|
$name |
string | The name of the feed type to remove (eg. 'opml') |
Removes a previously registered module from the list of supported modules.
Name | Type | Description |
---|---|---|
$name |
string | The name of the module to remove (eg. 'Slash') |
Creates a new feed object.
The $type value is used when calling generate() without specifying a feed type to output.
Name | Type | Description |
---|---|---|
$type |
string | The type of feed to create |
Type | Description |
---|---|
ezcFeedUnsupportedTypeException |
if the feed type $type is not supported |
Adds a new ezcFeedElement element with name $name and returns it.
Name | Type | Description |
---|---|---|
$name |
string | The element name |
Type | Description |
---|---|
ezcFeedUnsupportedElementException |
if the element $name is not supported |
Adds a new module to this item and returns it.
Name | Type | Description |
---|---|---|
$name |
string | The name of the module to add |
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.
Name | Type | Description |
---|---|---|
$type |
string | The feed type to generate |
Type | Description |
---|---|
ezcFeedUnsupportedTypeException |
if the feed type $type is not supported |
Returns the feed content type of this feed object (eg. 'application/rss+xml').
Returns the feed type of this feed object (eg. 'rss2').
Returns the loaded module $name.
Name | Type | Description |
---|---|---|
$name |
string | The name of the module to return |
Returns an array with all the modules loaded at feed-level.
Returns true if the module $name is loaded, false otherwise.
Name | Type | Description |
---|---|---|
$name |
string | The name of the module to check if loaded for this item |
Associates the module $module with the name $name.
Name | Type | Description |
---|---|---|
$name |
string | The name of the module associate |
$module |
ezcFeedModule | The module to set under the name $name |