Chris@0: # Consuming RSS Feeds
Chris@0: 
Chris@0: ## Reading a feed
Chris@0: 
Chris@0: To read an RSS feed, pass its URL to `Zend\Feed\Reader\Reader::import()`:
Chris@0: 
Chris@0: ```php
Chris@0: $channel = Zend\Feed\Reader\Reader::import('http://rss.example.com/channelName');
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: If any errors occur fetching the feed, a
Chris@0: `Zend\Feed\Reader\Exception\RuntimeException` will be thrown.
Chris@0: 
Chris@0: ## Get properties
Chris@0: 
Chris@0: Once you have a feed object, you can access any of the standard RSS channel
Chris@0: properties via the various instance getter methods:
Chris@0: 
Chris@0: ```php
Chris@0: echo $channel->getTitle();
Chris@0: echo $channel->getAuthor();
Chris@0: // etc.
Chris@0: ```
Chris@0: 
Chris@0: If channel properties have attributes, the getter method will return a key/value
Chris@0: pair, where the key is the attribute name, and the value is the attribute value.
Chris@0: 
Chris@0: ```php
Chris@0: $author = $channel->getAuthor();
Chris@0: echo $author['name'];
Chris@0: ```
Chris@0: 
Chris@0: Most commonly, you'll want to loop through the feed and do something with its
Chris@0: entries.  `Zend\Feed\Reader\Feed\Rss` internally converts all entries to a
Chris@0: `Zend\Feed\Reader\Entry\Rss` instance. Entry properties, similarly to channel
Chris@0: properties, can be accessed via getter methods, such as `getTitle`,
Chris@0: `getDescription`, etc.
Chris@0: 
Chris@0: An example of printing all titles of articles in a channel is:
Chris@0: 
Chris@0: ```php
Chris@0: foreach ($channel as $item) {
Chris@0:     echo $item->getTitle() . "\n";
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: If you are not familiar with RSS, here are the standard elements you can expect
Chris@0: to be available in an RSS channel and in individual RSS items (entries).
Chris@0: 
Chris@0: Required channel elements:
Chris@0: 
Chris@0: - `title`: The name of the channel.
Chris@0: - `link`: The URL of the web site corresponding to the channel.
Chris@0: - `description`: A sentence (or more) describing the channel.
Chris@0: 
Chris@0: Common optional channel elements:
Chris@0: 
Chris@0: - `pubDate`: The publication date of this set of content, in RFC 822 date
Chris@0:   format.
Chris@0: - `language`: The language the channel is written in.
Chris@0: - `category`: One or more (specified by multiple tags) categories the channel
Chris@0:   belongs to.
Chris@0: 
Chris@0: RSS `<item>` elements do not have any strictly required elements. However,
Chris@0: either `title` or `description` must be present.
Chris@0: 
Chris@0: Common item elements:
Chris@0: 
Chris@0: - `title`: The title of the item.
Chris@0: - `link`: The URL of the item.
Chris@0: - `description`: A synopsis of the item.
Chris@0: - `author`: The author's email address.
Chris@0: - `category`: One more categories that the item belongs to.
Chris@0: - `comments`: URL of comments relating to this item.
Chris@0: - `pubDate`: The date the item was published, in RFC 822 date format.
Chris@0: 
Chris@0: In your code you can always test to see if an element is non-empty by calling
Chris@0: the getter:
Chris@0: 
Chris@0: ```php
Chris@0: if ($item->getPropname()) {
Chris@0:     // ... proceed.
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: Where relevant, `Zend\Feed` supports a number of common RSS extensions including
Chris@0: Dublin Core, Atom (inside RSS); the Content, Slash, Syndication,
Chris@0: Syndication/Thread extensions; as well as several others.
Chris@0: 
Chris@0: Please see the official [RSS 2.0 specification](http://cyber.law.harvard.edu/rss/rss.html)
Chris@0: for further information.