documentation/manual/fr/module_specs/Zend_Search_Lucene-Extending.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- EN-Revision: 21829 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.search.lucene.extending">
   5     <title>Extensibilité</title>
   6
   7     <sect2 id="zend.search.lucene.extending.analysis">
   8         <title>Analyse de texte</title>
   9
  10         <para>
  11             La classe <classname>Zend_Search_Lucene_Analysis_Analyzer</classname> est utilisé par
  12             l'indexeur afin de transformer en segments les champs texte du document.
  13         </para>
  14
  15         <para>
  16             Les méthodes <methodname>Zend_Search_Lucene_Analysis_Analyzer::getDefault()</methodname>
  17             et <code>Zend_Search_Lucene_Analysis_Analyzer::setDefault()</code> sont utilisées pour
  18             récupérer et définir l'analyseur par défaut.
  19         </para>
  20
  21         <para>
  22             Vous pouvez assigner votre propre analyseur de texte ou choisir parmi un ensemble
  23             d'analyseurs prédéfinis&#160;:
  24             <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text</classname> et
  25             <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
  26             (par défaut). Tout deux interprètent les segments comme des séquences de lettres.
  27             <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
  28             convertit tous les segments en minuscule.
  29         </para>
  30
  31         <para>
  32             Pour changer d'analyseur&#160;:
  33         </para>
  34
  35         <programlisting language="php"><![CDATA[
  36 Zend_Search_Lucene_Analysis_Analyzer::setDefault(
  37     new Zend_Search_Lucene_Analysis_Analyzer_Common_Text());
  38 ...
  39 $index->addDocument($doc);
  40 ]]></programlisting>
  41
  42         <para>
  43             La classe <classname>Zend_Search_Lucene_Analysis_Analyzer_Common</classname> a été conçu
  44             pour être l'ancêtre de tous les analyseurs définis par l'utilisateur. L'utilisateur doit
  45             uniquement définir les méthodes <methodname>reset()</methodname> et
  46             <methodname>nextToken()</methodname>, qui prennent leur chaîne de caractères depuis la
  47             propriété $_input et retournent les segments un par un (une valeur
  48             <constant>NULL</constant> indique la fin du flux).
  49         </para>
  50
  51         <para>
  52             La méthode <methodname>nextToken()</methodname> doit appeler la méthode
  53             <methodname>normalize()</methodname> sur chacun des segments. Ce qui vous permet
  54             d'utiliser des filtres de segments avec votre analyseur.
  55         </para>
  56
  57         <para>
  58             Voici l'exemple d'analyseur personnalisé, qui accepte des mots contenant des chiffres
  59             comme terme&#160;:
  60             <example id="zend.search.lucene.extending.analysis.example-1">
  61                 <title>Analyseur de texte personnalisé</title>
  62                 <programlisting language="php"><![CDATA[
  63 /**
  64  * Voici un analyseur de texte qui traite les mots contenant des chiffres comme
  65  * un seul terme
  66  */
  67 class My_Analyzer extends Zend_Search_Lucene_Analysis_Analyzer_Common
  68 {
  69     private $_position;
  70     /**
  71      * Remet à Zéro le flux de segments
  72      */
  73     public function reset()
  74     {
  75         $this->_position = 0;
  76     }
  77     /**
  78      * API du flux de segmentation
  79      * Récupère le segment suivant
  80      * Retourne null à la fin du flux
  81      *
  82      * @return Zend_Search_Lucene_Analysis_Token|null
  83      */
  84     public function nextToken()
  85     {
  86         if ($this->_input === null) {
  87             return null;
  88         }
  89         while ($this->_position < strlen($this->_input)) {
  90             // Saute les espaces
  91             while ($this->_position < strlen($this->_input) &&
  92                    !ctype_alnum( $this->_input[$this->_position] )) {
  93                 $this->_position++;
  94             }
  95             $termStartPosition = $this->_position;
  96             // lit le segment
  97             while ($this->_position < strlen($this->_input) &&
  98                    ctype_alnum( $this->_input[$this->_position] )) {
  99                 $this->_position++;
 100             }
 101             // Segment vide, fin de flux.
 102             if ($this->_position == $termStartPosition) {
 103                 return null;
 104             }
 105             $token = new Zend_Search_Lucene_Analysis_Token(
 106                                       substr($this->_input,
 107                                              $termStartPosition,
 108                                              $this->_position -
 109                                              $termStartPosition),
 110                                       $termStartPosition,
 111                                       $this->_position);
 112             $token = $this->normalize($token);
 113             if ($token !== null) {
 114                 return $token;
 115             }
 116             // Continue si le segment est sauté
 117         }
 118         return null;
 119     }
 120 }
 121 Zend_Search_Lucene_Analysis_Analyzer::setDefault(
 122     new My_Analyzer());
 123 ]]></programlisting>
 124             </example>
 125         </para>
 126     </sect2>
 127
 128     <sect2 id="zend.search.lucene.extending.filters">
 129         <title>Filtrage des segments</title>
 130
 131         <para>
 132             L'analyseur <classname>Zend_Search_Lucene_Analysis_Analyzer_Common</classname> offre
 133             aussi un mécanisme de filtrage des segments.
 134         </para>
 135
 136         <para>
 137             La classe <classname>Zend_Search_Lucene_Analysis_TokenFilter</classname> fournit une
 138             interface abstraites pour ces filtres.
 139             Vos propres filtres devraient étendre cette classe directement ou indirectement.
 140         </para>
 141
 142         <para>
 143             Chaque filtre personnalisé doit implémenter la méthode
 144             <methodname>normalize()</methodname> qui devrait transformer le segment en entrée ou
 145             signaler que le segment courant doit être sauté.
 146         </para>
 147
 148         <para>
 149             Il y a trois filtres déjà défini dans le sous-paquet d'analyse&#160;:
 150             <itemizedlist>
 151                 <listitem>
 152                     <para>
 153                         <classname>Zend_Search_Lucene_Analysis_TokenFilter_LowerCase</classname>
 154                     </para>
 155                 </listitem>
 156                 <listitem>
 157                     <para>
 158                         <classname>Zend_Search_Lucene_Analysis_TokenFilter_ShortWords</classname>
 159                     </para>
 160                 </listitem>
 161                 <listitem>
 162                     <para>
 163                         <classname>Zend_Search_Lucene_Analysis_TokenFilter_StopWords</classname>
 164                     </para>
 165                 </listitem>
 166             </itemizedlist>
 167         </para>
 168
 169         <para>
 170             Le filtre <code>LowerCase</code> filtre est déjà utilisé par défaut par l'analyseur
 171             <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>.
 172         </para>
 173
 174         <para>
 175             Les filtres <code>ShortWords</code> et <code>StopWords</code> peuvent être utilisés avec
 176             des analyseurs prédéfinis ou personnalisés comme ceci&#160;:
 177             <programlisting language="php"><![CDATA[
 178 $stopWords = array('a', 'an', 'at', 'the', 'and', 'or', 'is', 'am');
 179 $stopWordsFilter =
 180     new Zend_Search_Lucene_Analysis_TokenFilter_StopWords($stopWords);
 181 $analyzer =
 182     new Zend_Search_Lucene_Analysis_Analyzer_Common_TextNum_CaseInsensitive();
 183 $analyzer->addFilter($stopWordsFilter);
 184 Zend_Search_Lucene_Analysis_Analyzer::setDefault($analyzer);
 185 ]]></programlisting>
 186             <programlisting language="php"><![CDATA[
 187 $shortWordsFilter = new Zend_Search_Lucene_Analysis_TokenFilter_ShortWords();
 188 $analyzer =
 189     new Zend_Search_Lucene_Analysis_Analyzer_Common_TextNum_CaseInsensitive();
 190 $analyzer->addFilter($shortWordsFilter);
 191 Zend_Search_Lucene_Analysis_Analyzer::setDefault($analyzer);
 192 ]]></programlisting>
 193         </para>
 194
 195         <para>
 196             Le constructeur <classname>Zend_Search_Lucene_Analysis_TokenFilter_StopWords</classname>
 197             prends un tableau de stop-words en entrée.
 198             Mais les stop-words peuvent aussi être chargé à partir d'un fichier&#160;:
 199             <programlisting language="php"><![CDATA[
 200 $stopWordsFilter = new Zend_Search_Lucene_Analysis_TokenFilter_StopWords();
 201 $stopWordsFilter->loadFromFile($my_stopwords_file);
 202 $analyzer =
 203    new Zend_Search_Lucene_Analysis_Analyzer_Common_TextNum_CaseInsensitive();
 204 $analyzer->addFilter($stopWordsFilter);
 205 Zend_Search_Lucene_Analysis_Analyzer::setDefault($analyzer);
 206 ]]></programlisting>
 207             Ce fichier doit être un simple fichier texte avec un mot par ligne. Le caractère '#'
 208             transforme la ligne en commentaire.
 209         </para>
 210
 211         <para>
 212             Le constructeur de la classe
 213             <classname>Zend_Search_Lucene_Analysis_TokenFilter_ShortWords</classname> a un argument
 214             optionnel.
 215             Il s'agit de la longueur maximum de mot, elle est définie par défaut à 2.
 216         </para>
 217     </sect2>
 218
 219     <sect2 id="zend.search.lucene.extending.scoring">
 220         <title>Algorithme de score</title>
 221
 222         <para>
 223             Le score d'un document <literal>d</literal> pour une requête <literal>q</literal>
 224             est défini comme suit&#160;:
 225         </para>
 226
 227         <para>
 228             <code>score(q,d) = sum( tf(t in d) * idf(t) * getBoost(t.field in d) *
 229             lengthNorm(t.field in d) ) * coord(q,d) * queryNorm(q)</code>
 230         </para>
 231
 232         <para>
 233             tf(t in d) - <methodname>Zend_Search_Lucene_Search_Similarity::tf($freq)</methodname> -
 234             un facteur de score basé sur la fréquence d'un terme ou d'une phrase dans un document.
 235         </para>
 236
 237         <para>
 238             idf(t) -
 239             <methodname>Zend_Search_Lucene_Search_Similarity::idf($input, $reader)</methodname> -
 240             un facteur de score pour un terme simple de l'index spécifié.
 241         </para>
 242
 243         <para>
 244             getBoost(t.field in d) - le facteur d'impulsion pour le champ du terme.
 245         </para>
 246
 247         <para>
 248             lengthNorm($term) - la valeur de normalisation pour un champ donné du nombre total de
 249             terme contenu dans un champ. Cette valeur est stockée dans l'index.
 250             Ces valeurs, ainsi que celle du champ d'impulsion, sont stocké dans un index et
 251             multipliées par le score de hits par code de recherche sur chaque champ.
 252         </para>
 253
 254         <para>
 255             La correspondance au sein de champs plus long est moins précise, ainsi l'implémentation
 256             de cette méthode retourne généralement de plus petites valeurs quand numTokens est
 257             important, et de plus grandes valeurs lorsque numTokens est petit.
 258         </para>
 259
 260         <para>
 261             coord(q,d) -
 262             <methodname>
 263                 Zend_Search_Lucene_Search_Similarity::coord($overlap, $maxOverlap)
 264             </methodname> - un facteur de score basé sur la fraction de tout les termes de la
 265             recherche que le document contient.
 266         </para>
 267
 268         <para>
 269             La présence d'une grande partie des termes de la requête indique une meilleure
 270             correspondance avec la requête, ainsi les implémentations de cette méthode retourne
 271             habituellement de plus grandes valeurs lorsque le ration entre ces paramètres est grand
 272             que lorsque le ratio entre elle est petit.
 273         </para>
 274
 275         <para>
 276             queryNorm(q) - la valeur de normalisation pour la requête en fonction de la somme des
 277             poids au carré de chaque terme de la requête.
 278             Cette valeur est ensuite multipliée par le poids de chacun des termes de la requête.
 279         </para>
 280
 281         <para>
 282             Ceci n'affecte pas le classement, mais tente plutôt de faire des scores à partir de
 283             différentes requêtes comparables entre elles.
 284         </para>
 285
 286         <para>
 287             Les algorithmes de score peuvent être personnalisés en définissant votre propre classe
 288             de similitude.
 289             Pour ce faire, étendez la classe
 290             <classname>Zend_Search_Lucene_Search_Similarity</classname> comme défini ci-dessous,
 291             puis appelez la méthode
 292             <classname>Zend_Search_Lucene_Search_Similarity::setDefault($similarity);</classname>
 293             afin de la définir par défaut.
 294         </para>
 295
 296         <programlisting language="php"><![CDATA[
 297 class MySimilarity extends Zend_Search_Lucene_Search_Similarity {
 298     public function lengthNorm($fieldName, $numTerms) {
 299         return 1.0/sqrt($numTerms);
 300     }
 301     public function queryNorm($sumOfSquaredWeights) {
 302         return 1.0/sqrt($sumOfSquaredWeights);
 303     }
 304     public function tf($freq) {
 305         return sqrt($freq);
 306     }
 307     /**
 308      * Ceci n'est pas encore utilisé. Cela évalue le nombre de correspondance
 309      * d'expressions vagues, basé sur une distance d'édition.
 310      */
 311     public function sloppyFreq($distance) {
 312         return 1.0;
 313     }
 314     public function idfFreq($docFreq, $numDocs) {
 315         return log($numDocs/(float)($docFreq+1)) + 1.0;
 316     }
 317     public function coord($overlap, $maxOverlap) {
 318         return $overlap/(float)$maxOverlap;
 319     }
 320 }
 321 $mySimilarity = new MySimilarity();
 322 Zend_Search_Lucene_Search_Similarity::setDefault($mySimilarity);
 323 ]]></programlisting>
 324     </sect2>
 325
 326     <sect2 id="zend.search.lucene.extending.storage">
 327         <title>Conteneur de stockage</title>
 328
 329         <para>
 330             La classe abstraite <classname>Zend_Search_Lucene_Storage_Directory</classname> définit
 331             la fonctionnalité de répertoire.
 332         </para>
 333
 334         <para>
 335             Le constructeur <classname>Zend_Search_Lucene</classname> utilise soit une chaîne soit
 336             un objet <classname>Zend_Search_Lucene_Storage_Directory</classname> en paramètre.
 337         </para>
 338
 339         <para>
 340             La classe <classname>Zend_Search_Lucene_Storage_Directory_Filesystem</classname>
 341             implémente la fonctionnalité de répertoire pour un système de fichier.
 342         </para>
 343
 344         <para>
 345             Si une chaîne est utilisé comme paramètre du constructeur
 346             <classname>Zend_Search_Lucene</classname>, le lecteur
 347             (<classname>Zend_Search_Lucene</classname> object) le considère comme un chemin dans le
 348             système de fichier et instancie l'objet
 349             <classname>Zend_Search_Lucene_Storage_Directory_Filesystem</classname>.
 350         </para>
 351
 352         <para>
 353             Vous pouvez définir votre propre implémentation de répertoire en étendant la classe
 354             <classname>Zend_Search_Lucene_Storage_Directory</classname>.
 355         </para>
 356
 357         <para>
 358             Les méthodes de<classname>Zend_Search_Lucene_Storage_Directory</classname>&#160;:
 359         </para>
 360
 361         <programlisting language="php"><![CDATA[
 362 abstract class Zend_Search_Lucene_Storage_Directory {
 363 /**
 364  * Ferme le stockage.
 365  *
 366  * @return void
 367  */
 368 abstract function close();
 369 /**
 370  * Crée un nouveau fichier vide dans le répertoire dont le nom est $filename.
 371  *
 372  * @param string $name
 373  * @return void
 374  */
 375 abstract function createFile($filename);
 376 /**
 377  * Supprime un fichier existant du répertoire.
 378  *
 379  * @param string $filename
 380  * @return void
 381  */
 382 abstract function deleteFile($filename);
 383 /**
 384  * Retourne true si un fichier portant le nom donné existe.
 385  *
 386  * @param string $filename
 387  * @return boolean
 388  */
 389 abstract function fileExists($filename);
 390 /**
 391  * Retourne la taille d'un $filename dans le répertoire.
 392  *
 393  * @param string $filename
 394  * @return integer
 395  */
 396 abstract function fileLength($filename);
 397 /**
 398  * Retourne le timestamp UNIX de la date de modification de $filename.
 399  *
 400  * @param string $filename
 401  * @return integer
 402  */
 403 abstract function fileModified($filename);
 404 /**
 405  * Renomme un fichier existant dans le répertoire.
 406  *
 407  * @param string $from
 408  * @param string $to
 409  * @return void
 410  */
 411 abstract function renameFile($from, $to);
 412 /**
 413  * Définit la date de modification de $filename à la date de maintenant.
 414  *
 415  * @param string $filename
 416  * @return void
 417  */
 418 abstract function touchFile($filename);
 419 /**
 420  * Retourne un objet Zend_Search_Lucene_Storage_File object pour un $filename
 421  * donné dans le répertoire
 422  *
 423  * @param string $filename
 424  * @return Zend_Search_Lucene_Storage_File
 425  */
 426 abstract function getFileObject($filename);
 427 }
 428 ]]></programlisting>
 429
 430         <para>
 431             La méthode <methodname>getFileObject($filename)</methodname> de l'instance
 432             <classname>Zend_Search_Lucene_Storage_Directory</classname> retourne un objet
 433             <classname>Zend_Search_Lucene_Storage_File</classname>.
 434         </para>
 435
 436         <para>
 437             La classe abstraite <classname>Zend_Search_Lucene_Storage_File</classname> implémente
 438             l'abstraction de fichiers et les primitives de lecture de fichier d'index.
 439         </para>
 440
 441         <para>
 442             Vous devez aussi étendre <classname>Zend_Search_Lucene_Storage_File</classname> dans
 443             votre implémentation de répertoire.
 444         </para>
 445
 446         <para>
 447             Seulement deux méthodes de <classname>Zend_Search_Lucene_Storage_File</classname>
 448             doivent être surchargées dans votre implémentation :
 449         </para>
 450
 451         <programlisting language="php"><![CDATA[
 452 class MyFile extends Zend_Search_Lucene_Storage_File {
 453     /**
 454      * Définit l'indicateur de position du fichier and avance le pointeur
 455      * de fichier.
 456      * La nouvelle position, calculé en octets depuis le début du fichier,
 457      * est obtenu en ajoutant l'offset à la position spécifiée par $whence,
 458      * dont les valeurs sont définit comme suit :
 459      * SEEK_SET - Définit la position comme égale aux octets de l'offset.
 460      * SEEK_CUR - Définit la position à la position courante plus l'offset.
 461      * SEEK_END - Définit la position à la fin du fichier plus l'offset.
 462      *(Pour déplacer à une position avant la fin du fichier, vous devrez passer
 463      * une valeur négative à l'offset.)
 464      * En cas de succès, retourne 0; sinon, retourne -1
 465      *
 466      * @param integer $offset
 467      * @param integer $whence
 468      * @return integer
 469      */
 470     public function seek($offset, $whence=SEEK_SET) {
 471         ...
 472     }
 473     /**
 474      * Lit $length octets dans le fichier et avance le pointeur de fichier.
 475      *
 476      * @param integer $length
 477      * @return string
 478      */
 479     protected function _fread($length=1) {
 480         ...
 481     }
 482 }
 483 ]]></programlisting>
 484     </sect2>
 485 </sect1>