La classe read permet depuis la version 2 de lire tous les types de fils (rss 0.91, 1.0, 2.0 et atom 0.3 et 1.0) et de connaître leur format d'encodage pour adapter le traitement des données à celui-ci.
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 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 a besoin à un phpinfo() pour vérification.
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']).
$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 rerourné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 strcuturé 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
)