pHp scripts

Lecteur universel de flux RSS

fil_LE est un ensemble de scripts php (avec une classe principale) permettant de lire des flux rss (fils xml, fils de syndication de contenu).

Pour la lecture et l’affichage sur une page web, la classe rss_read lit les fils aux formats rss/rdf 0.91 jusqu’à 2.0 inclus et les flux au format atom 0.3 ou 1.0. C’est donc une classe universelle (n’ayons pas peur des mots).

Nouveautés :
Pour la version 2.2, les données "enclosure" sont récupérées en natif.
Pour la mise au point il est posible de récupérer une indication sur le type d’erreur.

PHP 4 minimum est recommandé, les fonctions fopen et fsockopen doivent être autorisée par votre hébergeur ou la bibliothèque curl doit être active. Procédez au besoin à un phpinfo() pour vérification.

Zip - 18.1 ko
Télécharger Fil_LE

Documentation

Quel que soit le type de fil, les données contenues sont accessibles via des tableaux associatifs. Pour faciliter le traitement de différents types de flux, ces tableaux associatifs ont la même structure correspondant aux éléments minimum définissant un fil valide. (exemple "content" sera transformé en "description" dans tous les cas, de même "entry" en "item", "feed" en "channel", d’une manière générale pour les éléments "de base" les noms retenus sont ceux équivalent dans les flux au format 1.0). Mais tout élément supplémentaire sera lui aussi automatiquement collecté dans le tableau associatif sous le nom du tag correspondant. (voir plus bas pour plus d’explications). Il est donc possible de parser tout fichier de type rss (y compris les fichiers de podcast).

Depuis la version 2.1c ceci peut être "débrayé" si on choisi un mode d’analyse "brut", le mode par défaut étant le mode "agrégé" décrit ci-dessus. ce mode brut est particulièrement utile en phase de mise au point.

Remarque :
Tous les éléments du tableau associatif sont transmis en minuscules même si le tag correspondant dans le flux comporte des majuscules (le contenu de <webMaster> sera $array[’webmaster’] ou pour <pubDate> la donnée sera dans $array[’pubdate’]).

Exemples :
Plusieurs exemples d’utilisations sont donnés à titre non exhaustif, le code html produit pouvant sûrement être amélioré. Ils sont fournis en l’état à des fins de vulgarisation et d’aide.
- "exemple-1.php" indique une possibilité d’utilisation des fonctions de la classe read ainsi que quelques fonctions utiles dans la mise en forme des données.
- "exemple-2.php" utilise un cache pour ne pas avoir à relancer tout la requête vers le fil distant ainsi que son analyse à chaque demande.

Méthodes :

$rss = new rss_read() ;
Constructeur de la classe.

$rss -> to_replace_with($array_char_to_replace, $array_char_replace_with) ;
Cette fonction est implémentée de façon à pouvoir remplacer certains caractères présents dans le flux par d’autres caractères, les premiers pouvant provoquer des parasites dans l’affichage (exemple le guillemet de certains flux remplacé par un point d’interrogation dans les données retournées après analyse).
$array_char_to_replace = tableau de caractères à remplacer ex array(’’’,’•’)
$array_char_replace_with = tableau de caractères de remplacement ex : array("’",’-’).

IMPORTANT : cette fonction doit être invoquée avant toute autre et en particulier avant parsefile pour que le remplacement des caractères ait lieu avant l’analyse du flux.

$rss -> mode_brut() ;
Cette fonction permet d’activer le mode brut d’analyse des flux. Les données de même type ne sont alors pas agrégées come c’est le cas par défaut. (par exemple dc:date, issued, pubDate,... ne sont pas tous rapportés dans "pubdate" mais sont conservés tel quels). Pour activer le mode d’analyse brut il suffit d’appeler $rss -> mode_brut() avant parsefile().

$bool = $rss -> parsefile($filename, [$maxitem]) ;
Parse un fichier RSS $filename en limitant le nombre d’items à $maxitem.
Si $maxitem est omis, tous les items seront retournés.
Renvoi true si le fichier a été parsé et false sinon.
Cette méthode doit être appelée au préalable à toute récupération de données.
Le contenu est alors accessible via des fonctions ci-dessous.

$bool = $rss -> curl_parsefile($filename, [$maxitem]) ;
Identique à la fonction parsefile(), mais la lecture du flux distant se fait au moyen de la bibliothèque CURL. Suivant le paramètrage de l’hébergement (fsockopen et fopen desactivés et CURL installé) vous pourrez alors utiliser cette fonction.
Les paramètres et le fonctionnement sont identiques à parsefile().

$erreur = $rss -> retour_erreur() ;
Cette fonction retourne une chaîne vide ou une description de l’erreur rencontrée (echec de fopen par exemple).
Elle s’utilise après parsefile par exemple :

$res = $rss -> parsefile($flux);
//ou $res = $rss -> curl_parsefile($flux);

if ($res === false) {
echo $rss -> retour_erreur();
exit;
}

$string = $rss -> get_encoding() ;
Retourne dans $tring l’encodage du fil (en général "iso-8859-1" ou "utf-8").
Dans le cas d’un encodage utf-8, on pourra utiliser la fonction php utf8_decode string utf8_decode (string data) pour convertir les données utf-8 en iso-8859-1. (voir le fichier exemple_lire.php pour plus de précision).
Par défaut si l’encodage n’est pas défini dans la l’entête xml <?xml version="1" encoding="xxxx"?>, la chaine retournée est vide.
La chaine retournée est toujours en minuscules quelle que soit sa case dans le fichier source.

$string = $rss -> get_last_modified( $filename, [$format]) ;
Cette fonction permet de connaître la date de la dernière modification du flux sur le site distant. (en-tête "Last-Modified" si présente dans les informations retournées par le serveur). Particulièrement utile lorsque le flux est mis en cache local afin d’éviter de refaire la lecture et l’analyse l’analyse de cleui-ci à chaque requète sur la page locale sensée l’afficher.
$filename = url du flux distant,
$format (optionnel). si $format est omis ou "true" (par défaut), la date sera retournée sous forme du nombre de secondes depuis l’origine unix, sinon la date sera transmise telle que détectée. (de la forme "Sat, 16 Jul 2005 20:15:01 GMT").
Si la date n’est pas présente dans les informations transmises la donnée retournée sera soit une chaîne vide (si $format est false) soit 0 (option par défaut).
La fonction retourne "false" en cas de problème de lecture du fichier distant.

$bool = $rss -> curl_get_last_modified( $filename, [$format]) ;
Identique à la fonction get_last_modified(), mais la lecture du flux distant se fait au moyen de la bibliothèque CURL. Suivant le paramètrage de l’hébergement (fsockopen et fopen desactivés et CURL installé) vous pourrez alors utiliser cette fonction.
Les paramètres et le fonctionnement sont identiques à gest_last_modified().

$bool = $rss -> exist_channel() ;
Renvoi true ou false si l’élément channel (feed) existe ou pas.
Un channel (feed) est valide si les éléments "title", "link" et "description" sont eux-même définis.

$array = $rss -> get_channel() ;
Renvoi dans $array les sous-éléments de l’élément channel.
$array est un tableau associatif structuré de la manière suivante :

array(
title, // sous-élément title
link, // sous-élément link
description, // sous-élément description (ou content ou summary)
[language, // sous-élément language si existe]
[copyright, // sous-élément copyright si existe]
[webmaster // sous-élément webMaster si existe]
[pubdate // sous-élément pubdate si existe]
[modified // sous-élément modified si existe]
[xxxxx // sous élément xxxxx si existe]
);

$bool = $rss -> exist_image() ;
Renvoi true ou false si l’élément image existe ou pas.
Une image est valide si les éléments "title", "link" et "url" sont eux-même définis.

$array = $rss -> get_image() ;
Renvoi dans $array les sous-éléments de l’élément image si il existe.
$array est un tableau associatif structuré de la manière suivante :

array(
title, // sous-élément title
url, // sous-élément url
link, // sous-élément link
[width, // sous-élément width si présent]
[height, // sous-élément height si présent]
[description // sous-élément description (ou content ou summary) si présent]
[xxxxx // sous-élément xxxxx si existe]
)

$bool = $rss -> exist_items() ;
Renvoi true ou false si au moins 1 élément item (entry) existe ou pas.

$value = $rss -> get_num_items() ;
Renvoi dans $value le nombre d’items du channel.

$array = $rss -> get_items() ;
Renvoi dans le tableau $array la liste des sous-éléments des items (ou entry) indexée à partir de 0.

$array est un tableau associatif à deux dimensions $array[n][’sous_element’]
n étant le rang de l’item (à partir de 0), sous_element étant :

title, // sous-élément title
link, // sous-élément link
description, // sous-élément description (ou dc:description ou summary ou content ou content:encoded suivant le type de fil)
[author, // sous-élément author (ou dc:creator) si existe]
[pubdate // sous-élément pubDate (ou date, dc:date, published, issued suivant le type de fil) si existe]
[modified // sous-élément modified (ou updated suivant le type de fil) si existe]
[category // sous-élément category (ou dc:subject suivant le fil) si existe]
[copyright // sous-élément copyright (ou dc:creator) si existe]
[enclosure // sous élémet enclosure si existe retourné sous forme d'un tableau avec les clés 'url', 'lenght' et 'type']
[xxxxx // sous-élément xxxxx si existe]

$bool = $rss -> exist_textinput() ;
Renvoi true ou false si l’élément textinput existe ou pas.
Tous les éléments title, description, name, link doivent être définis.

$array = $rss -> get_textinput() ;
Renvoi dans $array les sous-éléments de l’élément textinput si il existe.

$array est un tableau associatif :

array(
title, // sous-élément title
description, // sous-élément description (ou content ou summary)
name, // sous-élément name
link // sous-élément link
)

Versions :

- V2.2 décembre 2008
Les données "enclosure" sont récupérées en natif.
Pour la mise au point il est posible de récupérer une indication sur le type d’erreur.

- V2.1c octobre 2006
Corrections mineures et ajout d’un mode de lecture des fils (mode agrégé ou brut). Ajout de fichiers d’exemples dans l’archive.

- V2.1b class read septembre 2005
Différenciation entre les balises de date de publication (pubdate, dc:date, published..) et les balises de modification (modified, updated) et donc ajout d’un champ "modified" pour les items. Modification également du critère de reconnaissance des images (il suffit que l’url soit définie).

- V2.1a class read août 2005
la balise content:encoded est reconnue comme équivalente à l’élément description.

- V2.1 class read août 2005
Correction sur la fonction get_encoding (l’encodage n’était pas détecté pour certains fils).Ajout de la fonction get_last_modified() permettant d’obtenir la date de dernière modification du fil distant (sous réserve qu’elle soit retournée par le serveur). Fonction utile pour la mise en cache et la détection du moment où régénérer le cache local.
Le support de la bibliothèque CURL a également été ajouté avec les fonctions curl_parsefile() et curl_get_last_modified() équivalentes respectivement à parsefile() et get_last_modified().

- V2.0 classe rss_read juillet 2005
Les diverses classes font l’objet de packages séparés (pour des raisons de mises à jour).La classe rss_read V2.0 complétement revue et réecrite lit désormais tous les types de fils RSS 0.91 à 2 et atom 0.3 existants à ce jour.
La compatibilité ascendante à été conservée avec les versions précédentes hormis le fait que tous les noms de champs des tableaux associatifs retournés sont en minuscules.
Introduction d’une fonction permettant de déterminer le type d’encodage (get_encoding) et d’une seconde permettant des remplacements de caractères sur les données sources avant traitement (to_replace_with).

- V1.1 mai 2005
Modification de la classe rss_read. La lecture des éléments contenant des balises du type<![CDATA[ ...... .... ]]> est désormais possible.

- V1.0 avril 2005
La version 1.0 de fil_LE est en fait la suite de plusieurs révisions de la classe easyRSS produite par Philippe RODIER, modifiée par Alain SICHEL http://www.cyes.info et moi-même.

Les codes sont publiés ici en l’état en espérant que leur utilisation pourra être utile, et dans le respect de la licence GNU GPL, ceux-ci sont distribués de la même façon.