Documentation de PhpDig 1.4

Dernière mise à jour : 2003-02-21

Où trouver la dernière version de PhpDig ?

A l'url : http://phpdig.toiletoine.net

Fonctionnalités

Exploration HTTP

PhpDig suit les liens contenus dans les documents fournis par un serveur web, comme n'importe quel navigateur, afin de constituer sa liste de pages à indexer.

Les liens peuvent être contenus dans des AreaMap, résulter d'une redirection, ou être contenus dans des frames. Toute écriture, même approximative, des liens HREF est supportée. Les liens en javascript simple comme window.open() et window.location() sont détectés.

PhpDig ne suit pas les liens externes au site défini comme racine lors de la recherche. La profondeur de recherche dans le site peut être paramétrée.

Tout le contenu html servi par le site distant est parcouru, que ce soit du html simple, ou des pages créées dynamiquement. PhpDig se base sur le Mime-Type ou la présence d'une balise <HTML> au début du document.

Indexation Full Text

PhpDig indexe exhaustivement les mots contenus dans un document, exceptés ceux de moins de 3 lettres (par défaut), et ceux contenus dans une liste de mots considérés comme courants.

Les nombres seuls ne sont pas indexés. En revanche, les mots contenant des chiffres le sont. Les underscores dans les mots sont considérés faisant partie des mots, comme des noms de fonctions dans une documentation technique.

Le nombre d'occurences d'un mot dans une page est conservé dans l'index pour une meilleure pertinence des résultats. Les mots du titre des pages peuvent être pondérés.

Autres fonctions

PhpDig prend en compte un éventuel fichier robots.txt contenant les chemins des répertoires à exclure de l'indexation. Les balises meta robots sont aussi examinées.

PhpDig peut indexer des sites situés sur un port différent du port 80 par défaut.
On peut spécifier un nom et un mot de passe au robot pour indexer les sites protégés par mot de passe.
Attention ! Cette dernière fonction peut permettre à des personnes non autorisées de lire des informations protégées. Il est recommandé de créer une instance spécifique de PhpDig, protégée par les mêmes droits d'accès que le site restreint, ainsi que de créer un compte pour le robot lui-même.

Si le serveur renvoie un header Last-Modified, la valeur est mémorisée afin de ne pas effectuer de réindexation inutile.
La balise <META> revisit-after est également prise en compte pour la mise à jour de l'index.

Si le moteur est configuré pour le faire, les résultats affichent un extrait des pages trouvées, contenant les termes de recherche surlignés ou mis en gras.

Modèles de présentation

Un système simple de modèles permet de personnaliser facilement la page de recherche et de résultats. Il suffit d'insérer quelques balises spécifiques dans une page statique servant de modèle.

Limitations

PhpDig ne gère pas la recherche par expression exacte. Cela impliquerait un index au moins de la taille des documents indexés (ce qui n'est pas le but), sans compter le ralentissement de la recherche.

Les instances de Php qui réalisent l'indexation ne peuvent être configurés en safe_mode, sans quoi la limite de temps des scripts empêcherait le moteur de fonctionner.
Cette limite est toutefois contournable de deux manières : Soit en utilisant la possibilité d'indexation distante (par les connexions TCP mysql et FTP), soit en lançant l'indexation en ligne de commande sur le serveur, éventuellement par une tâche cron.

L'indexation est relativement lente. En revanche, la recherche, même sur un contenu assez étendu, reste suffisament rapide pour ne pas gêner l'utilisateur.

Installation

Pré - Requis

PhpDig nécessite un serveur web (Apache a ma préférence) doté de Php, et d'un serveur de bases de données MySql.

Les configurations suivantes ont été testées :
PHP 4.0.3pl1 cgi, Apache 1.3.14, MySql 3.23.28, Windows 2000 ;
PHP 4.0.5rc1 module, Apache 1.3.20, MySql 3.23.28, Windows 2000 ;
PHP 4.0.5 module, Apache 1.3.20, MySql 3.23.39, Linux noyau 2.4.
Php/4.1.1, Apache/1.3.20 (Win32), Windows 2000 ;
Php/4.1.2, Apache/1.3.23 (Unix) mod_ssl/2.8.7, Linux noyau 2.4.3 ;
Php/4.3.0, Apache/2.0.44 (Unix) OpenSSL/0.9.6g, Linux noyau 2.4.18.

Installation des scripts

Il suffit de déplier le fichier d'archive dans un répertoire de votre choix. (qui sera désigné ultérieurement par [PHPDIG_DIR] Il n'est pas nécessaire de créer un VirtualHost Apache pour le moteur.
Vérifiez par la même occasion, si vous êtes sous un système Unix, que L'utilisateur sous lequel est lancé le serveur Apache ait le droit d'écrire dans les répertoires :

[PHPDIG_DIR]/text_content
[PHPDIG_DIR]/include
[PHPDIG_DIR]/admin/temp

Installation de la base MySql

Deux méthodes sont possibles pour installer la base.

- Script php d'installation :
Dans votre navigateur, appelez le script

[PHPDIG_DIR]/include/install.php

Et suivez les instructions.
Le script utilise les informations pour renseigner les champs du fichier "[PHPDIG_DIR]/include/_connect.php" et pour en faire une copie sous le nom "[PHPDIG_DIR]/include/connect.php".

- Installation manuelle :
Il vous faut créer la base mysql (il n'est pas obligatoire de la nommer "phpdig") :

#mysql mysql
mysql> CREATE DATABASE phpdig;
mysql> quit

#mysql phpdig < [PHPDIG_DIR]/sql/init_db.sql

Vérifiez l'existence de toutes les tables :

#mysql phpdig
mysql> SHOW TABLES;

La base de donnée doit vous répondre :

+------------------+
| Tables_in_phpdig |
+------------------+
| engine           |
| excludes         |
| keywords         |
| sites            |
| spider           |
| tempspider       |
+------------------+
6 rows in set (0.00 sec)

mysql>

Une fois la base créée, copiez le fichier "[PHPDIG_DIR]/include/_connect.php" vers le fichier "[PHPDIG_DIR]/include/connect.php" et éditez ce dernier.
Remplacez les valeurs "<host>", "<user>", "<pass>", et "<database>" respectivement par l'URL de votre serveur MySql, le nom d'utilisateur, son mot de passe, et le nom que vous avez donné à la base de données.
Sur une installation locale, généralement les valeurs "localhost", "root", et "" sont suffisantes pour la connexion.

Vous pouvez vérifier que l'installation s'est bien déroulée en ouvrant la page principale [PHPDIG_DIR]/index.php.
Le formulaire de recherche doit s'afficher.

Configuration

Dès l'étape d'installation franchie, le moteur est opérationnel. L'étape de configuration est optionnelle et dépend de vos besoins. N'oubliez pas de modifier le login et le mot de passe d'administration si vous utilisez Php compilé en module d'apache ou en module statique.
Note : l'authentification ne fonctionne pas avec php utilisé en CGI. Dans ce cas, utilisez un fichier .htaccess pour protéger le répertoire [PHPDIG_DIR]/admin

Tous les paramètres de configuration se trouvent dans le fichier [PHPDIG_DIR]/include/config.php. Chaque paramètre fait l'objet d'un commentaire explicitant son utilisation.

Dans les parties suivantes consacrées à la configuration, les lignes de code se rapportent toutes au fichier config.php.
Les valeurs indiquées sont les valeurs définies par défaut.

Configuration de l'accès à l'administration

Modifiez les constantes suivantes. Si vous ne voulez pas que le mot de passe apparaîsse en clair quelque part, utilisez les fonctions d'authentification d'apache.

define('PHPDIG_ADM_AUTH','1');     //active ou non l'authentification
define('PHPDIG_ADM_USER','admin'); //Nom d'utilisateur (login)
define('PHPDIG_ADM_PASS','admin'); //Mot de passe pour l'accès

Configuration du robot et du moteur

Modifiez les variables et constantes suivantes.

define('SPIDER_MAX_LIMIT',12);          //Profondeur maximale sélectionnable pour l'indexation
define('SPIDER_DEFAULT_LIMIT',1);       //Valeur séléctionnée par défaut dans le formulaire
define('RESPIDER_LIMIT',4);             //Profondeur pour les mises à jour

define('LIMIT_DAYS',7);                 //Nombre de jours par défaut avant de revisiter une page
define('SMALL_WORDS_SIZE',2);           //Taille des mots à ne pas indexer
define('MAX_WORDS_SIZE',30);            //Taille maximale possible d'un mot

define('TITLE_WEIGHT',3);               //Poids des mots du titre par rapport aux autres mots
define('CHUNK_SIZE',2048);              //Taille du découpage pour le traitement des pages
                                        (ce paramètre ne nécessite pas d'être modifié)

define('SUMMARY_LENGTH',500);           //Longueur de texte pour le résumé des pages

define('TEXT_CONTENT_PATH','text_content/'); //répertoire des fichiers de contenu textuel
define('CONTENT_TEXT',1);                    //Active ou non le stockage des fichiers de contenu.

Configuration du modèle pour les résultats

Modifiez les variables et constantes suivantes.

$phpdig_language = "en";                       //langue de l'interface

$template = "$relative_script_path/templates/phpdig.html";
                                                 //chemin du fichier de modèle
define('HIGHLIGHT_BACKGROUND','yellow');         //Couleur de fond du surlignage
                                                 //Seulement en mode 'classic'
define('HIGHLIGHT_COLOR','#000000');             //Couleur du texte surligné
                                                 //Seulement en mode 'classic'
define('LINK_TARGET','_blank');                  //Target pour les liens de résultats
define('WEIGHT_IMGSRC','./tpl_img/weight.gif');  //chemin de l'image servant de baragraph
define('WEIGHT_HEIGHT','5');                     //hauteur du baragraph
define('WEIGHT_WIDTH','50');                     //largeur maximale du baragraph (pour 100%)
define('SEARCH_PAGE','index.php');             //Nom de la page de recherche

define('SEARCH_DEFAULT_LIMIT',10);      //resultats par page par défaut
define('SEARCH_DEFAULT_MODE','start');  //mode de recherche par défaut (start|exact|any)

Configuration FTP (si nécessaire)

A quoi diable peut-donc servir une connexion ftp dans PhpDig si il n'indexe pas les sites FTP ?

Beaucoup d'utilisateurs de installent PhpDig sur des serveurs mutualisés, et sur ces dernier, Php est toujours configuré en safe_mode. PhpDig ne peut effectuer d'indexation en safe_mode, et dans le cas des hébergements mutualisés, l'accès aux tâches cron est bien entendue exclue.

La solution est d'avoir une instance Php sur une autre machine. Dans mon cas, c'est une machine Linux à mon domicile, branchée sur une connexion à haut débit qui effectue ce travail.
Votre hébergement doit toutefois vous autoriser à vous connecter en TCP/IP à votre serveur de bases de données MySql.

Et le FTP dans tout ça ? Il sert à envoyer au serveur les fichiers de contenu textuel qui permettent d'afficher des extraits pertinents des documents trouvés dans les pages de résultat.
Si vous désactivez la fonction FTP lors d'une indexation distante, les résultats afficheront l'ancienne version de l'extrait ou les premiers mots du documents stockés dans la base MySql, selon que le fichier de contenu existe ou non sur le serveur.

Les paramètres concernés sont les suivants.

define('FTP_ENABLE',0);              //Activation ou non de la connexion FTP
define('FTP_HOST','<ftp host dir>'); //nom du serveur FTP
define('FTP_PORT',21);               //port ftp
define('FTP_PASV',1);                //utiliser le mode passif (conseillé)
define('FTP_PATH','<phpdig root dir>'); //chemin du répertoire de phpdig sur le serveur ftp
define('FTP_TEXT_PATH','text_content'); //répertoire des fichiers de contenu (default)
define('FTP_USER','<ftp username>');  //utilisateur du compte FTP
define('FTP_PASS','<ftp password>');  //mot de passe pour le compte FTP

Mise à jour

Mise à jour de la base de données

Le script sql [PHPDIG_DIR]/sql/update_db_to[version].sql contient les instructions SQL nécessaires pour mettre à jour votre installation existante, version par version.

Mise à jour des scripts

Remplacez les anciens scripts par les nouveaux, en ayant préalablement effectué une sauvegarde de votre configuration.

Indexation manuelle

Indexer un nouveau site

A partir de l'interface d'administration [PHPDIG_DIR]/admin/index.php, un champ de formulaire vous permet de renseigner un site à indexer. Vous pouvez également indiquer un chemin et/ou un fichier à partir duquel le robot va commencer son indexation.

Spécifiez une profondeur de recherche (combien de niveaux de liens va suivre le robot avant d'arrêter son indexation, et cliquez sur le bouton [dig this!].

Une page s'ouvre montrant le processus de recherche de liens et d'indexation. Une page correctement indexée est marquée d'un coche vert. Les '+' indiquent les nouveaux liens trouvés à partir de cette page.
L'indication "doublon avec une page existante" indique que malgré une URL différente, la page que PhpDig vient de trouver est identique à une autre page déjà indexée.
A la fin de l'indexation, une liste récapitule tous les liens trouvés par PhpDig.

Il est également possible de lancer une indexation en ligne de commande :

#php -f [PHPDIG_DIR]/admin/spider.php http://mondomaine.com

Mettre à jour un site

Dans l'interface d'administration, une liste des sites déjà indexés permet de les mettre à jour : Sélectionnez l'un des sites et cliquez sur le bouton [update form].
Une interface à deux volets s'affiche. A gauche se trouve une liste des branches du site indexé, à droite s'affiche la liste des fichiers d'une branche si on clique sur la flèche bleue située à droite de chacune des branches.

Pour les deux volets, la croix rouge supprime la branche ou le fichier sélectionné, le coche vert force la réindexation de la branche ou de la page ainsi que la recherche de nouveaux liens sur une profondeur définie par le paramètre $respider_limit.

Maintenance du moteur

Trois liens situés en bas de l'interface d'administration permettent de nettoyer la base de donnée des enregistrements inutiles ou corrompus.

Le lien Nettoyer l'index supprime les entrées d'index qui sont ne sont plus liées à aucun mot-clef.

Le lien Nettoyer les mots-clefs supprime les entrées de mots-clefs qui ne sont plus liées à aucune entrée d'index. Ce lien permet de minimiser la taille de la table des mots-clefs après de nombreuses indexations et mises à jour.

Le lien Nettoyer les mots courants supprime les entrées d'index et de mots-clefs devenues inutiles suite au rajout de mots dans le fichier des mots courants [PHPDIG_DIR]/includes/common_words.txt.

Mise à jour automatique

Le script [PHPDIG_DIR]/admin/spider.php peut être programmé en tâche cron afin de procéder automatiquement à la mise à jour du moteur. La périodicité conseillée est de 7 jours, quitte à forcer la réindexation par l'interface des pages devant figurer dans le moteur immédiatement.
Ces dernières peuvent également comporter un Metatag "revisit-after" spécifique.

Le script se lance de deux manières :

#php -f [PHPDIG_DIR]/admin/spider.php all

Lance une réindexation normale.

La syntaxe suivante :

#php -f [PHPDIG_DIR]/admin/spider.php http://mondomaine.net

N'indexera ou ne mettra à jour que le site mondomaine.net.
Cette option peut être utile si on désire spécifier une fréquence de mise à jour différente par site ou pour un site en particulier.

Comme pour n'importe quelle commande, la sortie peut être redirigée vers un fichier (pour tenir des logs par exemple.)

#php -f [PHPDIG_DIR]/admin/spider.php all >> /var/log/phpdig.log

Liste des balises des templates

Les templates consistent en fichiers html dans lesquels quelques balises de style xml permettent de placer le contenu dynamique.
Les modèles fournis permettent de donner une petite idée de la façon dont les pages de résultat peuvent être personnalisées.

Deux classes CSS sont utilisées par PhpDig :
.phpdigHighlight : Classe de niveau <SPAN/> utilisée pour le surlignage des termes de recherche.
a.phpdig : Classe de balise <A/> pour les liens de résultats et de navigation.

Les balises sont toutes du style <phpdig:parametre/>.
A part la balise <phpdig:results></phpdig:results>, ce sont toutes des balises unitaires.

Balises en dehors de la table des résultats

phpdig:title_message   Titre de la page

phpdig:form_head       Début du formulaire
phpdig:form_title      Titre du formulaire
phpdig:form_field      Champ texte du formulaire
phpdig:form_button     Bouton de soumission du formulaire
phpdig:form_select     Liste déroulante du nombre de résultats par page
phpdig:form_radio      Boutons radio sur l'interprétation des mots
phpdig:form_foot       Fin du formulaire

phpdig:result_message         Message sur le nombre de résulats
phpdig:ignore_message         Message sur les mots trop courts
phpdig:ignore_commess         Message sur les mots trop courants

phpdig:nav_bar         Barre de navigation dans les pages de résultats
phpdig:pages_bar       Barre de navigation sans les liens suivants/précédents
phpdig:previous_link src=[img src]  Lien vers l'icône "précédents"
phpdig:next_link src=[img src]  Lien vers l'icône "suivants"

Balises pour la table des résultats

phpdig:results       Encadre les lignes de résultat

phpdig:img_tag       Baragraph de pertinence
phpdig:weight        Pertinence de la page (sur 100)
phpdig:page_link     Titre du résultat et lien vers la page
phpdig:limit_links   Liens limitant la recherche à un site/un chemin
phpdig:text          Texte du résultat
phpdig:n             Classement du résultat
phpdig:complete_path URL complète du document
phpdig:update_date   Dernière mise à jour du document
phpdig:filesize      Taille du document (Kilo Octets)

Précisions sur la recherche

Même si le formulaire de recherche parle de lui-même, il n'est pas inutile de rappeler que :

- Un opérateur AND est appliqué inconditionnellement à tous les termes de recherche ;
- Un mot précédé d'un '-' (signe moins) est exclu de la recherche. Aucune page contenant ce mot ne sera retournée en résultat ;
- La recherche est insensible à la casse et aux accents. En revanche, le surlignage des résultats est sensible aux accents.

Obtenir de l'aide sur PhpDig

Un mini-forum consacré à PhpDig est disponible à l'adresse http://phpdig.toiletoine.net/messageboard/
Vous pouvez y poser toutes les questions relatives au programme.

Vous pouvez demander de l'aide directement à l'auteur en écrivant à phpdig@toiletoine.net

Fichier créé par le parser XSLT Php 4.3.0 - Sablotron 0.96