Atom Builder

Introduction

Eine deutsche Version dieses Dokuments ist ebenfalls vorhanden!

Atom Builder are PHP classes which output Atom feeds according to the Working Draft 1.0. The classes API is similar to the RSS Builder classes. Notice: The code has only been tested with PHP 5.2.0 so far.

Create the feed-class

First we create an instance of the base class:

include_once '../inc/class.AtomBuilder.inc.php';
$atom = new AtomBuilder('Title of the Feed', 'http://example.com/link_to_feed', 'tag:flaimo@example.com,2004-12-31:link_to_feed');

As you can see we need three aguments for the constructor. All of them are required for every Atom Feed you want to create. The first argument is the title of the feed. The second argument is the URL of the feed and the last argument is the ID of the feed which has to be unique worldwide. Unique IDs are also used for the entries later on. There’s also a tutorial on how to create unique IDs which you should read before creating IDs for your feed.

Another required attribute is the information when the feed was last updated:

$atom->setUpdated('2005-10-20T10:04:00Z');	

All date/time attributes have to be passed to the classes as valid ISO.8601.1988 constructs. If you don’t set the Date manually, it automatically uses the current time. Hint: Since PHP 5 you can format dates with date('c', $timestamp) to get a valid ISO date string.

Now we can add some additional information to the feed. Most of them are selfexplaining:

$atom->setEncoding('UTF-8');
$atom->setLanguage('en');
$atom->setSubtitle('Description of the feed');
$atom->setRights('2008 © Example.com');
$atom->setIcon('http://flaimo.com/16x16_icon.png');
$atom->setLogo('http://flaimo.com/100x50_logo.png');
$atom->setAuthor('Flaimo', 'flaimo@example.com', 'http://example.com/');
$atom->addContributor('Jörg', 'joerg@example.com');
$atom->addContributor('Joe');

Subtitle is a short description of the feed. You can also add information about the author and contributors. There can only be one author per feed (and later on for each entry) but there can be multiple contributors. Everytime you add information about a person you need three arguments: The first argument is the name of the person and is required. The other two arguments are the e-mail address and the URL of the homepage which are optional.

For the feed, as for each entry, you can add information about links and categories:

$atom->addLink('http://php.net/', 'Official PHP homepage', 'related', 'text/html', 'en');
$atom->addLink('http://example.com/', 'Example.com – HTML Homepage', 'alternate', 'text/html', 'en');
$atom->addCategory('Webdesign', 'http://www.example.com/tags', 'Web 2.0 Webdesign');
$atom->addCategory('PHP', 'http://www.example.com/tags', 'PHP-Scripting');

For every link you add you can pass up to five arguments to the method. The first argument is the URL of the link. The second argument is the description of the URL. The third one is the relation of the link to the feed/entry. Possible values are:

• alternate
• related
• self
• enclosure
• via

The forth argument is the MIME-Type of the link and the last argument is the language. Only the first argument is required, the others are optional.

Just like the link method, the category method has some arguments too. The first one is the name of the category and is required. The second is the scheme and the third one a human readable description of the category.

Create entries

Now we can start to add the single entries of the feed:

$entry_1 = $atom->newEntry('Title of the Entry', 'http://example.com/permalink_to_first_entry', 'tag:flaimo@example.com,2004-12-31:permalink_to_first_entry/detail/1');
$entry_1->setUpdated(''2005-10-29T14:44:00Z'');

As you can see, the required information for an entry is the same as for creating a feed.

The other optional information you can add for each entry is also the same:

$entry_1->setPublished('2005-10-29T14:34:00.25Z'); // First published on this date
$entry_1->setAuthor('Flaimo', 'flaimo@example.com', 'http://example.com/');
$entry_1->addContributor('Matt', 'matt@example.com');
$entry_1->addContributor('Joe', '', 'http://joespage.com');
$entry_1->setRights('20086 © Example.com');
$entry_1->addLink('http://slashdot.org/', 'slashdot.org', 'via', 'text/html', 'en');
$entry_1->addLink('http://orf.com/', 'ORF ON', 'related', 'text/html', 'de');
$entry_1->addLink('http://netwold.com/', 'News Networld', 'related', 'text/html', 'de');
$entry_1->addCategory('Webdesign', 'http://www.flaimo.com/tags', 'Web 2.0 Webdesign');

For adding actual content you can use the following methods:

$entry_1->setSummary('A short summary of the entry');

$entry_1->setContent('The whole content of the <b>feed</b>', 'html');

I guess Summary is selfdescribing. For displaying the whole content you can use the Content method. Whenever you can add a Title, Subtitle, Summary or Content you can pass a second argument to the method on how the string should be handled. Possible values are text, html and xhtml. For Content elements you can also use any valid MIME-Type.

After you have entered all relevant information about an entry you can add it to the feed:

$atom->addEntry($entry_1);

Further entries are created the same way. Finally we have to return the final output. You have three possibilities:

$atom->outputAtom(1.0.0);

$foo = $atom->getAtomOutput('1.0.0');

echo $atom->saveAtom('1.0.0', 'path/to/folder');

With outputAtom the finalized feed is put out as MIME-Type application/atom+xml. With getAtomOutput you can pass the xml-code to a variable. With saveAtom you can save the feed as an xml file to the specified path and the filename is returned. All three methods take the version which should be created as the first argument. At the moment only 1.0.0 is available.

Further reading

• AtomBuilder – Sampleoutput
• What is Atom?
• Atom 1.0 draft
• Date and Time Formats
• A directory of AtomEnabled software and services