Chris@0: # Zend\\Feed\\Reader
Chris@0: 
Chris@0: `Zend\Feed\Reader` is a component used to consume RSS and Atom feeds of
Chris@0: any version, including RDF/RSS 1.0, RSS 2.0, Atom 0.3, and Atom 1.0. The API for
Chris@0: retrieving feed data is deliberately simple since `Zend\Feed\Reader` is capable
Chris@0: of searching any feed of any type for the information requested through the API.
Chris@0: If the typical elements containing this information are not present, it will
Chris@0: adapt and fall back on a variety of alternative elements instead. This ability
Chris@0: to choose from alternatives removes the need for users to create their own
Chris@0: abstraction layer on top of the component to make it useful or have any in-depth
Chris@0: knowledge of the underlying standards, current alternatives, and namespaced
Chris@0: extensions.
Chris@0: 
Chris@0: Internally, the `Zend\Feed\Reader\Reader` class works almost entirely on the
Chris@0: basis of making XPath queries against the feed XML's Document Object Model. This
Chris@0: singular approach to parsing is consistent, and the component offers a plugin
Chris@0: system to add to the Feed and Entry APIs by writing extensions on a similar
Chris@0: basis.
Chris@0: 
Chris@0: Performance is assisted in three ways. First of all, `Zend\Feed\Reader\Reader`
Chris@0: supports caching using [zend-cache](https://github.com/zendframework/zend-cache)
Chris@0: to maintain a copy of the original feed XML. This allows you to skip network
Chris@0: requests for a feed URI if the cache is valid. Second, the Feed and Entry APIs
Chris@0: are backed by an internal cache (non-persistent) so repeat API calls for the
Chris@0: same feed will avoid additional DOM or XPath use. Thirdly, importing feeds from
Chris@0: a URI can take advantage of HTTP Conditional `GET` requests which allow servers
Chris@0: to issue an empty 304 response when the requested feed has not changed since the
Chris@0: last time you requested it. In the final case, an zend-cache storage instance
Chris@0: will hold the last received feed along with the ETag and Last-Modified header
Chris@0: values sent in the HTTP response.
Chris@0: 
Chris@0: `Zend\Feed\Reader\Reader` is not capable of constructing feeds, and delegates
Chris@0: this responsibility to `Zend\Feed\Writer\Writer`.
Chris@0: 
Chris@0: ## Importing Feeds
Chris@0: 
Chris@0: Feeds can be imported from a string, file or a URI. Importing from a URI can
Chris@0: additionally utilise an HTTP Conditional `GET` request. If importing fails, an
Chris@0: exception will be raised. The end result will be an object of type
Chris@0: `Zend\Feed\Reader\Feed\AbstractFeed`, the core implementations of which are
Chris@0: `Zend\Feed\Reader\Feed\Rss` and `Zend\Feed\Reader\Feed\Atom`. Both objects
Chris@0: support multiple (all existing) versions of these broad feed types.
Chris@0: 
Chris@0: In the following example, we import an RDF/RSS 1.0 feed and extract some basic
Chris@0: information that can be saved to a database or elsewhere.
Chris@0: 
Chris@0: ```php
Chris@0: $feed = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');
Chris@0: $data = [
Chris@0:     'title'        => $feed->getTitle(),
Chris@0:     'link'         => $feed->getLink(),
Chris@0:     'dateModified' => $feed->getDateModified(),
Chris@0:     'description'  => $feed->getDescription(),
Chris@0:     'language'     => $feed->getLanguage(),
Chris@0:     'entries'      => [],
Chris@0: ];
Chris@0: 
Chris@0: foreach ($feed as $entry) {
Chris@0:     $edata = [
Chris@0:         'title'        => $entry->getTitle(),
Chris@0:         'description'  => $entry->getDescription(),
Chris@0:         'dateModified' => $entry->getDateModified(),
Chris@0:         'authors'      => $entry->getAuthors(),
Chris@0:         'link'         => $entry->getLink(),
Chris@0:         'content'      => $entry->getContent(),
Chris@0:     ];
Chris@0:     $data['entries'][] = $edata;
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: > ## Importing requires an HTTP client
Chris@0: >
Chris@0: > To import a feed, you will need to have an [HTTP client](zend.feed.http-clients)
Chris@0: > available. 
Chris@0: >
Chris@0: > If you are not using zend-http, you will need to inject `Reader` with the HTTP
Chris@0: > client. See the [section on providing a client to Reader](http-clients.md#providing-a-client-to-reader).
Chris@0: 
Chris@0: The example above demonstrates `Zend\Feed\Reader\Reader`'s API, and it also
Chris@0: demonstrates some of its internal operation. In reality, the RDF feed selected
Chris@0: does not have any native date or author elements; however it does utilise the
Chris@0: Dublin Core 1.1 module which offers namespaced creator and date elements.
Chris@0: `Zend\Feed\Reader\Reader` falls back on these and similar options if no relevant
Chris@0: native elements exist. If it absolutely cannot find an alternative it will
Chris@0: return `NULL`, indicating the information could not be found in the feed. You
Chris@0: should note that classes implementing `Zend\Feed\Reader\Feed\AbstractFeed` also
Chris@0: implement the SPL `Iterator` and `Countable` interfaces.
Chris@0: 
Chris@0: Feeds can also be imported from strings or files.
Chris@0: 
Chris@0: ```php
Chris@0: // from a URI
Chris@0: $feed = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');
Chris@0: 
Chris@0: // from a String
Chris@0: $feed = Zend\Feed\Reader\Reader::importString($feedXmlString);
Chris@0: 
Chris@0: // from a file
Chris@0: $feed = Zend\Feed\Reader\Reader::importFile('./feed.xml');
Chris@0: ```
Chris@0: 
Chris@0: ## Retrieving Underlying Feed and Entry Sources
Chris@0: 
Chris@0: `Zend\Feed\Reader\Reader` does its best not to stick you in a narrow confine. If
Chris@0: you need to work on a feed outside of `Zend\Feed\Reader\Reader`, you can extract
Chris@0: the base DOMDocument or DOMElement objects from any class, or even an XML
Chris@0: string containing these. Also provided are methods to extract the current
Chris@0: DOMXPath object (with all core and extension namespaces registered) and the
Chris@0: correct prefix used in all XPath queries for the current feed or entry. The
Chris@0: basic methods to use (on any object) are `saveXml()`, `getDomDocument()`,
Chris@0: `getElement()`, `getXpath()` and `getXpathPrefix()`. These will let you break
Chris@0: free of `Zend\Feed\Reader` and do whatever else you want.
Chris@0: 
Chris@0: - `saveXml()` returns an XML string containing only the element representing the
Chris@0:   current object.
Chris@0: - `getDomDocument()` returns the DOMDocument object representing the entire feed
Chris@0:   (even if called from an entry object).
Chris@0: - `getElement()` returns the DOMElement of the current object (i.e. the feed or
Chris@0:   current entry).
Chris@0: - `getXpath()` returns the DOMXPath object for the current feed (even if called
Chris@0:   from an entry object) with the namespaces of the current feed type and all
Chris@0:   loaded extensions pre-registered.
Chris@0: - `getXpathPrefix()` returns the query prefix for the current object (i.e. the
Chris@0:   feed or current entry) which includes the correct XPath query path for that
Chris@0:   specific feed or entry.
Chris@0: 
Chris@0: Let's look at an example where a feed might include an RSS extension not
Chris@0: supported by `Zend\Feed\Reader\Reader` out of the box. Notably, you could write
Chris@0: and register an extension (covered later) to do this, but that's not always
Chris@0: warranted for a quick check. You must register any new namespaces on the
Chris@0: DOMXPath object before use unless they are registered by `Zend\Feed\Reader` or
Chris@0: an extension beforehand.
Chris@0: 
Chris@0: ```php
Chris@0: $feed        = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');
Chris@0: $xpathPrefix = $feed->getXpathPrefix();
Chris@0: $xpath       = $feed->getXpath();
Chris@0: $xpath->registerNamespace('admin', 'http://webns.net/mvcb/');
Chris@0: $reportErrorsTo = $xpath->evaluate(
Chris@0:     'string(' . $xpathPrefix . '/admin:errorReportsTo)'
Chris@0: );
Chris@0: ```
Chris@0: 
Chris@0: > ### Do not register duplicate namespaces
Chris@0: >
Chris@0: > If you register an already registered namespace with a different prefix name
Chris@0: > to that used internally by `Zend\Feed\Reader\Reader`, it will break the
Chris@0: > internal operation of this component.
Chris@0: 
Chris@0: ## Cache Support and Intelligent Requests
Chris@0: 
Chris@0: ### Adding Cache Support to Zend\\Feed\\Reader\\Reader
Chris@0: 
Chris@0: `Zend\Feed\Reader\Reader` supports using a
Chris@0: [zend-cache](https://github.com/zendframework/zend-cache) storage instance to
Chris@0: cache feeds (as XML) to avoid unnecessary network requests. To add a cache,
Chris@0: create and configure your cache instance, and then tell
Chris@0: `Zend\Feed\Reader\Reader` to use it. The cache key used is
Chris@0: "`Zend\Feed\Reader\\`" followed by the MD5 hash of the feed's URI.
Chris@0: 
Chris@0: ```php
Chris@0: $cache = Zend\Cache\StorageFactory::adapterFactory('Memory');
Chris@0: Zend\Feed\Reader\Reader::setCache($cache);
Chris@0: ```
Chris@0: 
Chris@0: ### HTTP Conditional GET Support
Chris@0: 
Chris@0: The big question often asked when importing a feed frequently is if it has even
Chris@0: changed. With a cache enabled, you can add HTTP Conditional `GET` support to
Chris@0: your arsenal to answer that question.
Chris@0: 
Chris@0: Using this method, you can request feeds from URIs and include their last known
Chris@0: ETag and Last-Modified response header values with the request (using the
Chris@0: If-None-Match and If-Modified-Since headers). If the feed on the server remains
Chris@0: unchanged, you should receive a 304 response which tells
Chris@0: `Zend\Feed\Reader\Reader` to use the cached version. If a full feed is sent in a
Chris@0: response with a status code of 200, this means the feed has changed and
Chris@0: `Zend\Feed\Reader\Reader` will parse the new version and save it to the cache.
Chris@0: It will also cache the new ETag and Last-Modified header values for future use.
Chris@0: 
Chris@0: > #### Conditional GET requires a HeaderAwareClientInterface
Chris@0: >
Chris@0: > Conditional GET support only works for `Zend\Feed\Reader\Http\HeaderAwareClientInterface`
Chris@0: > client implementations, as it requires the ability to send HTTP headers.
Chris@0: 
Chris@0: These "conditional" requests are not guaranteed to be supported by the server
Chris@0: you request a *URI* of, but can be attempted regardless. Most common feed
Chris@0: sources like blogs should however have this supported. To enable conditional
Chris@0: requests, you will need to provide a cache to `Zend\Feed\Reader\Reader`.
Chris@0: 
Chris@0: ```php
Chris@0: $cache = Zend\Cache\StorageFactory::adapterFactory('Memory');
Chris@0: 
Chris@0: Zend\Feed\Reader\Reader::setCache($cache);
Chris@0: Zend\Feed\Reader\Reader::useHttpConditionalGet();
Chris@0: 
Chris@0: $feed = Zend\Feed\Reader\Reader::import('http://www.planet-php.net/rdf/');
Chris@0: ```
Chris@0: 
Chris@0: In the example above, with HTTP Conditional `GET` requests enabled, the response
Chris@0: header values for ETag and Last-Modified will be cached along with the feed. For
Chris@0: the the cache's lifetime, feeds will only be updated on the cache if a non-304
Chris@0: response is received containing a valid RSS or Atom XML document.
Chris@0: 
Chris@0: If you intend on managing request headers from outside
Chris@0: `Zend\Feed\Reader\Reader`, you can set the relevant If-None-Matches and
Chris@0: If-Modified-Since request headers via the URI import method.
Chris@0: 
Chris@0: ```php
Chris@0: $lastEtagReceived = '5e6cefe7df5a7e95c8b1ba1a2ccaff3d';
Chris@0: $lastModifiedDateReceived = 'Wed, 08 Jul 2009 13:37:22 GMT';
Chris@0: $feed = Zend\Feed\Reader\Reader::import(
Chris@0:     $uri, $lastEtagReceived, $lastModifiedDateReceived
Chris@0: );
Chris@0: ```
Chris@0: 
Chris@0: ## Locating Feed URIs from Websites
Chris@0: 
Chris@0: These days, many websites are aware that the location of their XML feeds is not
Chris@0: always obvious. A small RDF, RSS, or Atom graphic helps when the user is reading
Chris@0: the page, but what about when a machine visits trying to identify where your
Chris@0: feeds are located? To assist in this, websites may point to their feeds using
Chris@0: `<link>` tags in the `<head>` section of their HTML. To take advantage
Chris@0: of this, you can use `Zend\Feed\Reader\Reader` to locate these feeds using the
Chris@0: static `findFeedLinks()` method.
Chris@0: 
Chris@0: This method calls any URI and searches for the location of RSS, RDF, and Atom
Chris@0: feeds assuming, the website's HTML contains the relevant links. It then returns
Chris@0: a value object where you can check for the existence of a RSS, RDF or Atom feed
Chris@0: URI.
Chris@0: 
Chris@0: The returned object is an `ArrayObject` subclass called
Chris@0: `Zend\Feed\Reader\FeedSet`, so you can cast it to an array or iterate over it to
Chris@0: access all the detected links. However, as a simple shortcut, you can just grab
Chris@0: the first RSS, RDF, or Atom link using its public properties as in the example
Chris@0: below. Otherwise, each element of the `ArrayObject` is a simple array with the
Chris@0: keys `type` and `uri` where the type is one of "rdf", "rss", or "atom".
Chris@0: 
Chris@0: ```php
Chris@0: $links = Zend\Feed\Reader\Reader::findFeedLinks('http://www.planet-php.net');
Chris@0: 
Chris@0: if (isset($links->rdf)) {
Chris@0:     echo $links->rdf, "\n"; // http://www.planet-php.org/rdf/
Chris@0: }
Chris@0: if (isset($links->rss)) {
Chris@0:     echo $links->rss, "\n"; // http://www.planet-php.org/rss/
Chris@0: }
Chris@0: if (isset($links->atom)) {
Chris@0:     echo $links->atom, "\n"; // http://www.planet-php.org/atom/
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: Based on these links, you can then import from whichever source you wish in the usual manner.
Chris@0: 
Chris@0: > ### Finding feed links requires an HTTP client
Chris@0: >
Chris@0: > To find feed links, you will need to have an [HTTP client](zend.feed.http-clients)
Chris@0: > available. 
Chris@0: >
Chris@0: > If you are not using zend-http, you will need to inject `Reader` with the HTTP
Chris@0: > client. See the [section on providing a client to Reader](http-clients.md#providing-a-client-to-reader).
Chris@0: 
Chris@0: This quick method only gives you one link for each feed type, but websites may
Chris@0: indicate many links of any type. Perhaps it's a news site with a RSS feed for
Chris@0: each news category. You can iterate over all links using the ArrayObject's
Chris@0: iterator.
Chris@0: 
Chris@0: ```php
Chris@0: $links = Zend\Feed\Reader::findFeedLinks('http://www.planet-php.net');
Chris@0: 
Chris@0: foreach ($links as $link) {
Chris@0:     echo $link['href'], "\n";
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: ## Attribute Collections
Chris@0: 
Chris@0: In an attempt to simplify return types, return types from the various feed and
Chris@0: entry level methods may include an object of type
Chris@0: `Zend\Feed\Reader\Collection\AbstractCollection`. Despite the special class name
Chris@0: which I'll explain below, this is just a simple subclass of SPL's `ArrayObject`.
Chris@0: 
Chris@0: The main purpose here is to allow the presentation of as much data as possible
Chris@0: from the requested elements, while still allowing access to the most relevant
Chris@0: data as a simple array. This also enforces a standard approach to returning such
Chris@0: data which previously may have wandered between arrays and objects.
Chris@0: 
Chris@0: The new class type acts identically to `ArrayObject` with the sole addition
Chris@0: being a new method `getValues()` which returns a simple flat array containing
Chris@0: the most relevant information.
Chris@0: 
Chris@0: A simple example of this is `Zend\Feed\Reader\Reader\FeedInterface::getCategories()`.
Chris@0: When used with any RSS or Atom feed, this method will return category data as a
Chris@0: container object called `Zend\Feed\Reader\Collection\Category`. The container
Chris@0: object will contain, per category, three fields of data: term, scheme, and label.
Chris@0: The "term" is the basic category name, often machine readable (i.e. plays nice
Chris@0: with URIs). The scheme represents a categorisation scheme (usually a URI
Chris@0: identifier) also known as a "domain" in RSS 2.0. The "label" is a human readable
Chris@0: category name which supports HTML entities. In RSS 2.0, there is no label
Chris@0: attribute so it is always set to the same value as the term for convenience.
Chris@0: 
Chris@0: To access category labels by themselves in a simple value array, you might
Chris@0: commit to something like:
Chris@0: 
Chris@0: ```php
Chris@0: $feed = Zend\Feed\Reader\Reader::import('http://www.example.com/atom.xml');
Chris@0: $categories = $feed->getCategories();
Chris@0: $labels = [];
Chris@0: foreach ($categories as $cat) {
Chris@0:     $labels[] = $cat['label']
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: It's a contrived example, but the point is that the labels are tied up with
Chris@0: other information.
Chris@0: 
Chris@0: However, the container class allows you to access the "most relevant" data as a
Chris@0: simple array using the `getValues()` method. The concept of "most relevant" is
Chris@0: obviously a judgement call. For categories it means the category labels (not the
Chris@0: terms or schemes) while for authors it would be the authors' names (not their
Chris@0: email addresses or URIs). The simple array is flat (just values) and passed
Chris@0: through `array_unique()` to remove duplication.
Chris@0: 
Chris@0: ```php
Chris@0: $feed = Zend\Feed\Reader\Reader::import('http://www.example.com/atom.xml');
Chris@0: $categories = $feed->getCategories();
Chris@0: $labels = $categories->getValues();
Chris@0: ```
Chris@0: 
Chris@0: The above example shows how to extract only labels and nothing else thus giving
Chris@0: simple access to the category labels without any additional work to extract that
Chris@0: data by itself.
Chris@0: 
Chris@0: ## Retrieving Feed Information
Chris@0: 
Chris@0: Retrieving information from a feed (we'll cover entries and items in the next
Chris@0: section though they follow identical principals) uses a clearly defined API
Chris@0: which is exactly the same regardless of whether the feed in question is RSS,
Chris@0: RDF, or Atom. The same goes for sub-versions of these standards and we've tested
Chris@0: every single RSS and Atom version. While the underlying feed XML can differ
Chris@0: substantially in terms of the tags and elements they present, they nonetheless
Chris@0: are all trying to convey similar information and to reflect this all the
Chris@0: differences and wrangling over alternative tags are handled internally by
Chris@0: `Zend\Feed\Reader\Reader` presenting you with an identical interface for each.
Chris@0: Ideally, you should not have to care whether a feed is RSS or Atom so long as
Chris@0: you can extract the information you want.
Chris@0: 
Chris@0: > ### RSS feeds vary widely
Chris@0: >
Chris@0: > While determining common ground between feed types is itself complex, it
Chris@0: > should be noted that *RSS* in particular is a constantly disputed
Chris@0: > "specification". This has its roots in the original RSS 2.0 document, which
Chris@0: > contains ambiguities and does not detail the correct treatment of all
Chris@0: > elements. As a result, this component rigorously applies the RSS 2.0.11
Chris@0: > Specification published by the RSS Advisory Board and its accompanying RSS
Chris@0: > Best Practices Profile. No other interpretation of RSS
Chris@0: > 2.0 will be supported, though exceptions may be allowed where it does not
Chris@0: > directly prevent the application of the two documents mentioned above.
Chris@0: 
Chris@0: Of course, we don't live in an ideal world, so there may be times the API just
Chris@0: does not cover what you're looking for. To assist you, `Zend\Feed\Reader\Reader`
Chris@0: offers a plugin system which allows you to write extensions to expand the core
Chris@0: API and cover any additional data you are trying to extract from feeds. If
Chris@0: writing another extension is too much trouble, you can simply grab the
Chris@0: underlying DOM or XPath objects and do it by hand in your application. Of
Chris@0: course, we really do encourage writing an extension simply to make it more
Chris@0: portable and reusable, and useful extensions may be proposed to the component
Chris@0: for formal addition.
Chris@0: 
Chris@0: Below is a summary of the Core API for feeds. You should note it comprises not
Chris@0: only the basic RSS and Atom standards, but also accounts for a number of
Chris@0: included extensions bundled with `Zend\Feed\Reader\Reader`. The naming of these
Chris@0: extension sourced methods remain fairly generic; all Extension methods operate
Chris@0: at the same level as the Core API though we do allow you to retrieve any
Chris@0: specific extension object separately if required.
Chris@0: 
Chris@0: ### Feed Level API Methods
Chris@0: 
Chris@0: Method | Description
Chris@0: ------ | -----------
Chris@0: `getId()` | Returns a unique ID associated with this feed
Chris@0: `getTitle()` |  Returns the title of the feed
Chris@0: `getDescription()` | Returns the text description of the feed.
Chris@0: `getLink()` | Returns a URI to the HTML website containing the same or similar information as this feed (i.e. if the feed is from a blog, it should provide the blog's URI where the HTML version of the entries can be read).
Chris@0: `getFeedLink()` | Returns the URI of this feed, which may be the same as the URI used to import the feed. There are important cases where the feed link may differ because the source URI is being updated and is intended to be removed in the future.
Chris@0: `getAuthors()` | Returns an object of type `Zend\Feed\Reader\Collection\Author` which is an `ArrayObject` whose elements are each simple arrays containing any combination of the keys "name", "email" and "uri". Where irrelevant to the source data, some of these keys may be omitted.
Chris@0: `getAuthor(integer $index = 0)` | Returns either the first author known, or with the optional $index parameter any specific index on the array of authors as described above (returning `NULL` if an invalid index).
Chris@0: `getDateCreated()` | Returns the date on which this feed was created. Generally only applicable to Atom, where it represents the date the resource described by an Atom 1.0 document was created. The returned date will be a `DateTime` object.
Chris@0: `getDateModified()` | Returns the date on which this feed was last modified. The returned date will be a `DateTime` object.
Chris@0: `getLastBuildDate()` |  Returns the date on which this feed was last built. The returned date will be a `DateTime` object. This is only supported by RSS; Atom feeds will always return `NULL`.
Chris@0: `getLanguage()` | Returns the language of the feed (if defined) or simply the language noted in the XML document.
Chris@0: `getGenerator()` |  Returns the generator of the feed, e.g. the software which generated it. This may differ between RSS and Atom since Atom defines a different notation.
Chris@0: `getCopyright()` | Returns any copyright notice associated with the feed.
Chris@0: `getHubs()` | Returns an array of all Hub Server URI endpoints which are advertised by the feed for use with the Pubsubhubbub Protocol, allowing subscriptions to the feed for real-time updates.
Chris@0: `getCategories()` | Returns a `Zend\Feed\Reader\Collection\Category` object containing the details of any categories associated with the overall feed. The supported fields include "term" (the machine readable category name), "scheme" (the categorisation scheme and domain for this category), and "label" (a HTML decoded human readable category name). Where any of the three fields are absent from the field, they are either set to the closest available alternative or, in the case of "scheme", set to `NULL`.
Chris@0: `getImage()` | Returns an array containing data relating to any feed image or logo, or `NULL` if no image found. The resulting array may contain the following keys: uri, link, title, description, height, and width. Atom logos only contain a URI so the remaining metadata is drawn from RSS feeds only.
Chris@0: 
Chris@0: Given the variety of feeds in the wild, some of these methods will undoubtedly
Chris@0: return `NULL` indicating the relevant information couldn't be located. Where
Chris@0: possible, `Zend\Feed\Reader\Reader` will fall back on alternative elements
Chris@0: during its search. For example, searching an RSS feed for a modification date is
Chris@0: more complicated than it looks. RSS 2.0 feeds should include a `<lastBuildDate>`
Chris@0: tag and/or a `<pubDate>` element. But what if it doesn't? Maybe this is an RSS
Chris@0: 1.0 feed? Perhaps it instead has an `<atom:updated>` element with identical
Chris@0: information (Atom may be used to supplement RSS syntax)? Failing that, we
Chris@0: could simply look at the entries, pick the most recent, and use its `<pubDate>`
Chris@0: element. Assuming it exists, that is. Many feeds also use Dublin Core 1.0 or 1.1
Chris@0: `<dc:date>` elements for feeds and entries. Or we could find Atom lurking again.
Chris@0: 
Chris@0: The point is, `Zend\Feed\Reader\Reader` was designed to know this. When you ask
Chris@0: for the modification date (or anything else), it will run off and search for all
Chris@0: these alternatives until it either gives up and returns `NULL`, or finds an
Chris@0: alternative that should have the right answer.
Chris@0: 
Chris@0: In addition to the above methods, all feed objects implement methods for
Chris@0: retrieving the DOM and XPath objects for the current feeds as described
Chris@0: earlier. Feed objects also implement the SPL Iterator and Countable
Chris@0: interfaces. The extended API is summarised below.
Chris@0: 
Chris@0: ### Extended Feed API Methods
Chris@0: 
Chris@0: Method | Description
Chris@0: ------ | -----------
Chris@0: `getDomDocument()` | Returns the parent DOMDocument object for the entire source XML document.
Chris@0: `getElement()` | Returns the current feed level DOMElement object.
Chris@0: `saveXml()` | Returns a string containing an XML document of the entire feed element (this is not the original document, but a rebuilt version).
Chris@0: `getXpath()` | Returns the DOMXPath object used internally to run queries on the DOMDocument object (this includes core and extension namespaces pre-registered).
Chris@0: `getXpathPrefix()` | Returns the valid DOM path prefix prepended to all XPath queries matching the feed being queried.
Chris@0: `getEncoding()` | Returns the encoding of the source XML document (note: this cannot account for errors such as the server sending documents in a different encoding). Where not defined, the default UTF-8 encoding of Unicode is applied.
Chris@0: `count()` | Returns a count of the entries or items this feed contains (implements SPL `Countable` interface)
Chris@0: `current()` | Returns either the current entry (using the current index from `key()`).
Chris@0: `key()` | Returns the current entry index.
Chris@0: `next()` | Increments the entry index value by one.
Chris@0: `rewind()` | Resets the entry index to 0.
Chris@0: `valid()` | Checks that the current entry index is valid, i.e. it does not fall below 0 and does not exceed the number of entries existing.
Chris@0: `getExtensions()` | Returns an array of all extension objects loaded for the current feed (note: both feed-level and entry-level extensions exist, and only feed-level extensions are returned here). The array keys are of the form `{ExtensionName}_Feed`.
Chris@0: `getExtension(string $name)` | Returns an extension object for the feed registered under the provided name. This allows more fine-grained access to extensions which may otherwise be hidden within the implementation of the standard API methods.
Chris@0: `getType()` | Returns a static class constant (e.g.  `Zend\Feed\Reader\Reader::TYPE_ATOM_03`, i.e. "Atom 0.3"), indicating exactly what kind of feed is being consumed.
Chris@0: 
Chris@0: ## Retrieving Entry/Item Information
Chris@0: 
Chris@0: Retrieving information for specific entries or items (depending on whether you
Chris@0: speak Atom or RSS) is identical to feed level data. Accessing entries is
Chris@0: simply a matter of iterating over a feed object or using the SPL `Iterator`
Chris@0: interface feed objects implement, and calling the appropriate method on each.
Chris@0: 
Chris@0: ### Entry API Methods
Chris@0: 
Chris@0: Method | Description
Chris@0: ------ | -----------
Chris@0: `getId()` | Returns a unique ID for the current entry.
Chris@0: `getTitle()` | Returns the title of the current entry.
Chris@0: `getDescription()` | Returns a description of the current entry.
Chris@0: `getLink()` | Returns a URI to the HTML version of the current entry.
Chris@0: `getPermaLink()` | Returns the permanent link to the current entry. In most cases, this is the same as using `getLink()`.
Chris@0: `getAuthors()` | Returns an object of type `Zend\Feed\Reader\Collection\Author`, which is an `ArrayObject` whose elements are each simple arrays containing any combination of the keys "name", "email" and "uri". Where irrelevant to the source data, some of these keys may be omitted.
Chris@0: `getAuthor(integer $index = 0)` | Returns either the first author known, or, with the optional `$index` parameter, any specific index on the array of Authors as described above (returning `NULL` if an invalid index).
Chris@0: `getDateCreated()` | Returns the date on which the current entry was created. Generally only applicable to Atom where it represents the date the resource described by an Atom 1.0 document was created.
Chris@0: `getDateModified()` | Returns the date on which the current entry was last modified.
Chris@0: `getContent()` | Returns the content of the current entry (this has any entities reversed if possible, assuming the content type is HTML). The description is returned if a separate content element does not exist.
Chris@0: `getEnclosure()` | Returns an array containing the value of all attributes from a multi-media `<enclosure>` element including as array keys: url, length, type. In accordance with the RSS Best Practices Profile of the RSS Advisory Board, no support is offers for multiple enclosures since such support forms no part of the RSS specification.
Chris@0: `getCommentCount()` | Returns the number of comments made on this entry at the time the feed was last generated.
Chris@0: `getCommentLink()` | Returns a URI pointing to the HTML page where comments can be made on this entry.
Chris@0: `getCommentFeedLink([string $type = ‘atom'|'rss'])` | Returns a URI pointing to a feed of the provided type containing all comments for this entry (type defaults to Atom/RSS depending on current feed type).
Chris@0: `getCategories()` | Returns a `Zend\Feed\Reader\Collection\Category` object containing the details of any categories associated with the entry. The supported fields include "term" (the machine readable category name), "scheme" (the categorisation scheme and domain for this category), and "label" (an HTML-decoded human readable category name). Where any of the three fields are absent from the field, they are either set to the closest available alternative or, in the case of "scheme", set to `NULL`.
Chris@0: 
Chris@0: The extended API for entries is identical to that for feeds with the exception
Chris@0: of the `Iterator` methods, which are not needed here.
Chris@0: 
Chris@0: > ### Modified vs Created dates
Chris@0: > 
Chris@0: > There is often confusion over the concepts of *modified* and *created* dates.
Chris@0: > In Atom, these are two clearly defined concepts (so knock yourself out) but in
Chris@0: > RSS they are vague. RSS 2.0 defines a single `<pubDate>` element which
Chris@0: > typically refers to the date this entry was published, i.e.  a creation date of
Chris@0: > sorts. This is not always the case, and it may change with updates or not. As a
Chris@0: > result, if you really want to check whether an entry has changed, don't rely on
Chris@0: > the results of `getDateModified()`. Instead, consider tracking the MD5 hash of
Chris@0: > three other elements concatenated, e.g. using `getTitle()`, `getDescription()`,
Chris@0: > and `getContent()`. If the entry was truly updated, this hash computation will
Chris@0: > give a different result than previously saved hashes for the same entry. This
Chris@0: > is obviously content oriented, and will not assist in detecting changes to
Chris@0: > other relevant elements.  Atom feeds should not require such steps.
Chris@0: 
Chris@0: > Further muddying the waters, dates in feeds may follow different standards.
Chris@0: > Atom and Dublin Core dates should follow ISO 8601, and RSS dates should
Chris@0: > follow RFC 822 or RFC 2822 (which is also common). Date methods will throw an
Chris@0: > exception if `DateTime` cannot load the date string using one of the above
Chris@0: > standards, or the PHP recognised possibilities for RSS dates.
Chris@0: 
Chris@0: > ### Validation
Chris@0: >
Chris@0: > The values returned from these methods are not validated. This means users
Chris@0: > must perform validation on all retrieved data including the filtering of any
Chris@0: > HTML such as from `getContent()` before it is output from your application.
Chris@0: > Remember that most feeds come from external sources, and therefore the default
Chris@0: > assumption should be that they cannot be trusted.
Chris@0: 
Chris@0: ### Extended Entry Level API Methods
Chris@0: 
Chris@0: Method | Description
Chris@0: ------ | -----------
Chris@0: `getDomDocument()` | Returns the parent DOMDocument object for the entire feed (not just the current entry).
Chris@0: `getElement()` | Returns the current entry level DOMElement object.
Chris@0: `getXpath()` | Returns the DOMXPath object used internally to run queries on the DOMDocument object (this includes core and extension namespaces pre-registered).
Chris@0: `getXpathPrefix()` | Returns the valid DOM path prefix prepended to all XPath queries matching the entry being queried.
Chris@0: `getEncoding()` | Returns the encoding of the source XML document (note: this cannot account for errors such as the server sending documents in a different encoding). The default encoding applied in the absence of any other is the UTF-8 encoding of Unicode.
Chris@0: `getExtensions()` | Returns an array of all extension objects loaded for the current entry (note: both feed-level and entry-level extensions exist, and only entry-level extensions are returned here). The array keys are in the form `{ExtensionName}Entry`.
Chris@0: `getExtension(string $name)` | Returns an extension object for the entry registered under the provided name. This allows more fine-grained access to extensions which may otherwise be hidden within the implementation of the standard API methods.
Chris@0: `getType()` | Returns a static class constant (e.g. `Zend\Feed\Reader\Reader::TYPE_ATOM_03`, i.e. "Atom 0.3") indicating exactly what kind of feed is being consumed.
Chris@0: 
Chris@0: ## Extending Feed and Entry APIs
Chris@0: 
Chris@0: Extending `Zend\Feed\Reader\Reader` allows you to add methods at both the feed
Chris@0: and entry level which cover the retrieval of information not already supported
Chris@0: by `Zend\Feed\Reader\Reader`. Given the number of RSS and Atom extensions that
Chris@0: exist, this is a good thing, since `Zend\Feed\Reader\Reader` couldn't possibly
Chris@0: add everything.
Chris@0: 
Chris@0: There are two types of extensions possible, those which retrieve information
Chris@0: from elements which are immediate children of the root element (e.g.
Chris@0: `<channel>` for RSS or `<feed>` for Atom), and those who retrieve information
Chris@0: from child elements of an entry (e.g. `<item>` for RSS or `<entry>` for Atom).
Chris@0: On the filesystem, these are grouped as classes within a namespace based on the
Chris@0: extension standard's name. For example, internally we have
Chris@0: `Zend\Feed\Reader\Extension\DublinCore\Feed` and
Chris@0: `Zend\Feed\Reader\Extension\DublinCore\Entry` classes which are two extensions
Chris@0: implementing Dublin Core 1.0 and 1.1 support.
Chris@0: 
Chris@0: Extensions are loaded into `Zend\Feed\Reader\Reader` using an "extension
Chris@0: manager". Extension managers must implement `Zend\Feed\Reader\ExtensionManagerInterface`.
Chris@0: Three implementations exist:
Chris@0: 
Chris@0: - `Zend\Feed\Reader\StandaloneExtensionManager` is a hard-coded implementation
Chris@0:   seeded with all feed and entry implementations. You can extend it to add
Chris@0:   extensions, though it's likely easier to copy and paste it, adding your
Chris@0:   changes.
Chris@0: - `Zend\Feed\Reader\ExtensionPluginManager` is a `Zend\ServiceManager\AbstractPluginManager`
Chris@0:   implementation, `Zend\Feed\Reader\ExtensionManager`; as such, you can extend
Chris@0:   it to add more extensions, use a `Zend\ServiceManager\ConfigInterface` instance
Chris@0:   to inject it with more extensions, or use its public API for adding services
Chris@0:   (e.g., `setService()`, `setFactory()`, etc.). This implementation *does not*
Chris@0:   implement `ExtensionManagerInterface`, and must be used with `ExtensionManager`.
Chris@0: - `Zend\Feed\Reader\ExtensionManager` exists for legacy purposes; prior to 2.3,
Chris@0:   this was an `AbstractPluginManager` implementation, and the only provided
Chris@0:   extension manager. It now implements `ExtensionManagerInterface`, and acts as
Chris@0:   a decorator for `ExtensionPluginManager`.
Chris@0: 
Chris@0: By default, `Zend\Feed\Reader\Reader` composes a `StandaloneExtensionManager`. You
Chris@0: can inject an alternate implementation using `Reader::setExtensionManager()`:
Chris@0: 
Chris@0: ```php
Chris@0: $extensions = new Zend\Feed\Reader\ExtensionPluginManager();
Chris@0: Zend\Feed\Reader\Reader::setExtensionManager(
Chris@0:     new ExtensionManager($extensions)
Chris@0: );
Chris@0: ```
Chris@0: 
Chris@0: The shipped implementations all provide the default extensions (so-called
Chris@0: "Core Extensions") used internally by `Zend\Feed\Reader\Reader`. These
Chris@0: include:
Chris@0: 
Chris@0: Extension | Description
Chris@0: --------- | -----------
Chris@0: DublinCore (Feed and Entry) | Implements support for Dublin Core Metadata Element Set 1.0 and 1.1.
Chris@0: Content (Entry only) | Implements support for Content 1.0.
Chris@0: Atom (Feed and Entry) | Implements support for Atom 0.3 and Atom 1.0.
Chris@0: Slash | Implements support for the Slash RSS 1.0 module.
Chris@0: WellFormedWeb | Implements support for the Well Formed Web CommentAPI 1.0.
Chris@0: Thread | Implements support for Atom Threading Extensions as described in RFC 4685.
Chris@0: Podcast | Implements support for the Podcast 1.0 DTD from Apple.
Chris@0: 
Chris@0: The core extensions are somewhat special since they are extremely common and
Chris@0: multi-faceted. For example, we have a core extension for Atom. Atom is
Chris@0: implemented as an extension (not just a base class) because it doubles as a
Chris@0: valid RSS module; you can insert Atom elements into RSS feeds.  I've even seen
Chris@0: RDF feeds which use a lot of Atom in place of more common extensions like
Chris@0: Dublin Core.
Chris@0: 
Chris@0: The following is a list of non-Core extensions that are offered, but not registered 
Chris@0: by default. If you want to use them, you'll need to
Chris@0: tell `Zend\Feed\Reader\Reader` to load them in advance of importing a feed.
Chris@0: Additional non-Core extensions will be included in future iterations of the
Chris@0: component.
Chris@0: 
Chris@0: Extension | Description
Chris@0: --------- | -----------
Chris@0: Syndication | Implements Syndication 1.0 support for RSS feeds.
Chris@0: CreativeCommons | An RSS module that adds an element at the `<channel>` or `<item>` level that specifies which Creative Commons license applies.
Chris@0: 
Chris@0: `Zend\Feed\Reader\Reader` requires you to explicitly register non-Core
Chris@0: extensions in order to expose their API to feed and entry objects.  Below, we
Chris@0: register the optional Syndication extension, and discover that it can be
Chris@0: directly called from the entry API without any effort. (Note that
Chris@0: extension names are case sensitive and use camelCasing for multiple terms.)
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Feed\Reader\Reader;
Chris@0: 
Chris@0: Reader::registerExtension('Syndication');
Chris@0: $feed = Reader::import('http://rss.slashdot.org/Slashdot/slashdot');
Chris@0: $updatePeriod = $feed->getUpdatePeriod();
Chris@0: ```
Chris@0: 
Chris@0: In the simple example above, we checked how frequently a feed is being updated
Chris@0: using the `getUpdatePeriod()` method. Since it's not part of
Chris@0: `Zend\Feed\Reader\Reader`'s core API, it could only be a method supported by
Chris@0: the newly registered Syndication extension.
Chris@0: 
Chris@0: As you can also notice, methods provided by extensions are accessible from the
Chris@0: main API using method overloading. As an alternative, you can also directly
Chris@0: access any extension object for a similar result as seen below.
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Feed\Reader\Reader;
Chris@0: 
Chris@0: Reader::registerExtension('Syndication');
Chris@0: $feed = Reader::import('http://rss.slashdot.org/Slashdot/slashdot');
Chris@0: $syndication = $feed->getExtension('Syndication');
Chris@0: $updatePeriod = $syndication->getUpdatePeriod();
Chris@0: ```
Chris@0: 
Chris@0: ### Writing Zend\\Feed\\Reader Extensions
Chris@0: 
Chris@0: Inevitably, there will be times when the `Zend\Feed\Reader` API is just
Chris@0: not capable of getting something you need from a feed or entry. You can use the
Chris@0: underlying source objects, like DOMDocument, to get these by hand; however, there
Chris@0: is a more reusable method available: you can write extensions supporting these new
Chris@0: queries.
Chris@0: 
Chris@0: As an example, let's take the case of a purely fictitious corporation named
Chris@0: Jungle Books. Jungle Books have been publishing a lot of reviews on books they
Chris@0: sell (from external sources and customers), which are distributed as an RSS 2.0
Chris@0: feed. Their marketing department realises that web applications using this feed
Chris@0: cannot currently figure out exactly what book is being reviewed. To make life
Chris@0: easier for everyone, they determine that the geek department needs to extend
Chris@0: RSS 2.0 to include a new element per entry supplying the ISBN-10 or ISBN-13
Chris@0: number of the publication the entry concerns. They define the new `<isbn>`
Chris@0: element quite simply with a standard name and namespace URI:
Chris@0: 
Chris@0: - Name: JungleBooks 1.0
Chris@0: - Namespace URI: http://example.com/junglebooks/rss/module/1.0/
Chris@0: 
Chris@0: A snippet of RSS containing this extension in practice could be something
Chris@0: similar to:
Chris@0: 
Chris@0: ```xml
Chris@0: <?xml version="1.0" encoding="utf-8" ?>
Chris@0: <rss version="2.0"
Chris@0:    xmlns:content="http://purl.org/rss/1.0/modules/content/"
Chris@0:    xmlns:jungle="http://example.com/junglebooks/rss/module/1.0/">
Chris@0: <channel>
Chris@0:     <title>Jungle Books Customer Reviews</title>
Chris@0:     <link>http://example.com/junglebooks</link>
Chris@0:     <description>Many book reviews!</description>
Chris@0:     <pubDate>Fri, 26 Jun 2009 19:15:10 GMT</pubDate>
Chris@0:     <jungle:dayPopular>
Chris@0:         http://example.com/junglebooks/book/938
Chris@0:     </jungle:dayPopular>
Chris@0:     <item>
Chris@0:         <title>Review Of Flatland: A Romance of Many Dimensions</title>
Chris@0:         <link>http://example.com/junglebooks/review/987</link>
Chris@0:         <author>Confused Physics Student</author>
Chris@0:         <content:encoded>
Chris@0:         A romantic square?!
Chris@0:         </content:encoded>
Chris@0:         <pubDate>Thu, 25 Jun 2009 20:03:28 -0700</pubDate>
Chris@0:         <jungle:isbn>048627263X</jungle:isbn>
Chris@0:     </item>
Chris@0: </channel>
Chris@0: </rss>
Chris@0: ```
Chris@0: 
Chris@0: Implementing this new ISBN element as a simple entry level extension would
Chris@0: require the following class (using your own namespace).
Chris@0: 
Chris@0: ```php
Chris@0: namespace My\FeedReader\Extension\JungleBooks;
Chris@0: 
Chris@0: use Zend\Feed\Reader\Extension\AbstractEntry;
Chris@0: 
Chris@0: class Entry extends AbstractEntry
Chris@0: {
Chris@0:     public function getIsbn()
Chris@0:     {
Chris@0:         if (isset($this->data['isbn'])) {
Chris@0:             return $this->data['isbn'];
Chris@0:         }
Chris@0: 
Chris@0:         $isbn = $this->xpath->evaluate(
Chris@0:             'string(' . $this->getXpathPrefix() . '/jungle:isbn)'
Chris@0:         );
Chris@0: 
Chris@0:         if (! $isbn) {
Chris@0:             $isbn = null;
Chris@0:         }
Chris@0: 
Chris@0:         $this->data['isbn'] = $isbn;
Chris@0:         return $this->data['isbn'];
Chris@0:     }
Chris@0: 
Chris@0:     protected function registerNamespaces()
Chris@0:     {
Chris@0:         $this->xpath->registerNamespace(
Chris@0:             'jungle',
Chris@0:             'http://example.com/junglebooks/rss/module/1.0/'
Chris@0:         );
Chris@0:     }
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: This extension creates a new method `getIsbn()`, which runs an XPath query on
Chris@0: the current entry to extract the ISBN number enclosed by the `<jungle:isbn>`
Chris@0: element. It can optionally store this to the internal non-persistent cache (no
Chris@0: need to keep querying the DOM if it's called again on the same entry). The
Chris@0: value is returned to the caller. At the end we have a protected method (it's
Chris@0: abstract, making it required by implementations) which registers the Jungle
Chris@0: Books namespace for their custom RSS module. While we call this an RSS module,
Chris@0: there's nothing to prevent the same element being used in Atom feeds; all
Chris@0: extensions which use the prefix provided by `getXpathPrefix()` are actually
Chris@0: neutral and work on RSS or Atom feeds with no extra code.
Chris@0: 
Chris@0: Since this extension is stored outside of zend-feed, you'll need to ensure your
Chris@0: application can autoload it. Once that's in place, you will also need to ensure
Chris@0: your extension manager knows about it, and then register the extension with
Chris@0: `Zend\Feed\Reader\Reader`.
Chris@0: 
Chris@0: The following example uses `Zend\Feed\Reader\ExtensionPluginManager` to manage
Chris@0: extensions, as it provides the ability to register new extensions without
Chris@0: requiring extension of the plugin manager itself. To use it, first intall
Chris@0: zend-servicemanager:
Chris@0: 
Chris@0: ```bash
Chris@0: $ composer require zendframework/zend-servicemanager
Chris@0: ```
Chris@0: 
Chris@0: From there:
Chris@0: 
Chris@0: ```php
Chris@0: use My\FeedReader\Extension\JungleBooks;
Chris@0: use Zend\Feed\Reader\ExtensionManager;
Chris@0: use Zend\Feed\Reader\ExtensionPluginManager;
Chris@0: use Zend\Feed\Reader\Reader;
Chris@0: 
Chris@0: $extensions = new ExtensionPluginManager();
Chris@0: $extensions->setInvokableClass('JungleBooksEntry', JungleBooks\Entry::class);
Chris@0: Reader::setExtensionManager(new ExtensionManager($extensions));
Chris@0: Reader::registerExtension('JungleBooks');
Chris@0: 
Chris@0: $feed = Reader::import('http://example.com/junglebooks/rss');
Chris@0: 
Chris@0: // ISBN for whatever book the first entry in the feed was concerned with
Chris@0: $firstIsbn = $feed->current()->getIsbn();
Chris@0: ```
Chris@0: 
Chris@0: Writing a feed extension is not much different. The example feed from earlier
Chris@0: included an unmentioned `<jungle:dayPopular>` element which Jungle Books have
Chris@0: added to their standard to include a link to the day's most popular book (in
Chris@0: terms of visitor traffic). Here's an extension which adds a
Chris@0: `getDaysPopularBookLink()` method to the feel level API.
Chris@0: 
Chris@0: ```php
Chris@0: namespace My\FeedReader\Extension\JungleBooks;
Chris@0: 
Chris@0: use Zend\Feed\Reader\Extension\AbstractFeed;
Chris@0: 
Chris@0: class Feed extends AbstractFeed
Chris@0: {
Chris@0:     public function getDaysPopularBookLink()
Chris@0:     {
Chris@0:         if (isset($this->data['dayPopular'])) {
Chris@0:             return $this->data['dayPopular'];
Chris@0:         }
Chris@0: 
Chris@0:         $dayPopular = $this->xpath->evaluate(
Chris@0:             'string(' . $this->getXpathPrefix() . '/jungle:dayPopular)'
Chris@0:         );
Chris@0: 
Chris@0:         if (!$dayPopular) {
Chris@0:             $dayPopular = null;
Chris@0:         }
Chris@0: 
Chris@0:         $this->data['dayPopular'] = $dayPopular;
Chris@0:         return $this->data['dayPopular'];
Chris@0:     }
Chris@0: 
Chris@0:     protected function registerNamespaces()
Chris@0:     {
Chris@0:         $this->xpath->registerNamespace(
Chris@0:             'jungle',
Chris@0:             'http://example.com/junglebooks/rss/module/1.0/'
Chris@0:         );
Chris@0:     }
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: Let's add to the previous example; we'll register the new class with the
Chris@0: extension manager, and then demonstrate using the newly exposed method:
Chris@0: 
Chris@0: ```php
Chris@0: use My\FeedReader\Extension\JungleBooks;
Chris@0: use Zend\Feed\Reader\ExtensionManager;
Chris@0: use Zend\Feed\Reader\ExtensionPluginManager;
Chris@0: use Zend\Feed\Reader\Reader;
Chris@0: 
Chris@0: $extensions = new ExtensionPluginManager();
Chris@0: $extensions->setInvokableClass('JungleBooksEntry', JungleBooks\Entry::class);
Chris@0: $extensions->setInvokableClass('JungleBooksFeed', JungleBooks\Feed::class);
Chris@0: Reader::setExtensionManager(new ExtensionManager($extensions));
Chris@0: Reader::registerExtension('JungleBooks');
Chris@0: 
Chris@0: $feed = Reader::import('http://example.com/junglebooks/rss');
Chris@0: 
Chris@0: // URI to the information page of the day's most popular book with visitors
Chris@0: $daysPopularBookLink = $feed->getDaysPopularBookLink();
Chris@0: ```
Chris@0: 
Chris@0: Going through these examples, you'll note that while we need to register the
Chris@0: feed and entry classes separately with the plugin manager, we don't register
Chris@0: them separately when registering the extension with the `Reader`.  Extensions
Chris@0: within the same standard may or may not include both a feed and entry class, so
Chris@0: `Zend\Feed\Reader\Reader` only requires you to register the overall parent name,
Chris@0: e.g.  JungleBooks, DublinCore, Slash. Internally, it can check at what level
Chris@0: extensions exist and load them up if found. In our case, we have a complete
Chris@0: extension now, spanning the classes `JungleBooks\Feed` and `JungleBooks\Entry`.