Basic Usage

Zend\Feed\Reader is a component used to consume RSS and Atom feeds of any version, including RDF/RSS 1.0, RSS 2.0, Atom 0.3, and Atom 1.0. The API for retrieving feed data is deliberately simple since Zend\Feed\Reader is capable of searching any feed of any type for the information requested through the API. If the typical elements containing this information are not present, it will adapt and fall back on a variety of alternative elements instead. This ability to choose from alternatives removes the need for users to create their own abstraction layer on top of the component to make it useful or have any in-depth knowledge of the underlying standards, current alternatives, and namespaced extensions.

Internally, the Zend\Feed\Reader\Reader class works almost entirely on the basis of making XPath queries against the feed XML's Document Object Model. This singular approach to parsing is consistent, and the component offers a plugin system to add to the Feed and Entry APIs by writing extensions on a similar basis.

Performance is assisted in three ways. First of all, Zend\Feed\Reader\Reader supports caching using zend-cache to maintain a copy of the original feed XML. This allows you to skip network requests for a feed URI if the cache is valid. Second, the Feed and Entry APIs are backed by an internal cache (non-persistent) so repeat API calls for the same feed will avoid additional DOM or XPath use. Thirdly, importing feeds from a URI can take advantage of HTTP Conditional GET requests which allow servers to issue an empty 304 response when the requested feed has not changed since the last time you requested it. In the final case, an zend-cache storage instance will hold the last received feed along with the ETag and Last-Modified header values sent in the HTTP response.

Zend\Feed\Reader\Reader is not capable of constructing feeds, and delegates this responsibility to Zend\Feed\Writer\Writer.

Importing Feeds

Feeds can be imported from a string, file or a URI. Importing from a URI can additionally utilise an HTTP Conditional GET request. If importing fails, an exception will be raised. The end result will be an object of type Zend\Feed\Reader\Feed\AbstractFeed, the core implementations of which are Zend\Feed\Reader\Feed\Rss and Zend\Feed\Reader\Feed\Atom. Both objects support multiple (all existing) versions of these broad feed types.

In the following example, we import an RDF/RSS 1.0 feed and extract some basic information that can be saved to a database or elsewhere.

$feed = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');
$data = [
    'title'        => $feed->getTitle(),
    'link'         => $feed->getLink(),
    'dateModified' => $feed->getDateModified(),
    'description'  => $feed->getDescription(),
    'language'     => $feed->getLanguage(),
    'entries'      => [],
];

foreach ($feed as $entry) {
    $edata = [
        'title'        => $entry->getTitle(),
        'description'  => $entry->getDescription(),
        'dateModified' => $entry->getDateModified(),
        'authors'      => $entry->getAuthors(),
        'link'         => $entry->getLink(),
        'content'      => $entry->getContent(),
    ];
    $data['entries'][] = $edata;
}

Importing requires an HTTP client

To import a feed, you will need to have an HTTP client available.

If you are not using zend-http, you will need to inject Reader with the HTTP client. See the section on providing a client to Reader.

The example above demonstrates Zend\Feed\Reader\Reader's API, and it also demonstrates some of its internal operation. In reality, the RDF feed selected does not have any native date or author elements; however it does utilise the Dublin Core 1.1 module which offers namespaced creator and date elements. Zend\Feed\Reader\Reader falls back on these and similar options if no relevant native elements exist. If it absolutely cannot find an alternative it will return NULL, indicating the information could not be found in the feed. You should note that classes implementing Zend\Feed\Reader\Feed\AbstractFeed also implement the SPL Iterator and Countable interfaces.

Feeds can also be imported from strings or files.

// from a URI
$feed = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');

// from a String
$feed = Zend\Feed\Reader\Reader::importString($feedXmlString);

// from a file
$feed = Zend\Feed\Reader\Reader::importFile('./feed.xml');

Retrieving Underlying Feed and Entry Sources

Zend\Feed\Reader\Reader does its best not to stick you in a narrow confine. If you need to work on a feed outside of Zend\Feed\Reader\Reader, you can extract the base DOMDocument or DOMElement objects from any class, or even an XML string containing these. Also provided are methods to extract the current DOMXPath object (with all core and extension namespaces registered) and the correct prefix used in all XPath queries for the current feed or entry. The basic methods to use (on any object) are saveXml(), getDomDocument(), getElement(), getXpath() and getXpathPrefix(). These will let you break free of Zend\Feed\Reader and do whatever else you want.

• saveXml() returns an XML string containing only the element representing the current object.
• getDomDocument() returns the DOMDocument object representing the entire feed (even if called from an entry object).
• getElement() returns the DOMElement of the current object (i.e. the feed or current entry).
• getXpath() returns the DOMXPath object for the current feed (even if called from an entry object) with the namespaces of the current feed type and all loaded extensions pre-registered.
• getXpathPrefix() returns the query prefix for the current object (i.e. the feed or current entry) which includes the correct XPath query path for that specific feed or entry.

Let's look at an example where a feed might include an RSS extension not supported by Zend\Feed\Reader\Reader out of the box. Notably, you could write and register an extension (covered later) to do this, but that's not always warranted for a quick check. You must register any new namespaces on the DOMXPath object before use unless they are registered by Zend\Feed\Reader or an extension beforehand.

$feed        = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');
$xpathPrefix = $feed->getXpathPrefix();
$xpath       = $feed->getXpath();
$xpath->registerNamespace('admin', 'http://webns.net/mvcb/');
$reportErrorsTo = $xpath->evaluate(
    'string(' . $xpathPrefix . '/admin:errorReportsTo)'
);

Do not register duplicate namespaces

If you register an already registered namespace with a different prefix name to that used internally by Zend\Feed\Reader\Reader, it will break the internal operation of this component.

Cache Support and Intelligent Requests

Adding Cache Support to Zend\Feed\Reader\Reader

Zend\Feed\Reader\Reader supports using a zend-cache storage instance to cache feeds (as XML) to avoid unnecessary network requests. To add a cache, create and configure your cache instance, and then tell Zend\Feed\Reader\Reader to use it. The cache key used is "Zend\Feed\Reader\\" followed by the MD5 hash of the feed's URI.

$cache = Zend\Cache\StorageFactory::adapterFactory('Memory');
Zend\Feed\Reader\Reader::setCache($cache);

HTTP Conditional GET Support

The big question often asked when importing a feed frequently is if it has even changed. With a cache enabled, you can add HTTP Conditional GET support to your arsenal to answer that question.

Using this method, you can request feeds from URIs and include their last known ETag and Last-Modified response header values with the request (using the If-None-Match and If-Modified-Since headers). If the feed on the server remains unchanged, you should receive a 304 response which tells Zend\Feed\Reader\Reader to use the cached version. If a full feed is sent in a response with a status code of 200, this means the feed has changed and Zend\Feed\Reader\Reader will parse the new version and save it to the cache. It will also cache the new ETag and Last-Modified header values for future use.

Conditional GET requires a HeaderAwareClientInterface

Conditional GET support only works for Zend\Feed\Reader\Http\HeaderAwareClientInterface client implementations, as it requires the ability to send HTTP headers.

These "conditional" requests are not guaranteed to be supported by the server you request a URI of, but can be attempted regardless. Most common feed sources like blogs should however have this supported. To enable conditional requests, you will need to provide a cache to Zend\Feed\Reader\Reader.

$cache = Zend\Cache\StorageFactory::adapterFactory('Memory');

Zend\Feed\Reader\Reader::setCache($cache);
Zend\Feed\Reader\Reader::useHttpConditionalGet();

$feed = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');

In the example above, with HTTP Conditional GET requests enabled, the response header values for ETag and Last-Modified will be cached along with the feed. For the the cache's lifetime, feeds will only be updated on the cache if a non-304 response is received containing a valid RSS or Atom XML document.

If you intend on managing request headers from outside Zend\Feed\Reader\Reader, you can set the relevant If-None-Matches and If-Modified-Since request headers via the URI import method.

$lastEtagReceived = '5e6cefe7df5a7e95c8b1ba1a2ccaff3d';
$lastModifiedDateReceived = 'Wed, 08 Jul 2009 13:37:22 GMT';
$feed = Zend\Feed\Reader\Reader::import(
    $uri, $lastEtagReceived, $lastModifiedDateReceived
);

Locating Feed URIs from Websites

These days, many websites are aware that the location of their XML feeds is not always obvious. A small RDF, RSS, or Atom graphic helps when the user is reading the page, but what about when a machine visits trying to identify where your feeds are located? To assist in this, websites may point to their feeds using <link> tags in the <head> section of their HTML. To take advantage of this, you can use Zend\Feed\Reader\Reader to locate these feeds using the static findFeedLinks() method.

This method calls any URI and searches for the location of RSS, RDF, and Atom feeds assuming, the website's HTML contains the relevant links. It then returns a value object where you can check for the existence of a RSS, RDF or Atom feed URI.

The returned object is an ArrayObject subclass called Zend\Feed\Reader\FeedSet, so you can cast it to an array or iterate over it to access all the detected links. However, as a simple shortcut, you can just grab the first RSS, RDF, or Atom link using its public properties as in the example below. Otherwise, each element of the ArrayObject is a simple array with the keys type and uri where the type is one of "rdf", "rss", or "atom".

$links = Zend\Feed\Reader\Reader::findFeedLinks('http://www.planet-php.net');

if (isset($links->rdf)) {
    echo $links->rdf, "\n"; // http://www.planet-php.org/rdf/
}
if (isset($links->rss)) {
    echo $links->rss, "\n"; // http://www.planet-php.org/rss/
}
if (isset($links->atom)) {
    echo $links->atom, "\n"; // http://www.planet-php.org/atom/
}

Based on these links, you can then import from whichever source you wish in the usual manner.

Finding feed links requires an HTTP client

To find feed links, you will need to have an HTTP client available.

If you are not using zend-http, you will need to inject Reader with the HTTP client. See the section on providing a client to Reader.

This quick method only gives you one link for each feed type, but websites may indicate many links of any type. Perhaps it's a news site with a RSS feed for each news category. You can iterate over all links using the ArrayObject's iterator.

$links = Zend\Feed\Reader\Reader::findFeedLinks('http://www.planet-php.net');

foreach ($links as $link) {
    echo $link['href'], "\n";
}

Attribute Collections

In an attempt to simplify return types, return types from the various feed and entry level methods may include an object of type Zend\Feed\Reader\Collection\AbstractCollection. Despite the special class name which I'll explain below, this is just a simple subclass of SPL's ArrayObject.

The main purpose here is to allow the presentation of as much data as possible from the requested elements, while still allowing access to the most relevant data as a simple array. This also enforces a standard approach to returning such data which previously may have wandered between arrays and objects.

The new class type acts identically to ArrayObject with the sole addition being a new method getValues() which returns a simple flat array containing the most relevant information.

A simple example of this is Zend\Feed\Reader\Reader\FeedInterface::getCategories(). When used with any RSS or Atom feed, this method will return category data as a container object called Zend\Feed\Reader\Collection\Category. The container object will contain, per category, three fields of data: term, scheme, and label. The "term" is the basic category name, often machine readable (i.e. plays nice with URIs). The scheme represents a categorisation scheme (usually a URI identifier) also known as a "domain" in RSS 2.0. The "label" is a human readable category name which supports HTML entities. In RSS 2.0, there is no label attribute so it is always set to the same value as the term for convenience.

To access category labels by themselves in a simple value array, you might commit to something like:

$feed = Zend\Feed\Reader\Reader::import('http://www.example.com/atom.xml');
$categories = $feed->getCategories();
$labels = [];
foreach ($categories as $cat) {
    $labels[] = $cat['label']
}

It's a contrived example, but the point is that the labels are tied up with other information.

However, the container class allows you to access the "most relevant" data as a simple array using the getValues() method. The concept of "most relevant" is obviously a judgement call. For categories it means the category labels (not the terms or schemes) while for authors it would be the authors' names (not their email addresses or URIs). The simple array is flat (just values) and passed through array_unique() to remove duplication.

$feed = Zend\Feed\Reader\Reader::import('http://www.example.com/atom.xml');
$categories = $feed->getCategories();
$labels = $categories->getValues();

The above example shows how to extract only labels and nothing else thus giving simple access to the category labels without any additional work to extract that data by itself.

Retrieving Feed Information

Retrieving information from a feed (we'll cover entries and items in the next section though they follow identical principals) uses a clearly defined API which is exactly the same regardless of whether the feed in question is RSS, RDF, or Atom. The same goes for sub-versions of these standards and we've tested every single RSS and Atom version. While the underlying feed XML can differ substantially in terms of the tags and elements they present, they nonetheless are all trying to convey similar information and to reflect this all the differences and wrangling over alternative tags are handled internally by Zend\Feed\Reader\Reader presenting you with an identical interface for each. Ideally, you should not have to care whether a feed is RSS or Atom so long as you can extract the information you want.

RSS feeds vary widely

While determining common ground between feed types is itself complex, it should be noted that RSS in particular is a constantly disputed "specification". This has its roots in the original RSS 2.0 document, which contains ambiguities and does not detail the correct treatment of all elements. As a result, this component rigorously applies the RSS 2.0.11 Specification published by the RSS Advisory Board and its accompanying RSS Best Practices Profile. No other interpretation of RSS 2.0 will be supported, though exceptions may be allowed where it does not directly prevent the application of the two documents mentioned above.

Of course, we don't live in an ideal world, so there may be times the API just does not cover what you're looking for. To assist you, Zend\Feed\Reader\Reader offers a plugin system which allows you to write extensions to expand the core API and cover any additional data you are trying to extract from feeds. If writing another extension is too much trouble, you can simply grab the underlying DOM or XPath objects and do it by hand in your application. Of course, we really do encourage writing an extension simply to make it more portable and reusable, and useful extensions may be proposed to the component for formal addition.

Below is a summary of the Core API for feeds. You should note it comprises not only the basic RSS and Atom standards, but also accounts for a number of included extensions bundled with Zend\Feed\Reader\Reader. The naming of these extension sourced methods remain fairly generic; all Extension methods operate at the same level as the Core API though we do allow you to retrieve any specific extension object separately if required.

Feed Level API Methods

Given the variety of feeds in the wild, some of these methods will undoubtedly return NULL indicating the relevant information couldn't be located. Where possible, Zend\Feed\Reader\Reader will fall back on alternative elements during its search. For example, searching an RSS feed for a modification date is more complicated than it looks. RSS 2.0 feeds should include a <lastBuildDate> tag and/or a <pubDate> element. But what if it doesn't? Maybe this is an RSS 1.0 feed? Perhaps it instead has an <atom:updated> element with identical information (Atom may be used to supplement RSS syntax)? Failing that, we could simply look at the entries, pick the most recent, and use its <pubDate> element. Assuming it exists, that is. Many feeds also use Dublin Core 1.0 or 1.1 <dc:date> elements for feeds and entries. Or we could find Atom lurking again.

The point is, Zend\Feed\Reader\Reader was designed to know this. When you ask for the modification date (or anything else), it will run off and search for all these alternatives until it either gives up and returns NULL, or finds an alternative that should have the right answer.

In addition to the above methods, all feed object...