The sfFeed2Plugin offers an object interface for feeds and feed items, feed input methods using a web feed or an array of objects as source, and feed output methods for displaying items on a page and serving feeds through a symfony application.

Developers

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Release 0.9.2 - 03/03/2007

Release 0.9.1 - 22/02/2007

Release 0.9.0 - 21/02/2007

Release 0.8.1 - 19/02/2007

Release 0.8.0 - 18/02/2007

sfFeed2 plugin

The sfFeed2Plugin offers an object interface for feeds and feed items, feed input methods using a web feed or an array of objects as source, and feed output methods for displaying items on a page and serving feeds through a symfony application.

Possible uses

serving a RSS/Atom feed based on model objects

Using web feeds as data source

Feed aggregator

As compared with the sfFeedPlugin, this plugin has a cleaner code separation in classes and offers more features. The syntax differs, but many classes have the same names, therefore the two plugins are not compatible.

The Post class is extended by a getStrippedTitle() method that transforms the title into a string that can be used in an URI, replacing spaces by dashes, upper case by lower case, and removing all special characters:

Using the creators and setters

To build the feed, you need to initialize it with a certain format and options, and to add feed items based on the objects resulting from a database request. With the syntax of the sfFeed and sfFeedItem class, that would give:

At the end of the action, the $feed variable contains a sfAtom1Feed object which includes several sfFeedItem objects. To transform the object into an actual Atom feed, the lastPostsSuccess.php template simply contains:

<?php decorate_with(false) ?>
<?php echo $feed->asXml() ?>

The content type is automatically set by the asXML() method, depending on the feed format (Atom1 in this example).

When called from a feed aggregator, the result of the action is now exactly the Atom feed described above:

http://www.myblog.com/feed/lastPosts

Using the initialize() method

The use of all the setters for the feed and item construction can be a little annoying, since there is a lot of information to define. Both the sfFeed and the sfFeedItem classes provide an initialize() method that uses an associative array for a shorter syntax:

The rules governing the sfFeedPeer::convertObjectsToItems algorithm are as follows:

To set the item title, it looks for a getFeedTitle(), a getTitle(), a getName() or a __toString() method.

In the example, the Post object has a getName() method.

To set the link, it uses the second argument of the method call, which is supposed to be a route name for the feed items. If there is one, it looks in the route url for parameters for which it could find a getter in the object methods. If not, it looks for a getFeedLink(), getLink(), getUrl() method in the object.

In the example, the route name given as parameter is @permalink. The routing rule contains a :stripped_title parameter and the Post object has a getStrippedTitle() method, so the convertObjectsToItems method is able to define the URIs to link to.

To set the author's email, it looks for a getFeedAuthorEmail or a getAuthorEmail. If there is no such method, it looks for a getAuthor(), getUser() or getPerson() method. If the result returned is an object, it looks in this object for a getEmail or a getMail method.

In the example, the Post object has a getAuthor(), and the Author object has a getName(). The same kind of rules is used for the author's name and URL.

To set the publication date, it looks for a getFeedPubdate(), getPubdate(), getCreatedAt() or a getDate() method.

In the example, the Post object has a getCreatedAt

The same goes for the other possible fields of an Atom feed (including the categories, the summary, the unique id, etc.), and you are advised to the source of the sfFeed class(http://www.symfony-project.com/trac/browser/plugins/sfFeed2Plugin/lib) to discover all the deduction algorithms.

All in all, the way the accessors of the Post and Author objects are built allow the built-in algorithm of the convertObjectsToItems method to work, and the creation of the feed to be more simple.

Defining custom values for the feed

In the list of rules presented above, you can see that the first method name that the sfFeed object looks for is always a getFeedXXX(). This allows you to specify a custom value for each of the fields of a feed item by simply extended the model.

For instance, if you don't want the author's email to be published in the feed, just add the following getFeedAuthorEmail() method to the Post object:

public function getFeedAuthorEmail()
{
return '';
}

This method will be found before the getAuthor() method, and the feed will not disclose the publishers' email addresses.

Using the sfFeedPeer static methods

The sfFeedPeer class offer helper methods that facilitate the creation and population of feed items.

When the feed format is determined at runtime, create feed objects using the sfFeedPeer::newInstance() method, which is a factory, rather that using the new command:

Fetching a feed from the web and displaying it

You may want to display the latest posts of the symfony users group in your application. The steps to retrieve this information are to fetche a feed from the Internet, create an empty feed object, and populate it with the items of the feed. You can use the fromXML() method and the [sfWebBrowserPlugin](http://www.symfony-project.com/trac/wiki/sfWebBrowserPlugin) for that:

The createFromWeb() method first parse the response and tries to recognize a known feed format (RSS or Atom - The recognized formats are the same ones as above). Note that this method depends on the sfWebBrowserPlugin, so this plugin must be installed to make the method work.

Once the feed is built, it is very easy to use it for the display in the template:

Aggregating several feeds

The sfFeedPeer class contains a mathod called aggregate(), which merges several feeds and reorders the items chronologically. Using it is very simple: just pass an array of feeds as parameters, and you receive a new feed object with all the items within.

For instance, here is how you could display the posts of both the users and the devs groups: