
                          Documentation de daCode
                           http://www.dacode.org
                               Dcembre 2000

               Denis Barbier <barbier@imacs.polytechnique.fr>

   Systme de cache
   ================

   Afin d'accrotre les performances, daCode utilise un cache pour
   stocker des informations sur disque tant qu'elles restent
   pertinentes, c'est--dire tant que les donnes dans la base les
   concernant n'ont pas t modifies.

   I) Pages entires caches
      ----------------------

   Le but recherch est de servir des pages HTML ou PHP lorsqu'elles
   ont dj t calcules, sans faire intervenir la base de donnes,
   et l'interprteur PHP au minimum.
   Cela signifie qu'une requte 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 mme temps gnrer la page ci-dessus pour les
   appels ultrieurs (la prsence de termes aprs la virgule est
   explique 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 accder  la configuration du serveur web.

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

   Afin de ne pas mlanger ces documents gnrs avec les sources da
   daCode, ces documents sont placs dans un sous-rpertoire de
   htdocs/.  Par dfaut, il s'agit du rpertoire cache/, mais ce nom
   est paramtrable 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 rgles utilises 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 requte http://www.dacode.org/2000/12/23/32,0,0,0.html
   est effectue, la premire rgle 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
   rgle s'applique, car la premire condition est remplie. Le script
   gen.php3 est donc appel, avec l'URL du document demand en
   argument. La sortie du script est envoye et aussi crite dans le
   fichier /var/dacode.org/htdocs/cache/2000/12/23/32,0,0,0.html pour
   que les appels ultrieurs l'utilisent sans manipulation autre que
   mod_rewrite.

   Quand l'utilisateur est authentifi, l'affichage dpend de ses
   paramtres. Mais on peut cependant conomiser beaucoup de
   traitement.  Pour cel, le mme 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 enleves et
   remplaces par des appels PHP. Mais la page ainsi gnre demande
   trs 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 rpertoire de cache n'est alors pas obligatoirement sous
   htdocs, puisque les pages ne sont pas appeles directement, mais
   pour des raisons de cohrence, ce cas n'a pas t pris en compte.
   
   Il est nanmoins 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
   dfinition de $this->newsfile dans phplib/config.php3, et indiquer
   au serveur que la requte /forum/ doit invoquer /forum.php3.
   Il existe plusieurs faons d'y arriver avec Apache, par exemple
   avec une directive Alias (mais il faut avoir accs  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 souhaite.
   Celle-ci est un chemin relatif par rapport  htdocs, et doit se
   terminer par un slash. Ainsi,
     $this->htmldir = '/';
   mettra les fichiers cachs dans htdocs, et
     $this->htmldir = 'cache/';
   les mettra dans htdocs/cache. Il est de trs loin prfrable de ne
   pas choisir cette premire solution, qui est source de problmes.

   Si cette variable est vide, le cache est dsactiv.

   Ensuite, il faut autoriser daCode  crer les fichiers temporaires
   dans le rpertoire. Pour cela, le plus simple est de crer le
   rpertoire htdocs/cache, et changer le propritaire de ce
   rpertoire, 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 nanmoins crer ce rpertoire avec le bon
   utilisateur en mettant le rpertoire 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) Paramtres utilisateurs
        -----------------------

   Dans tous les cas de figure, des paramtres sont passs dans l'URL
   pour tenir compte des rglages des utilisateurs. Ces paramtres
   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    : numro du thme
   Par exemple,
        http://www.dacode.org/2000/12/23/32,1,3,1.php3
   signifie que l'utilisateur a adopt le thme slashdot, qu'il ne
   veut pas voir les signatures des posteurs, et qu'il n'est
   intress que par les commentaires de score >= 3.
   Les paramtres passs dans l'URL sont pris de prfrence aux
   paramtres choisis par l'utilisateur, cela permet par exemple de
   bookmarker la page d'accueil avec les rglages que l'on souhaite,
   sans avoir besoin de cookie. Avec les paramtres ci-dessus, il
   suffit de bookmarker la page
        http://www.dacode.org/index,1,3,1.php3

   II) Morceaux de pages cachs
       ------------------------

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

   Les pages sont composes de boites. Ces boites sont stockes sur
   le disque, et restitues sans faire appel  PHP si les paramtres
   sont identiques. Le nom du rpertoire 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 rpertoire peut se trouver n'importe o
   sur le disque. C'est pourquoi la variable $this->cachedir contient
   un rpertoire absolu, contrairement  $this->htmldir qui contient
   un chemin relatif par rapport  htdocs.

   Si cette variable est vide, le cache est dsactiv.

   Comme pour $this->htmldir, il faut s'assurer qu'Apache a le droit
   de crer des fichiers dans ce rpertoire.

