In questo lungo articolo dedicato ai neofiti di PHP, completo per questo di molto codice commentato, cercheremo di fornire un'introduzione e semplici esempi d'uso per MagpieRSS, una potente e semplice libreria che è in grado di manipolare con PHP diversi formati di feed RSS. Con MagpieRSS potrete recuperare, formattare e includere all'interno di siti in PHP i principali feed RSS disponibili su siti Web. La classe ha incluso anche un sistema di caching per evitare di appesantire il server con continue richieste remote.
Prima di iniziare a descrivere la classe è necessario capire cosa sia un feed RSS. Non ci vogliamo dilungare troppo nel spiegarvi quello che su Html.it è già stato scritto e riscritto decine di volte. In poche righe: i feed (nei formati RSS o Atom) servono per poter condividere e mostrare gli aggiornamenti avvenuti su siti Web, il tutto in tempo reale e con più velocità. Esempi di feed sono nella pagina dei feed RSS di Html.it. Su ITCv è inoltre presente un video che spiega nei dettagli cosa sia questa tecnologia.
Cosa è MagpieRSS
MagpieRSS, o semplicemente Magpie, è una delle migliori classi in PHP attualmente presenti sul web per il parsing dei feed. Inutile dire che è del tutto gratuita e utilizzabile liberamente, basta solamente eseguire il download dal sito ufficiale e seguire la nostra guida. La potenzialità della classe è caratterizzata dalla sua semplicità: con poche righe di codice lo si può inserire in ogni script.
Magpie supporta i formati feed più importanti, cioè Atom e RSS. In particolare lo script supporta le versioni 0.9 e 1.0 per RSS e 0.3 per Atom.
Impostazioni e primo esempio
Come già accennato in precedenza la potenzialità di questo script è la semplicità. Vedremo infatti come sia possibile, semplicemente inserendo poche righe di codice, leggere i nostri feed. Non dovete tuttavia farvi trarre in inganno dalla parola "semplicità" Anche se è semplice da utilizzare, la classe comprende parecchie funzioni utili e professionali.
Le prime operazioni da fare nella stesura del codice sono le solite: inclusioni dei file principali e definizione della variabile relativa all'indirizzo (o URL) del feed.
<?php //Includiamo Magpie nel nostro script require_once('rss_fetch.inc'); //Impostiamo l'url riferito al feed da analizzare $url = 'http://rss.html.it/guide.xml'; //Richiamo della funzione di Magpie che analizza ed elabora il feed $rss = fetch_rss($url);
Fino a qui non ci sono problemi; le righe di codice inserite sono facili da comprendere. La funzione fetch_rss($url) analizza diversi aspetti del feed: per prima cosa verifica che l'URL che avete inserito sia valido secondo gli standard e poi verifica che sia raggiungibile. Nel caso si verifichi qualche errore la funzione rilascia come output valore FALSE e un messaggio per permettere allo sviluppatore di sistemare il problema. Più avanti vedremo come gestire eventuali errori.
Procediamo con il resto del codice:
//Ciclo if che verifica se è stato inserito il feed senza errori if ($rss) { //In questa parte vengono stampate le informazioni generali del feed echo "<h1><a href="". $rss -> channel['link'] ."">". $rss -> channel['title'] ."</a></h1>"; echo "<p>". $rss -> channel['description'] ."</p>";
In questa parte del listato abbiamo un ciclo IF che ci permette di uscire dallo script e di elaborare tutto il codice nel caso in cui Magpie abbia trovato uno o più errore nel parsing del feed. Ciò evita di stampare all'utente errori inutili e porzioni di codice senza senso.
Se il controllo è positivo allora lo script inizia a stampare i primi dati del feed. Come potete vedere la programmazione ad oggetti di Magpie permette di restituire i valori richiesti richiamando l'array channel[]. A quest'ultimo array assegneremo come indice il nome del sottoelemento di "channel" che volete visualizzare.
Illustriamo meglio la parte finale dello script. Come potete vedere la potenzialità di Magpie è che siete in grado di inserire l'output del feed in qualsiasi <div> o tag HTML. Questo ci permette una personalizzazione completa della grafica dell'output. Nel nostro esempio (è evidenziato in rosso nel codice sopra) abbiamo inserito il titolo nel tag <h1></h1>, ma potevo benissimo inserirlo in un <div> o in altro.
Continuiamo con il codice:
//Inserisco un titolo echo "<h2>Elenco guide:</h2>"; //Inizio il listato echo "<ul>"; //Scompongo e stampo l'array del feed foreach ($rss -> items as $feed) { echo "<li>". "<a href="". $feed['link'] ."">". $feed['title'] ."</a><br />". "<small>". $feed['description'] ."</small>". "</li>"; }
Terminiamo quindi il codice del nostro esempio con questo ultimo pezzo:
//Concludo il listato e chiudo lo script
echo "</ul>";
}
?>
L'ultima parte inserite ci permette di stampare ogni singolo componente del feed. Magpie immagazzina i sottoelementi di <channel>, cioè gli <item>, in un array. Per questo utilizziamo un ciclo FOR per estrarli tutti. Anche qui i dati sono inseriti all'interno di semplice codice HTML: dato che avevamo aperto la lista con <ul> dobbiamo includere ognuno di essi all'interno dei TAG <li> </li> per definire la lista.
Opzioni di lettura
Ora abbiamo uno script funzionante e pronto per essere testato. Qui sotto potete vedere un'immagine che mostra il risultato:
Dopo aver illustrato un piccolo esempio vediamo come sfruttare al meglio MagpieRSS: è una classe molto efficace e personalizzabile. Come abbiamo detto prima, Magpie ci permette di inserire i "canali" del feed dove vogliamo, semplicemente personalizzando lo script PHP per restituire l'output.
Se qualcuno ci ha fatto caso, il feed di Html.it (http://rss.html.it/guide.xml) che ho selezionato per il nostro primo esempio non comprende solamente gli items title, link e description; ma ne comprende anche altri, oltre a quelli citati sopra abbiamo: pubDate, category e guid, come mostrato nella porzione di feed pubblicata qui sotto.
<item> <title><![CDATA[ Guida Microsoft SQL Server 2005 ]]></title> <link>http://database.html.it/guide/leggi/133/guida-microsoft-sql-server-2005/</link> <description><![CDATA[ L'RDBMS di Microsoft è uno dei più utilizzati ]]></description> <pubDate>Thu, 26 Jul 2007 13:00:00 +0200</pubDate> <category>Database</category> <guid>http://database.html.it/guide/leggi/133/guida-microsoft-sql-server-2005/</guid> </item>
Mettiamo quindi che vogliamo mostrare solamente i tag title, link e pubdate; come possiamo fare??
Semplice, ecco il codice:
<? //Includiamo Magpie nel nostro script require_once('rss_fetch.inc'); //Impostiamo l'url riferito al feed da analizzare $url = 'http://rss.html.it/guide.xml'; //Richiamo della funzione di Magpie che analizza ed elabora il feed $rss = fetch_rss($url); //Ciclo if che verifica se è stato inserito l'URL if ($rss) { //In questa parte vengono stampate le informazioni generali del feed echo "<h1><a href="". $rss -> channel['link'] ."">". $rss -> channel['title'] ."</a></h1>"; echo "<p>". $rss -> channel['description'] ."</p>"; //Inserisco un titolo echo "<h2>Elenco guide (solo titolo e data):</h2>"; //Inizio il listato echo "<ul>"; //Scompongo e stampo l'array del feed foreach ($rss -> items as $feed) { echo "<li>". "<a href="". $feed['link'] ."">". $feed['title'] ."</a><br />". "<i>". $feed['pubdate'] ."</i>". "</li>";} //Concludo il listato echo "</ul>"; } ?>
Come potete vedere mi è bastato modificare l'array $feed[], inserendo come nome dell'indice il nome del sottoelemento dell'items voluto. Nel prosieguo dell'articolo vedremo come gestire gli errori, il caching e i problemi più comuni di visualizzazione.
Nella prima parte dell'articolo abbiamo introdotto le funzioni base della libreria MagpieRSS. In questa seconda parte analizziamo opzioni leggermente più avanzate.
Gestiamo gli errori
Magpie contiene, al suo interno, una funzione utile per tutti gli sviluppatori la quale permette di avere il pieno controllo degli errori. Può capitare che, per qualsiasi motivo, uno dei nostri script non restituisca niente come risultato. Lasciandoci a bocca aperta, senza una spiegazione su cosa abbiamo sbagliato oppure con un semplice messaggio di errore non molto chiaro a tutti. Qui ci viene in aiuto la funzione: magpie_error().
Ecco come farla funzionare:
if ($rss)
{
...CODICE…
}
else
{
echo '<h2>Si è verificato un errore:</h2><p>'.magpie_error().'</p>';
}
Non vi spaventate lo so che mostrato così può non essere troppo chiaro, inseriamolo nel primo esempio che abbiamo fatto, così da renderlo più chiaro:
<? //Includiamo Magpie nel nostro script require_once('rss_fetch.inc'); //Impostiamo l'url riferito al feed da analizzare $url = 'http://rss.html.it/guide.xml'; //Richiamo della funzione di Magpie che analizza ed elabora il feed $rss = fetch_rss($url); //Ciclo if che verifica se è stato inserito il feed senza errori // Se viene rilevato un errore vado al punto *1 if ($rss) { //In questa parte vengono stampate le informazioni generali del feed echo "<h1><a href="". $rss -> channel['link'] ."">". $rss -> channel['title'] ."</a></h1>"; echo "<p>". $rss -> channel['description'] ."</p>"; //Inserisco un titolo echo "<h2>Elenco guide:</h2>"; //Inizio il listato echo "<ul>"; //Scompongo e stampo l'array del feed foreach ($rss -> items as $feed) { echo "<li>". "<a href="". $feed['link'] ."">". $feed['title'] ."</a><br />". "<small>". $feed['description'] ."</small>". "</li>"; } //Concludo il listato echo "</ul>"; } //*1---- // Stampo nella pagina l'errore che mi ha bloccato lo script // richiamando la funzione magpie_error() else { echo '<h2>Si è verificato un errore:</h2><p>'.magpie_error().'</p>'; } ?>
Quindi se al controllo del feed tramite la funzione fetch_rss($url) vengono trovati degli errori il ciclo IF ci fa uscire e verrà visualizzato l'errore.
Per fare un esempio provate a modificare l'URL del feed nelle prime righe: invece di chiamarlo "guide.xml" chiamatelo "guidexx.xml". Ecco cosa vi verrà mostrato una volta che eseguite lo script con l'URL appositamente sbagliato:
Come potete vedere il controllo ha funzionato alla perfezione: non è stato eseguito il codice ma ci è stato mostrato l'errore verificatosi, cioè l'URL non è stato trovato e Magpie non è riuscito a leggerlo.
Se però notate meglio le prime righe della pagina visualizzata nell'immagine vediamo che è riportato anche l'errore restituito da PHP. Ciò potrebbe bloccare i nostri script o causare confusione nel codice. Per ovviare a questo problema dobbiamo inserire una funzione di PHP che ci permette di eliminarlo, eccola:
//Impostiamo il report degli errori
error_reporting(E_ERROR);
Bisogna inserirlo come prime righe dello script, prima di tutto il resto. Questo ci permette di eliminare il warning di PHP e lasciare che sia la funzione di Magpie a segnalarci l'errore. Infine, dal momento che tale funzione apporta una modifica alle configurazioni di PHP, alla fine dello script dobbiamo inserirne un'altra che riporta tutto alla normalità:
// Ripristiniamo il valore per il report degli errori
@ini_restore('error_reporting');
Il caching di Magpie
Magpie dispone di una funzione molto interessante: il caching. In termini informatici la cache è una memoria temporanea in cui vengono memorizzati dei dati che possono essere poi recuperati e utilizzati in modo veloce anziché ricaricati ogni volta.
Nel nostro caso avviene la stessa cosa, infatti una volta che Magpie ha letto con successo un feed quest'ultimo viene salvato una cartella di cache per permettere una rilettura più veloce e per consumare meno banda. Provate ad immaginare quante risorse sarebbero sprecate se il vostro script venisse aperto più di 200 volte in un'ora. E tutte le 200 volte si collegasse al sito dove è memorizzato il feed. Ci sarebbero cioè 200 connessioni ad una pagina esterna in meno di un'ora.
Qui ci viene in aiuto la cache, Magpie legge il feed la prima volta e lo salva nella directory cache così che le altre 199 volte in cui sarà caricato non si deve più collegare al sito esterno consumando banda preziosa. Ovviamente Magpie ci permette di decidere se attivare o no la cache e di impostare anche il tempo di aggiornamento di quest'ultima. Vediamo come.
Di default Magpie ha attivo il sistema di caching e la cartella apposita (chiamata "cache") viene creata nella directory in cui lo script viene eseguito (che deve avere naturalmente gli appositi permessi di lettura e scrittura). Il tempo predefinito per la durata della cache è di 30 minuti, vedremo adesso come modificare tutti questi parametri nel nostro script.
Dato che il caching è attivo di default non ci sarà nessuna operazione da fare, a meno che non ci interessi modificare uno dei parametri della cache che sono: nome e posizione della "cache directory", età cache e sua attivazione.
Ecco come apporre le modifiche:
Attivazione della cache
define('MAGPIE_CACHE_ON', 1);
//Valori: 1 = Attiva; 0 = Non attiva
Directory della cache
define('MAGPIE_CACHE_DIR', '/indirizzo/nome_cartella');
//Valore: inserire al posto di '/indirizzo/nome_cartella'
//il percorso e il nome della cartella in cui volete
//che la cache sia memorizzata
Periodo di validità della cache
define('MAGPIE_CACHE_AGE', 3600);
//Valore: 3600 sono i secondi equivalenti a 1 ora
//(60 secondi in un minuto X 60 minuti = 3600 secondi).
//Il dato deve essere espresso sempre in secondi
Per rendere effettiva la modifica dobbiamo inserire queste costanti all'inizio del nostro script. Non siamo obbligati ad inserirle tutte e tre insieme, includiamo semplicemente quella a cui siamo interessati.
Ecco un esempio:
<? //Modifico la cartella dove è salvata la cache define('MAGPIE_CACHE_DIR', './chc'); //Imposto il report degli errori error_reporting(E_ERROR); //Includiamo Magpie nel nostro script require_once('rss_fetch.inc'); //Impostiamo l'url riferito al feed da analizzare $url = 'http://rss.html.it/guide.xml'; //Richiamo della funzione di Magpie che analizza ed elabora il feed $rss = fetch_rss($url); //Ciclo if che verifica se è stato inserito il feed senza errori // Se viene rilevato un errore vado al punto *1 if ($rss) { //In questa parte vengono stampate le informazioni generali del feed echo "<h1><a href="". $rss -> channel['link'] ."">". $rss -> channel['title'] ."</a></h1>"; echo "<p>". $rss -> channel['description'] ."</p>"; //Inserisco un titolo echo "<h2>Elenco guide:</h2>"; //Inizio il listato echo "<ul>"; //Scompongo e stampo l'array del feed foreach ($rss -> items as $feed) { echo "<li>". "<a href="". $feed['link'] ."">". $feed['title'] ."</a><br />". "<small>". $feed['description'] ."</small>". "</li>"; } //Concludo il listato echo "</ul>"; } //*1---- // Stampo nella pagina l'errore che mi ha bloccato lo script // richiamando la funzione magpie_error() else { echo '<h2>Si è verificato un errore:</h2><p>'.magpie_error().'</p>'; } // Ripristiniamo il valore per il report degli errori @ini_restore('error_reporting'); ?>
Magpie ci restituirà un errore nel caso ci fossimo dimenticati di creare la cartella /chc oppure di assegnare ad essa i permessi di scrittura. Ricordatevi dunque di aver creato e dato i permessi di scrittura giusti!
Limitare il numero di item
Ora mai siamo alla fine di questo articolo su come utilizzare MagpieRSS. L'ultimo paragrafo lo dedichiamo ai problemi più comuni che si incontrano utilizzando questa libreria.
Se, ad esempio, il feed RSS di HTML.it contenesse più voci di quante ne volessimo inserire all'interno della nostra pagina o all'interno dei nostri box ci basterebbe utilizzare un'apposita funzione per gli array di PHP chiamata array_slice() (http://it2.php.net/array_slice) e ridurre il loro numero a 5.
Per usarla inseriamo al posto di:
//Richiamo della funzione di Magpie che analizza ed elabora il feed
$rss = fetch_rss($url);
Il seguente codice:
//Numero di voci da visualizzare $num_items = 5; //Richiamo della funzione di Magpie che analizza ed elabora il feed $rss = fetch_rss($url); //Estraggo dall'array solo il numero di voci richieste $items = array_slice($rss->items, 0, $num_items);
poi modifichiamo:
//Scompongo e stampo l'array del feed
foreach ($rss -> items as $feed) {
con:
//Scompongo e stampo l'array del feed
foreach ($items as $feed) {
Eseguiamo lo script e ci saranno visualizzate solamente 5 voci.
Limitare la lunghezza del testo
Altro problema: se la descrizione fosse troppo lunga? Come possiamo evitare che rovini la nostra grafica?
Semplice, attraverso le seguenti modifiche possiamo mostrare solamente un certo numero di caratteri dopo i quali mostreremo dei punti per indicare all'utente che continua.
Ci basta inserire la funzione substr() (http://it2.php.net/manual/it/function.substr.php) che restituisce della stringa solamente un numero determinato di caratteri che noi impostiamo.
Nel nostro esempio sostituiremo:
//Scompongo e stampo l'array del feed
foreach ($rss -> items as $feed) {
echo "<li>".
"<a href="". $feed['link'] ."">". $feed['title'] ."</a><br />".
"<small>". $feed['description'] ."</small>".
"</li>";
}
con:
//Scompongo e stampo l'array del feed foreach ($rss -> items as $feed) { echo "<li>". "<a href="". $feed['link'] ."">". $feed['title'] ."</a><br />". "<small>"; $descr = $feed['description']; //Impostiamo il numero massimo di caratteri che vogliamo mostrare $num_caratteri = 30; //Verifico che la descrizione sia presente if($descr){ //Controllo che il numero di caratteri sia maggiore a quello che vogliamo if (strlen($descr) >= $num_caratteri) { //Mostriamo solo i caratteri richiesti e poi i 3 puntini $descr = substr($descr,0,$num_caratteri-1)."..."; } echo $descr; } echo "</small>". "</li>"; }
Il listato, l'ultimo finalmente, si spiega da sé.
