Finweblog - Matěj „Finwë“ Humpál

PHP třída generující RSS

Měl jsem potřebu moci do kteréhokoliv svého projektu jednoduše přidat RSS feed, nezávisle na struktuře dat v databázi, a na zdroji dat vůbec. Na internetu jsem buď líný hledat, nebo nic takového, co by mi vyhovovalo, neexistuje. Tím pádem vznikla třída Rss (možná ještě přejmenuji), volně k použití pod licencí CC Attribution-ShareAlike 2.5

Potřeby, vlastnosti

• Co nejjednodušší konfigurace, která je zároveň v kódu přehledná
• Minimální nároky na moduly PHP (samo PHP5 je velkým nárokem)
• nezávislý na struktuře databáze
• kontroluje výstupní data („sofistikované“ omezení délky pro description + uzavření textu do CDATA)
• předpřipravené funkce na získání dat z MySQL 4.0+
• možnost nastavit vlastní (externí) funkci pro zisk dat z libovolného zdroje

Ukázka

Nejprve je samozřejmě potřeba includovat potřebné soubory a vytvořit třídu:

require_once 'rss.class.php';
$rss = new Rss;

Nadchází nastavení vlastností daného RSS:

Jako první nastavme handler pro získání dat z databáze. Hodnota je používána pro callback, nelze tedy specifikovat parametry, ale je možné (krom interních handlerů) volat jak externí funkci, tak statickou metodu třídy.

Samotná třída Rss má dva handlery vestavěné – pro obě varianty práce s MySQL. Defaultní handler je MySQL 4.0, ten tedy není potřeba explicitně nastavovat.

// Použijme MySQL 4.1+ handler, vestavěný ve třídě
$rss->setdbCallback(array('Rss', 'getMysqliData'));

Jako první nastavme základní statické vlastnosti RSS feedu

$rss->settitle('Finweblog');
$rss->setlink('http://weblog.finwe.info');
$rss->setdescripton('Finweblog - Matěj Finwe Humpál - Webdesign, Turistika, Muzika');
$rss->setlanguage('cs');

Rss třída v základě rozpoznává 10 základních typů RSS tagů (guid, link, description, comments, title, author, source, category, enclosure, pubDate). Pokud je v klíči pole Rss::dbFields nastaven jiný string, může se přihodit, že budeme potřebovat přidat do hlavičky RSS určitý namespace: (definice tagů viz níže)

// budu používat wfw:commentRSS, musím nadefinovat namespace
$rss->addNamespace('xmlns:wfw','http://wellformedweb.org/CommentAPI/');

Teď nastavíme detaily spojení s databází. Pokud jsme použili vlastní externí handler, můžeme tyto kroky vynechat.

$rss->setdbHost('localhost');
$rss->setdbUser('user');
$rss->setdbPass('pass');
$rss->setdbName('name');
$rss->setdbPort('3307');

Nastavení dotazu pro vyhledání správných polí ve správné tabulce. Náleží také pouze interním datahandlerům.

$rss->setdbSql("SELECT id, seo_url, title, perex, timestamp, gr
                FROM blog WHERE status = 'published'
                ORDER BY timestamp DESC
                LIMIT 15");

A nyní nastává ta pravá zábava. Data handler nám vrátil pole s položkami ve formátu 'jmeno-sloupce'=>'hodnota'. Nastavíme, které sloupce se mají použít pro který tag RSS.

$rss->setdbFields(array(
        'link' => 'seo_url', // Proměnná pro použití v tagu link. Viz dále
        'title' => 'title',
        'description' => 'perex',
        'comments' => 'id', // Proměnná pro použití v tagu comments. Viz dále
        'category' => 'gr',
        'pubDate' => 'timestamp' // třída očekává typ UNIX_TIMESTAMP
        // Příklad osobního tagu:
        // 'wfw:commentRSS' => 'id', // pokud tag bude mít pouze hodnotu z tabulky
        // 'wfw:commentRSS' => array(array('id','seo_url'),'http://weblog.finwe.info/rss-comments.php?id=%s&%s') //pokud bude mít tag více proměnných zasazených do stringu
        'wfw:commentRSS' => array('id','http://weblog.finwe.info/rss-comments.php?id=%s') // pokud má tag jednu proměnnou zasazenou do stringu
));

Nastavíme řetězce, které se použijí pro zkombinování URL pro tagy link a comments

// linky musejí být absolutní
$rss->setpostLink('http://weblog.finwe.info/item/%s');
$rss->setcommentsLink('http://weblog.finwe.info/rss-comments.php?id=%s');

Až do teď jednoduché. Ale co když potřebujeme v řetězci víc proměnných? Bez problému, stačí v Rss::dbFields nastavit jako hodnotu klíče link/comments pole s potřebným počtem proměnných.

$rss->setdbFields(array(
        ...
        'link' => array('id','seo_url'),
        ...;
$rss->setpostLink('/item/%s/komentar-%s');

Hotovo, zbývá jen odeslat feed na výstup.

$rss->display();

Vychytávky

• třída automaticky utne tag description tak, aby končil okolo 450. znaku, nikdy uprostřed slova, a pokud ano, na konec přidá tři tečky
• pokud chcete před tag title vložit statický řetězec, hodnota klíče title bude pole s položkami sloupec-tabulky,řetězec
• pro úpravu tagů, které nemají vlastní formátovací řetězec, můžete využít následujícího triku (stejný postup, jako při přidávání custom tagů):

$rss->setdbFields(array(
        ...
        'title' => array('id','Formát %s'), // Pro jednu proměnnou
        'author' => array(array('id,author'),'%s formát %s') // Pro více proměnných
        ...;
$rss->setpostLink('/item/%s/komentar-%s');

Verzování, licence, download

Momentálně se třída nachází ve versi 1.2.5. Bugreport i feature-request je vítán, na mail, nebo zde v komentářích, postupně snad vychytám(e) mouchy a přidám(e) třeba i nějaké ty třešničky na dort.

Licence celého třídy je CC Attribution-ShareAlike 2.5

Automaticky generovaná dokumentace s anglickými komentáři a příklady

Třídu Rss ve verzi 1.3 stahujte zde (ZIP, 5kiB)

Changelog

Co dodat?

Objevuji Ameriku? Objevuji ji rád. Toto je můj první veřejný dokončený projekt, mám z něj radost a ta mi snad dodá energii pro další rozpracované projekty. Ale o nich třeba příště.

P. S. Za oponenturu a lehký feature-request díky Andrewovi

Komentáře

RSS feed komentářů k tomuto článku

setConnParams(array('host' => 'localhost', 'user' => 'lojza'));