Documentation de daCode
                           http://www.dacode.org
                               Décembre 2000

               Denis Barbier <barbier@imacs.polytechnique.fr>

   Système de cache
   ================

   Afin d'accroître les performances, daCode utilise un cache pour
   stocker des informations sur disque tant qu'elles restent
   pertinentes, c'est-à-dire tant que les données dans la base les
   concernant n'ont pas été modifiées.

   I) Pages entières cachées
      ----------------------

   Le but recherché est de servir des pages HTML ou PHP lorsqu'elles
   ont déjà été calculées, sans faire intervenir la base de données,
   et l'interpréteur PHP au minimum.
   Cela signifie qu'une requête de la forme
      http://www.dacode.org/2000/12/23/32,0,0,0.php3
   doit envoyer cette page si elle existe, et
      http://www.dacode.org/gen.php3/2000/12/23/32,0,0,0.php3
   sinon, qui doit en même temps générer la page ci-dessus pour les
   appels ultérieurs (la présence de termes après la virgule est
   expliquée ci-dessous).

   Nous allons d'abord voir comment ceci est possible en configurant
   le serveur Apache. Ensuite, nous verrons d'autres solutions
   lorsqu'on ne peut pas accéder à la configuration du serveur web.

     a) Avec mod_rewrite
        ----------------

   Afin de ne pas mélanger ces documents générés avec les sources da
   daCode, ces documents sont placés dans un sous-répertoire de
   htdocs/.  Par défaut, il s'agit du répertoire cache/, mais ce nom
   est paramétrable dans le fichier de configuration (variable
   $config->htmldir).

   Donc en fait, le document se trouve à l'adresse
      http://www.dacode.org/cache/2000/12/23/32,0,0,0.php3

   Afin qu'il soit aussi accessible à l'adresse
      http://www.dacode.org/2000/12/23/32,0,0,0.php3
   il est naturel de penser à utiliser mod_rewrite.

   Voici les règles utilisées sur demo.dacode.org:
     RewriteEngine on

     RewriteCond /var/dacode.org/htdocs/cache%{REQUEST_FILENAME}  -f
     RewriteRule ^(.+) /var/dacode.org/htdocs/cache$1            [L]

     RewriteCond   %{REQUEST_FILENAME} ^/[0-9]                   [OR]
     RewriteCond   %{REQUEST_FILENAME} ^/index,                  [OR]
     RewriteCond   %{REQUEST_FILENAME} ^/section/                [OR]
     RewriteCond   %{REQUEST_FILENAME} ^/topic/

     RewriteRule   ^(.*)$ /var/dacode.org/htdocs/gen.php3$1      [L]

   Lorsqu'une requête http://www.dacode.org/2000/12/23/32,0,0,0.html
   est effectuée, la première règle regarde si le fichier
   /var/dacode.org/htdocs/cache/2000/12/23/32,0,0,0.html existe, et
   si oui, ce fichier est envoyé. Dans le cas contraire, la seconde
   règle s'applique, car la première condition est remplie. Le script
   gen.php3 est donc appelé, avec l'URL du document demandé en
   argument. La sortie du script est envoyée et aussi écrite dans le
   fichier /var/dacode.org/htdocs/cache/2000/12/23/32,0,0,0.html pour
   que les appels ultérieurs l'utilisent sans manipulation autre que
   mod_rewrite.

   Quand l'utilisateur est authentifié, l'affichage dépend de ses
   paramètres. Mais on peut cependant économiser beaucoup de
   traitement.  Pour celà, le même processus que ci-dessus est mis en
   place, mais lors de l'écriture du fichier dans le cache, certaines
   informations (comme la boite d'authentification) sont enlevées et
   remplacées par des appels PHP. Mais la page ainsi générée demande
   très peu de traitement par PHP.

     b) Sans mod_rewrite
        ----------------

   Il n'y a pas le choix, on est obligé de faire apparaitre le script
   dans l'URL, ce qui signifie qu'il faut obligatoirement avoir
   $this->visiblenewsfile=1 dans le fichier de configuration.
   L'appel se fera sur l'adresse
      http://www.dacode.org/gen.php3/2000/12/23/32,0,0,0.php3
   qui ira chercher la page
      /var/dacode.org/htdocs/cache/2000/12/23/32,0,0,0.php3
   si elle existe.
   Le répertoire de cache n'est alors pas obligatoirement sous
   htdocs, puisque les pages ne sont pas appelées directement, mais
   pour des raisons de cohérence, ce cas n'a pas été pris en compte.
   
   Il est néanmoins possible d'avoir une URL dans lequel le script
   n'apparait pas, par exemple
      http://www.dacode.org/forum/2000/12/23/32,0,0,0.php3
   Pour celà, il faut renommer gen.php3 en forum.php3, changer la
   définition de $this->newsfile dans phplib/config.php3, et indiquer
   au serveur que la requête /forum/ doit invoquer /forum.php3.
   Il existe plusieurs façons d'y arriver avec Apache, par exemple
   avec une directive Alias (mais il faut avoir accès à la
   configuration du serveur), ou en activant l'option MultiViews dans
   un fichier .htaccess à la racine du site.

     c) Configuration de daCode
        -----------------------

   Si on souhaite utiliser le cache, il faut positionner la variable
   $this->htmldir dans phplib/config.php3 à la valeur souhaitée.
   Celle-ci est un chemin relatif par rapport à htdocs, et doit se
   terminer par un slash. Ainsi,
     $this->htmldir = '/';
   mettra les fichiers cachés dans htdocs, et
     $this->htmldir = 'cache/';
   les mettra dans htdocs/cache. Il est de très loin préférable de ne
   pas choisir cette première solution, qui est source de problèmes.

   Si cette variable est vide, le cache est désactivé.

   Ensuite, il faut autoriser daCode à créer les fichiers temporaires
   dans le répertoire. Pour cela, le plus simple est de créer le
   répertoire htdocs/cache, et changer le propriétaire de ce
   répertoire, pour lui donner l'identité du process Apache
   (www-data, nobody au autre, suivant les OS). Si on n'est pas root
   sur la machine, on peut néanmoins créer ce répertoire avec le bon
   utilisateur en mettant le répertoire htdocs accessible en
   écriture, et en faisant un mkdir('cache') avec PHP. Il faut
   ensuite penser à remettre les bons droits sur htdocs.

   Le fait de rendre le script visible dans l'URL est gouverné par la
   variable $this->visiblenewsfile. Si elle vaut 1, le script
   gen.php3 apparait dans l'URL.

     d) Paramètres utilisateurs
        -----------------------

   Dans tous les cas de figure, des paramètres sont passés dans l'URL
   pour tenir compte des règlages des utilisateurs. Ces paramètres
   sont actuellement au nombre de 3 :
     hide_sig : 1 si l'utilisateur demande à ne pas voir les
                signatures des posteurs, 0 sinon
     score    : score minimal en dessous duquel un commentaire n'est
                pas affiché
     theme    : numéro du thème
   Par exemple,
        http://www.dacode.org/2000/12/23/32,1,3,1.php3
   signifie que l'utilisateur a adopté le thème slashdot, qu'il ne
   veut pas voir les signatures des posteurs, et qu'il n'est
   intéressé que par les commentaires de score >= 3.
   Les paramètres passés dans l'URL sont pris de préférence aux
   paramètres choisis par l'utilisateur, cela permet par exemple de
   bookmarker la page d'accueil avec les réglages que l'on souhaite,
   sans avoir besoin de cookie. Avec les paramètres ci-dessus, il
   suffit de bookmarker la page
        http://www.dacode.org/index,1,3,1.php3

   II) Morceaux de pages cachés
       ------------------------

   En plus des pages mises en cache, il existe une autre technique
   qui permet d'accélérer le traitement.

   Les pages sont composées de boites. Ces boites sont stockées sur
   le disque, et restituées sans faire appel à PHP si les paramètres
   sont identiques. Le nom du répertoire contenant ces boites est
   $this->cachedir dans le fichier de configuration
   phplib/config.php3.

   Comme l'inclusion de ces fichiers se fait par PHP et non
   directement par Apache, ce répertoire peut se trouver n'importe où
   sur le disque. C'est pourquoi la variable $this->cachedir contient
   un répertoire absolu, contrairement à $this->htmldir qui contient
   un chemin relatif par rapport à htdocs.

   Si cette variable est vide, le cache est désactivé.

   Comme pour $this->htmldir, il faut s'assurer qu'Apache a le droit
   de créer des fichiers dans ce répertoire.