RSSFeed package documentation

Introduction

Author

Hugo 'Emacs' HAMON - webmaster@apprendre-php.com - http://www.apprendre-php.com

Presentation

The RSSFeed was built to power valid and complete RSS 2.0 feeds for your website. Generated feeds can be as minimal as possible or very complete. Indeed, every RSS 2.0 tag is supported in this classes package.

The biggest pros of this package is to create RSS 2.0 feeds very easily without to write one XML code line. The programm does it for you !

Environment

The RSSFeed library needs to run on a PHP5 web server because it uses the PHP5 Object Model.

License

The RSSFeed package source is completely open. You can edit, improve or sell it with your web applications.

Installation

Unzip the RSSFeed package on your web server.

Include the RSSFeed.class.php file in your script like this :

<?php
	require_once('path/to/RSSFeed/RSSFeed.class.php');
?>

Generate your RSS 2.0 feed like example scripts.

RSSFeed package

Let's see more in details the five classes, which compose this package.

RSSFeedException

This class provides RSS Feed Exceptions (errors). It herits the native PHP Exception class properties.

RSSFeedTools

The abstract RSSFeedTools class contains a serie of static methods which allow to validate some information for the feed.

RSSFeedBase

The RSSFeedBase script is an abstract class which contains properties and methods that are shared by the two RSSFeed and RSSFeedItem classes. Indeed, both of the feed or item can have a title, description, link, pubDate element and one or more category elements. That's why theses properties are placed in this superclass.

RSSFeed

The RSSFeed file is the main class of the package. It's a concrete class which allows to instanciate a new RSSFeed object. It herits the properties and methods of the RSSFeedBase abstract superclass. Below are listed the public methods that you can apply on the RSSFeed object.

See a method documentation :

RSSFeed::__construct()

Introduction

This is the constructor of the class. It allows to create the new RSSFeed object.

void __construct([string $encoding]);

Parameters

(string) $encoding : the feed encoding.

Example

$myRssFeed = new RSSFeed('utf-8');

RSSFeed::setProtectString()

Introduction

This method allows to set the protect string policy. If the $protectString parameter is set to true, all feed information will be protected. Special characters will be transformed into their html entity equivalent.

void setProtectString(boolean $protectString);

Parameters

(boolean) $protectString : false by default, true to enable the string protection.

Example

$myRssFeed->setProtectString(true);

RSSFeedBase::setTitle()

Introduction

Set the feed title.

void setTitle(string $title);

Parameters

(string) $title : the feed title.

Example

$myRssFeed->setTitle('My RSS2.0 Feed Title');

RSSFeedBase::setDescription()

Introduction

Set the feed description.

void setDescription(string $description);

Parameters

(string) $description : the feed description.

Example

$myRssFeed->setDescription('My RSS2.0 Feed Description');

RSSFeedBase::setLink()

Introduction

Set the feed link.

void setLink(string $link);

Parameters

(string) $link : the feed URI link.

Example

$myRssFeed->setLink('http://www.mywebsite.com/rss/myrssfeed.php');

RSSFeedBase::setCategory()

Introduction

Set a new feed category. Note that a feed can have 0 or more categories elements.

void setCategory(string $domain, string $content);

Parameters

(string) $domain : the category URI.
(string) $content : the category content.

Example

$myRssFeed->setCategory('http://www.technorati.com/posts/tag/php', 'PHP Websites');

RSSFeed::setImage()

Introduction

Set the feed image.

void setImage(string $url, string $title, string $link [, string $description][, int $width][, int $height]);

Parameters

(string) $url : the image URI.
(string) $title : the image caption.
(string) $link : the image link. Note that it's recommanded to provide the same string that the feed link.
(string) $description : the image description.
(int) $width : the image width : 0px < $width < 144px
(int) $height : the image height : 0px < $height < 400px

Example

$myRssFeed->setImage('http://www.mywebsite.com/image/logo.jpg', 'My Website logo', 'http://www.mywebsite.com/rss/myrssfeed.php', 'This is the RSS feed of my blog posts', 100, 80);

RSSFeed::setLastBuildDate()

Introduction

Set the feed last build date.

void setLastBuildDate(string $lastBuildDate);

Parameters

(string) $lastBuildDate : the last build date. Attempt formats : AAAA-MM-DD or AAAA-MM-DD HH:II:SS.

Example

$myRssFeed->setLastBuildDate('2007-09-16 17:19:34');

RSSFeedBase::setPubDate()

Introduction

Set the feed publication date.

void setPubDate(string $setPubDate);

Parameters

(string) $setPubDate : the feed publication date. Attempt formats : AAAA-MM-DD or AAAA-MM-DD HH:II:SS.

Example

$myRssFeed->setPubDate('2007-09-16 17:19:34');

RSSFeed::setTimeToLive()

Introduction

Set the feed time to live. This is the time (in seconds) during the feed is stored in client cache.

void setTimeToLive(int $ttl);

Parameters

(int) $ttl : the feed time to live.

Example

$myRssFeed->setTimeToLive(1080);

RSSFeed::setManagingEditor()

Introduction

Set the managing editor of the feed.

void setManagingEditor(string $email [, $name]);

Parameters

(string) $email : the manager email.
(string) $name : the manager name.

Example

$myRssFeed->setManagingEditor('me@mywebsite.com','John Doe');

RSSFeed::setWebMaster()

Introduction

Set the website webmaster.

void setWebMaster(string $email [, $name]);

Parameters

(string) $email : the webmaster email.
(string) $name : the webmaster name.

Example

$myRssFeed->setWebMaster('me@mywebsite.com','John Doe');

RSSFeed::setCopyright()

Introduction

Set the feed copyright.

void setCopyright(string $copyright);

Parameters

(string) $copyright : the feed copyright.

Example

$myRssFeed->setCopyright('(C) Copyright 2007 - My Website - All rights reserved');

RSSFeed::setRating()

Introduction

Set the feed rating.

void setRating(string $rating);

Parameters

(string) $rating : the feed rating.

Example

$myRssFeed->setRating('(PICS-1.1 "http://www.classify.org/safesurf/" l r (SS--000 1))');

RSSFeed::setGenerator()

Introduction

Set the feed generator.

void setGenerator(string $generator);

Parameters

(string) $generator : the feed generator.

Example

$myRssFeed->setGenerator('Powered with the RSSFeed package');

RSSFeed::setLanguage()

Introduction

Set the feed language.

void setLanguage(string $language);

Parameters

(string) $language : the feed language with 2 characters.

Example

$myRssFeed->setLanguage('en');

RSSFeed::setDocs()

Introduction

Set the feed documentation.

void setDocs(string $docs);

Parameters

(string) $docs : the feed documentation.

Example

$myRssFeed->setDocs('http://fr.wikipedia.org/wiki/RSS_(format)');

RSSFeed::setSkipDay()

Introduction

Set a new skip day. A skip day indicates a day when the feed hasn't to be refreshed. A feed can have more than one skip day. Note that if you provide the seven week days, your RSS 2.0 feed won't be refreshed anymore.

void setSkipDay(string $day);

Parameters

(string) $day : the skip day. Attempt values : Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.

Example

$myRssFeed->setSkipDay('Monday');

RSSFeed::setSkipHour()

Introduction

Set a new skip hour. A skip hour indicates a time when the feed hasn't to be refreshed in a day. A feed can have more than one skip hour.

void setSkipHour(int $hour);

Parameters

(int) $hour : the skip hour. Attempt values : from 0 to 23.

Example

$myRssFeed->setSkipHour(20);

RSSFeed::setCloud()

Introduction

Set the feed cloud.

void setCloud(string $domain, int $port, string $path, string $registerProcedure, string $protocol);

Parameters

(string) $domain : the host domain name of the server to register.
(int) $port : port tu use.
(string) $path : path of the script on the web server.
(string) $registerProcedure : name of the register procedure.
(string) $protocol : the protocol : xml-rpc or soap.

Example

$myRssFeed->setCloud('http://www.oreilly.com', 80, '/RPC2', 'pleaseNotify', 'XML-RPC');

RSSFeed::appendItem()

Introduction

Add a new RSSFeedItem object to the feed.

void appendItem(RSSFeedItem $item);

Parameters

(RSSFeedItem) $item : the item object.

Example

$myRssFeed->appendItem($myItem);

RSSFeed::display()

Introduction

Display the generated feed.

void display();

Parameters

No parameter for this method.

Example

$myRssFeed->display();

RSSFeed::regenerate()

Introduction

Regenerate the feed.

void regenerate();

Parameters

No parameter for this method.

Example

$myRssFeed->regenerate();

RSSFeed::save()

Introduction

Save the feed in a XML file on the web server.

void save([string $xmlFileName]);

Parameters

(string) $xmlFileName : the xml file name.

Example

$myRssFeed->save('myRssFeed.xml');

RSSFeedItem

The RSSFeedItem file is the second important class of the package. It's a concrete class which allows to instanciate a new RSSFeedItem object. It herits the properties and methods of the RSSFeedBase abstract superclass. Below are listed the public methods that you can apply on the RSSFeedItem object.

See a method documentation :

RSSFeedItem::__construct()

Introduction

This is the constructor of the class. It allows to create the new RSSFeedItem object.

void __construct();

Parameters

No parameter for this method.

Example

$myRssItem = new RSSFeedItem();

RSSFeedBase::setTitle()

Introduction

Set the item title.

void setTitle(string $title);

Parameters

(string) $title : the item title.

Example

$myRssItem->setTitle('My RSS2.0 Item Title');

RSSFeedBase::setDescription()

Introduction

Set the item description.

void setDescription(string $description);

Parameters

(string) $description : the item description.

Example

$myRssItem->setDescription('My RSS2.0 Item Description');

RSSFeedBase::setLink()

Introduction

Set the item link.

void setLink(string $link);

Parameters

(string) $link : the item URI link.

Example

$myRssItem->setLink('http://www.mywebsite.com/blog/post.php?idPost=53');

RSSFeedBase::setCategory()

Introduction

Set a new item category. Note that an item can have 0 or more categories elements.

void setCategory(string $domain, string $content);

Parameters

(string) $domain : the category URI.
(string) $content : the category content.

Example

$myRssItem->setCategory('http://www.technorati.com/posts/tag/ajax', 'Ajax Websites');

RSSFeedBase::setPubDate()

Introduction

Set the item publication date.

void setPubDate(string $setPubDate);

Parameters

(string) $setPubDate : the item publication date. Attempt formats : AAAA-MM-DD or AAAA-MM-DD HH:II:SS.

Example

$myRssItem->setPubDate('2007-09-16 17:19:34');

RSSFeedItem::setAuthor()

Introduction

Set the item author.

void setAuthor(string $email [, string $name]);

Parameters

(string) $email : the author email.
(string) $name : the author name.

Example

$myRssItem->setAuthor('someone@somewhere.com','Jane Smith');

RSSFeedItem::setComments()

Introduction

Set the item comments URI of a post.

void setComments(string $comments);

Parameters

(string) $comments : the comments URI.

Example

$myRssItem->setComments('http://www.mywebsite.com/blog/post.php?idPost=53#comments');

RSSFeedItem::setEnclosure()

Introduction

Set the item enclosure element.

void setEnclosure(string $url, int $length, string $mimeType);

Parameters

(string) $url : the media URI.
(int) $length : the length in bytes of the media.
(string) $mimeType : the media mimeType.

Example

$myRssItem->setEnclosure('http://www.mywebsite.com/image.jpg',2800,'image/jpg');

RSSFeedItem::setGuid()

Introduction

Set the unique item guid element.

void setGuid(string $url, boolean $isPermaLink);

Parameters

(string) $url : the guid link.
(boolean) $isPermaLink : specify if the link is permanent or not

Example

$myRssItem->setGuid('http://www.mywebsite.com/blog/post.php?idPost=53',true);

RSSFeedItem::setSource()

Introduction

Set the item source element.

void setSource(string $url, string $content);

Parameters

(string) $url : the source link.
(string) $content : ths source name link

Example

$myRssItem->setSource('http://www.anothersite.com/article.php?id=8','Using a PHP5 Framework');

Examples

See the scripts in the RSSFeed/examples/ directory.

Generate a minimal RSS 2.0 feed from MySQL

<?php

	// Import the RSSFeed class
	require_once('path/to/RSSFeed/RSSFeed.class.php');

	// MySQL Connection
	$connection = mysql_connect('localhost','root','example');
	mysql_select_db('website', $connection);
	
	try
	{
		// Create the new instance of the RSS Feed
		$rssFeed = new RSSFeed('utf-8');
		// Activate the string protection
		$rssFeed->setProtectString(true);
		// Set the feed title
		$rssFeed->setTitle('My blog : the best in the world');
		// Set the feed description
		$rssFeed->setDescription('A little blog, which talks about Web programming');
		// Set the feed link
		$rssFeed->setLink('http://www.mywebsite.com/blog/rss/posts.php');
		// Set the feed publication date
		$rssFeed->setPubDate('2007-08-01');
		// Set the feed last build date
		$rssFeed->setLastBuildDate(date('Y-m-d'));
		// Set the feed webmaster
		$rssFeed->setWebMaster('me@mywebsite.com','John Doe');
		// Set the feed managing editor
		$rssFeed->setManagingEditor('me@mywebsite.com','John Doe');
		// Set the feed image
		$rssFeed->setImage('http://www.mywebsite.com/image/logo.jpg','My Logo','My blog',100,200);
		
		// Adding items
		$request = mysql_query('SELECT post_id, post_title, post_description, post_author_email, post_author_name, post_date FROM post WHERE post_valid=1 LIMIT 10');
		
		while($row = mysql_fetch_object($request))
		{
			// Creating a new feed item
			$rssItem = new RSSFeedItem();
			$rssItem->setTitle($row->post_title);
			$rssItem->setDescription($row->post_description);
			$rssItem->setLink('http://www.mywebsite.com/blog/post.php?id='. $row->post_id);
			$rssItem->setGuid('http://www.mywebsite.com/blog/post.php?id='. $row->post_id, true);
			$rssItem->setComments('http://www.mywebsite.com/blog/post.php?id='. $row->post_id .'#comments');
			$rssItem->setAuthor($row->post_author_email, $row->post_author_name);
			$rssItem->setPubDate($row->post_date);
			
			// Add the item to the feed
			$rssFeed->appendItem($rssItem);
		}
		
		// Save the feed
		$rssFeed->save();
		
		// SQL connection closing
		mysql_close();
		
		// Send headers to the browser
		header('Content-Type: text/xml; charset=utf-8');
		// Display the feed
		$rssFeed->display();
	}
	catch(RSSFeedException $e)
	{
		echo $e->getErrorMessage();	
	}
?>