Nerull.net

English version below

Présentations de la classe Pavatar

Les pavatars

Pour ceux qui ne connaissent pas encore le principe des pavatars, voici une rapide introduction. Les pavatars (personnal avatar) sont des avatars liés à un site web, ils permettent ainsi de donner une identité visuelle à un webmaster. Contrairement à des systèmes tels que Gravatar, ceux-ci ne sont pas centralisés. Cela permet de ne pas dépendre d’un site externe, qui, lorsqu’il tombe en panne, empêche l’affichage de tous les pavatars.
Le but de cette classe PHP est de permettre la gestion des pavatars, tout d’abord en les récupérant sur les sites concernés.

Recherche, récupération et mise en cache

Lorsque l’on doit afficher un pavatar pour la première fois, il faut aller le récupérer sur le site dont il dépend. Afin de découvrir l’adresse du pavatar, il existe trois solutions:

• vérifier dans les headers s’il existe une entrée “x-pavatar”: cette opération est réalisée par la fonction “findFromHeaders”, prenant en paramètre l’URI du site dont nous cherchons le pavatar. Merci à Jeena pour m’avoir montré une solution gérée par PHP4 pour simuler la fonction get-headers;
• vérifier dans le code source de la page, plus précisément dans la partie header un bout de code ressemblant à “<link rel=”pavatar” src=”…”>”. Ceci est effectuée par la fonction findFromSource, prenant aussi en paramètre l’URI du site à fouiller;
• La dernière solution est de vérifier l’existence d’un fichier nommé “pavatar.png” à la racine du site. La fonction “findInDirectory” prend cette solution en charge

Toutes ces opérations sont effectuées à la suite grâce à la fonction “find”, prenant l’URI du site en paramètre. Evidemment, si une fonction renvoie un résultat, les fonctions suivantes ne sont pas effectuées.
Une fois l’URI trouvée, la fonction “save” se charge de faire une copie sur notre serveur du pavatar. Sur le serveur, le nom du fichier est déterminé par un encodage en base 64 de l’URI du site de provenance, évitant ainsi tout doublon. Le code de la fonction de sauvegarde est directement inspiré du code du module Favatar

Afin d’automatiser tout cela, la fonction “display” s’occupe de tout. Tout d’abord elle vérifie s’il existe une version du Pavatar en cache, si ce n’est pas le cas, on utilise les fonctions de recherche puis on met en cache.
Une fois tout cela fait, on envoie les bons headers (pour que le navigateur considère la page comme une image) et on affiche le contenu de l’image.

Mais cela ne suffit pas, en effet, il faut encore pouvoir mettre les pavatars à jour, et éventuellement les modérer (on est jamais trop méfiant :p ). Tout ceci sera pris en compte par la prochaine version de la classe, c’est déjà prévu, vous trouverez les signatures des méthodes, mais pas encore le contenu, désolé

Nous allons maintenant voir la mise en place de ce système sur votre site.

Installation du biniou

La première chose à faire est de récupérer la classe, sans ça risque d’être très difficile. Vous la trouverez à cette adresse. On dezippe et nous y voilà.

Avant d’uploader la classe sur votre serveur, il faut régler quelques petits paramètres, en modifiant les lignes 77 à 79 avec votre éditeur favori:

• var $storageDir = “pavatars/”; si vous voulez stocker vos pavatars en cache à un endroit bien précis, remplacez pavatars dans cette ligne par le chemin de votre choix;
• var $defaultPavatar = “default.png”; default.png correspond au nom du pavatar par défaut, utilisé pour les visiteurs n’ayant pas de pavatars. Si votre pavatar par défaut à un autre nom, mettez ce nom à la place de default.png;
• var $moderatedPavatar = “default.png”; même principe qu’au dessus, mais pour les pavatars moderés.

Une fois ces réglages fait (mais ceux par défaut fonctionnent très bien, si vous ne vous sentez pas à l’aide, ne touchez à rien :p ), il faut créer une page php qui va appeler notre classe. Dans le cadre du plug-in pour dotClear, voilà le code que j’ai écrit:

 <?php
 /* File: pavatar.php
 Author: Vincent Pretre
 Licence: GPL
 Description: This plug-in displays pavatars in comments */
 ?>
 <?php require 'pavatar.class.php';
 // Si l'url est fournie if(isset($_GET['url']) && $_GET['url'] != ''){
 	$p = new pavatar;
 	$p->display($_GET['url']);
 } else {
 	// On affiche l'image par défaut
 	header("Content-Type: image/png");
 	readfile('pavatars/default.png'); }
?>

Si vous ne connaissez pas grand chose à PHP, copiez ce code et enregistrez le dans un fichier nommé “pavatar.php”, situé à coté du fichier “pavatar.class.php”. Si vous avez modifié la configuration dans la classe, pensez aussi à mettre à jour la ligne “readfile(…);”, selon les paramètres donnés dans votre classe (oui y’a de la redondance d’information, il faut que je remédie à ça :p ).
Pensez aussi a créer un dossier servant à stocker les pavatars en cache (par défaut, un dossier “pavatars” à coté des fichiers “pavatar.php” et “pavatar.class.php”.

Il faut maintenant mettre tout ça sur votre site web, à l’endroit de votre choix, pourvu qu’il soit lisible de l’extérieur, sinon ça ne marchera pas :p. Par exemple chez moi, ça donne ça (ne vous inquiétez pas pour les fichiers desc.xml, pour vous il ne faut que les fichiers créé précédemment):

Maintenant que tout est en place, allez voir sur votre site, et admirez, rien ne se passe. C’est normal, faudrait penser à l’utiliser ce code non ? Pour ça rien de plus simple, tout d’abord identifiez la page dans laquelle vous voulez afficher les pavatars (par exemple dans les commentaires) et téléchargez là.
Identifiez le bout de code utile (la boucle affichant les commentaires par exemple), et inserez du code ressemblant à ça:

 <div class="pavatar-cont">
 	<img src="chemin/pavatar.php?url=<php echo '$siteDuPosteur' >" alt="Pavatar de <php echo '$nomDuPosteur' >" class="pavatar"/>
 </div>
 

en remplaçant évidemment “chemin” par le chemin d’accès au fichier “pavatar.php”, et $siteDuPosteur et $nomDuPosteur par ce que vous avez sous la main.
Maintenant remettez la page la où vous l’avez trouvé, et si vous n’avez pas fait de boulette, les pavatars de vos visiteurs apparaissent, magique non ?

Si des points restent obscures, n’hésitez pas à me le signaler, j’ai un peu de mal à visualiser le public intéressé par ce type de code, donc difficile de savoir si on insiste sur des banalités ou pas assez.

Introduction to the pavatar class

What are pavatar

For those who don’t yet know what are pavatar, here is a quick introduction. Pavatar (personnal avatar) is a system allowing to link an image to a website, giving a visual identity to webmaster. Contrary to a system like Gravatar, there is no centralization in pavatar. The advantage is that there are no dependencies to a website, and there can’t be global breakdown.
The goal of this php class is to allow managing of your visitor’s pavatar. The first thing is to find and put them in cache.

Discovering and caching

The first time we have to display a pavatar, we have to get it on the website. For discovering the pavatar’s address, there exists three solutions:

• look for an entry “x-pavatar” in the headers sent by the server. This si done by the function “findFromHeaders”, which take in input the website URI. Thanks to Jeena, this works now with PHP4
• look in the source code of the website, seeking for “$lt;link rel=”pavatar” … src=”…” />”. This is done by the “findFromSource”, which also takes in input the website URI.
• the last solution is to look if there exists a file “pavatar.png” at the root directory of the site. This is done by the “findInDirectory” function.

All these function are called by the “find” function, wich tries each of these solutions in order to find the pavatar’s address.
Once the pavatar’s adress found, we get it and put in in cache on the server (as asked by the pavatar protocol). This is done by the “save” function. The name of the cached pavatar is obtained by encoding the website URI in base64. The code of the “save” function is directly inspired by the Favatar plug-in for dotClear

The discovery and caching functions are called by the “display” function. First, the function checks if there already exists a pavatar cached for the website given in parameter. If there is not yet a cached version, the discovery functions are caleed, and then the caching function. If no pavatar is found, the default pavatar is displayed.

In the next version of the class, we will be able to update pavatars and moderate them. The signature of the functions wich will take this in charge are already written, if you want to take a look at it.

We will now see how to set up this class on your website.

Setting up the biniou

(sorry, I don’t have any good translation for biniou, whatever, I wouldn’t know how to explain it, so don’t care :p )

The first thing to do is to get the class, you will find it at this address. Download and unzip it.

Before using it, you may have to change the settings (the default setings work well, so if you’re not familiar with php, forget this). With your favorite editor, open the file and go to the line 77, you will find three variables:

• var $storageDir = “pavatars/”; path where to store pavatars.
• var $defaultPavatar = “default.png”; name of the default pavatar.
• var $moderatedPavatar = “default.png”; same as before, but for moderated pavatars.

Now, we have to create a page that will call this class. This is what I have written for the dotClear plug-in, you can use it:

 <?php
 /* File: pavatar.php
 Author: Vincent Pretre
 Licence: GPL
 Description: This plug-in displays pavatars in comments */
 ?>
 <?php
 require 'pavatar.class.php';
 // Si l'url est fournie if(isset($_GET['url']) && $_GET['url'] != ''){
 	$p = new pavatar;
 	$p->display($_GET['url']);
 } else {
 	// On affiche l'image par défaut
 	header("Content-Type: image/png");
 	readfile('pavatars/default.png');
 }
 ?>
 

Save this code in a file called “pavatar.php”, in the same directory where you have your file “pavatar.class.php”. ou may adapt this solution to your architecture if you are familiar with PHP.

If you just took the code “as given”, you have to create a directory called “pavatars”, near your files “pavatar.class.php” and “pavatar.php”. The next action is to upload this on your website server. On my installation, it looks like this (don’t worry for extra files (descxml …), they are here for the dotClear plug-in. You may just have the “pavatars” directory, and the two php files given above:

Now that everything is set up, look at your website, and you will see that nothing has changed, that’s normal
The last action is to find the file where you want to display pavatars (for example, in the comments), download it and open it.
Identify the code section where you want to display pavatars (this depends of your site, so I can’t be more precise), and insert this code:

 <div class="pavatar-cont">
 	<img src="path/pavatar.php?url=<php echo '$visitorWebsite' >" alt="Pavatar de <php echo '$visitorName' >" class="pavatar"/>
 </div>
 

Of course, you have to change “path” in order to give the path of the “pavatar.php” file, $visitorWebsite and $visitorName by your php variables.
Now save the file, and put it back where you found it, and if you didn’t something wrong, everything should work well, and your visitor’s pavatars should be displayed

If something still seem not clear, don’t hesitate and tell it in the comments. It is hard for me to know what kind of public is interrested by this article, so I don’t know if I have to be very detailled or not.