smarty/docs/fr/programmers/caching.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <chapter id="caching">
   <title>Cache</title>
   <para>
   Le cache est utilisée pour accélérer l'appel de <link
   linkend="api.display">display()</link> ou de <link
   linkend="api.fetch">fetch()</link> en sauvegardant leur résultat
   dans un fichier. Si un fichier de cache est disponible lors d'un appel,
   il sera affiché sans qu'il ne soit nécessaire de regénérer le résultat.
   Le systéme de cache
   peut accélérer les traitements de faton impressionnante, en particulier les
   templates dont la compilation est trés longue. Comme le résultat de
   display() ou de fetch() est dans le cache, un fichier de cache peut
   être composé de plusieurs fichiers de templates, plusieurs fichiers
   de configuration, etc.
   </para>
   <para>
   Comme les templates sont dynamiques, il est important de faire attention
   a la faton dont les fichiers de cache sont générés, et pour combien de temps.
   Si par exemple vous affichez la page d'accueil de votre site Web dont le
   contenu ne change pas souvent, il peut être intéressant de mettre cette page
   dans le cache pour une heure ou plus. A l'inverse, si vous affichez une page
   de météo mises a jour toutes les minutes, mettre cette page en cache
   n'a aucun sens.
   </para>
   <sect1 id="caching.setting.up">
   <title>Paramétrer le cache</title>
   <para>
   La premiére chose a faire est d'activer le cache. Cela est fait en
   mettant <link linkend="variable.caching">$caching</link> = true
   (ou 1).
   </para>
    <example>
     <title>activation du cache</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

$smarty->display('index.tpl');</programlisting>
    </example>
    <para>
    Avec le cache activé, la fonction display('index.tpl') va afficher
    le template mais sauvegardera par la même occasion une copie du résultat
    dans un fichier (de cache) du répertoire
    <link linkend="variable.cache.dir">$cache_dir</link>. Au prochain appel de
    display('index.tpl'), le fichier de cache sera préféré a la réutilisation
    du template.
    </para>
	<note>
	<title>Note technique</title>
	<para>
	Les fichiers situés dans $cache_dir sont nommés de la même faton que les templates.
	Bien qu'ils aient une extension ".php", ils ne sont pas vraiment exécutable.
	N'éditez surtout pas ces fichiers !
	</para>
	</note>
	<para>
	Tout fichier de cache a une durée de vie limitée déterminée par <link
	linkend="variable.cache.lifetime">$cache_lifetime</link>. La valeur par
	défaut est 3600 secondes, i.e. 1 heure. Une fois que cette durée est
	dépassée, le cache est regénéré. Il est possible de donner
   une durée d'expiration propre a chaque fichier de cache en réglant
   $caching = 2.
   Se reporter a la documentation de <link
	linkend="variable.cache.lifetime">$cache_lifetime</link> pour plus de
	détails.
	</para>
    <example>
     <title>réglage individuel de cache_lifetime</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = 2; // régler la durée de vie individuellement

// régle la durée de vie du cache a 15 minutes pour index.tpl
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');

// régle la durée de vie du cache a 1 heure pour home.tpl
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');

// NOTE : le réglage suivant ne fonctionne pas quand $caching = 2. La durée de vie
// du fichier de cache de home.tpl a déja été réglée a 1 heure et ne respectera
// plus la valeur de $cache_lifetime. Le cache de home.tpl expirera toujours
// dans 1 heure.
$smarty->cache_lifetime = 30; // 30 secondes
$smarty->display('home.tpl');</programlisting>
    </example>
  <para>
  Si <link linkend="variable.compile.check">$compile_check</link> est actif,
  chaque fichier de template et de configuration qui a un rapport
  avec le fichier de cache sera vérifié pour détecter une éventuelle
  modification. Si l'un de ces fichiers a été modifié depuis que le fichier de cache a été
  généré, le cache est immédiatement regénéré. Ce processus est covteux, donc,
  pour des raisons de performances, mettez ce paramétre a false pour une application
  en production.
  </para>
    <example>
     <title>activation de $compile_check</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;
$smarty->compile_check = true;

$smarty->display('index.tpl');</programlisting>
	</example>
   <para>
   Si <link linkend="variable.force.compile">$force_compile</link> est actif,
   les fichiers de cache sont toujours regénérés. Ceci revient finalement a
   désactiver le cache. $force_compile est utilisé a des fins de débogage,
   un moyen plus efficace de désactiver le cache est de régler
   <link	linkend="variable.caching">$caching</link> = false (ou 0).
   </para>
   <para>
   La fonction <link linkend="api.is.cached">is_cached()</link> permet
   de tester si un template a ou non un fichier de cache valide.
   Si vous disposez d'un template en cache qui requiert une requête
   a une base de données, vous pouvez utiliser cette méthode plut(t
   que $compile_check.
   </para>
    <example>
     <title>utilisation de is_cached()</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

if(!$smarty->is_cached('index.tpl')) {
   // pas de cache disponible, on assigne
	$contents = get_database_contents();
	$smarty->assign($contents);
}

$smarty->display('index.tpl');</programlisting>
    </example>
    <para>
    Vous pouvez rendre dynamiques seulement certaines parties d'une
    page avec la fonction de templates <link
    linkend="language.function.insert">insert</link>.
    Imaginons que toute une page doit être mise en cache a part
    une banniére en bas a droite. En utilisant une fonction insert pour la
    banniére, vous pouvez garder cet élément dynamique dans le contenu qui
    est en cache. Reportez-vous a la documentation
    <link linkend="language.function.insert">insert</link> pour plus de détails
    et des exemples.
    </para>
    <para>
    Vous pouvez effacer tous les fichiers du cache avec la fonction <link
	 linkend="api.clear.all.cache">clear_all_cache(),</link> ou de faton
	 individuelle (ou par groupe) avec la fonction <link
	 linkend="api.clear.cache">clear_cache()</link>.
    </para>
    <example>
     <title>nettoyage du cache</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

// efface tous les fichiers du cache
$smarty->clear_all_cache();

// efface le fichier de cache du template 'index.tpl'
$smarty->clear_cache('index.tpl');

$smarty->display('index.tpl');</programlisting>
    </example>
   </sect1>
   <sect1 id="caching.multiple.caches">
   <title>Caches multiples pour une seule page</title>
   <para>
   Vous pouvez avoir plusieurs fichiers de caches pour un même appel
   aux fonctions display() ou fetch(). Imaginons qu'un appel a display('index.tpl')
   puisse avoir plusieurs résultats, en fonction de certaines conditions, et que
   vous vouliez des fichiers de cache séparés pour chacun d'eux. Vous
   pouvez faire cela en passant un identifiant de cache (cache_id) en
   deuxiéme paramétre a l'appel de fonction.
   </para>
    <example>
     <title>Passage d'un cache_id a display()</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

$my_cache_id = $_GET['article_id'];

$smarty->display('index.tpl',$my_cache_id);</programlisting>
    </example>
    <para>
    Nous passons ci-dessus la variable $my_cache_id a display() comme
    identifiant de cache. Pour chaque valeur distincte de $my_cache_id,
    un fichier de cache distinct va être créé. Dans cet exemple,
    "article_id" a été passé dans l'URL et est utilisé en tant qu'identifiant
    de cache.
    </para>
 	<note>
	<title>Note technique</title>
	<para>
	Soyez prudent en passant des valeurs depuis un client (navigateur Web)
	vers Smarty (ou vers n'importe quelle application PHP). Bien que l'exemple
	ci-dessus consistant a utiliser article_id depuis l'URL puisse paraetre
	commode, le résultat peut s'avérer mauvais. L'identifiant
	de cache est utilisé pour créer un répertoire sur le systéme de fichiers,
	donc si l'utilisateur décide de donner une trés grande valeur a article_id
	ou d'écrire un script qui envoie des article_id de faton aléatoire,
	cela pourra causer des problémes coté serveur. Assurez-vous de bien
	tester toute donnée passée en paramétre avant de l'utiliser. Dans cet
	exemple, peut-être savez-vous que article_id a une longueur de 10
   caractéres, est exclusivement composé de caractéres alph-numériques et
   doit avoir une valeur contenue dans la base de données. Vérifiez-le bien !
	</para>
	</note>
	<para>
	Assurez-vous de bien passer le même identifiant aux fonctions
   <link linkend="api.is.cached">is_cached()</link> et
	<link linkend="api.clear.cache">clear_cache()</link>.
	</para>
	<example>
     <title>passer un  cache_id a is_cached()</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

$my_cache_id = $_GET['article_id'];

if(!$smarty->is_cached('index.tpl',$my_cache_id)) {
	// pas de fichier de cache dispo, on assigne donc les variables
	$contents = get_database_contents();
	$smarty->assign($contents);
}

$smarty->display('index.tpl',$my_cache_id);</programlisting>
    </example>
    <para>
    Vous pouvez effacer tous les fichiers de cache pour un identifiant
    de cache particulier en passant null en tant que premier paramétre
    a clear_cache().
    </para>
	<example>
     <title>effacement de tous les fichiers de cache pour un identifiant de cache particulier</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

// efface tous les fichiers de cache avec "sports" comme identifiant
$smarty->clear_cache(null,"sports");

$smarty->display('index.tpl',"sports");</programlisting>
    </example>
    <para>
    De cette maniére vous pouvez "grouper" vos fichiers de cache en leur
    donnant le même identifiant.
    </para>
   </sect1>
   <sect1 id="caching.groups">
    <title>groupes de fichiers de cache</title>
    <para>
    Vous pouvez faire des groupements plus élaborés en paramétrant les
    groupes d'identifiant de cache. Il suffit de séparer chaque sous-groupes
    avec une barre verticale "|" dans la valeur de l'identifiant de cache.
    Vous pouvez faire autant de sous-groupes que vous le désirez.
    </para>
	<example>
     <title>groupes d'identifiants de cache</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

// efface tous les fichiers de cache avec "sports|basketball" comme premiers
// groupes d'identifiants de cache
$smarty->clear_cache(null,"sports|basketball");

// efface tous les fichiers de cache "sports" comme premier groupe d'identifiants.
// Inclue donc "sports|basketball" ou "sports|nimportequoi|nimportequoi|..."
$smarty->clear_cache(null,"sports");

$smarty->display('index.tpl',"sports|basketball");</programlisting>
    </example>
   <note>
   <title>Note technique</title>
   <para>
   Le systéme de cache n'utilise PAS le chemin vers le template en quoi
   que ce soit pour l'identifiant de cache.  Si par exemple vous
   faites display('themes/blue/index.tpl'), vous ne pouvez pas effacer tous
   les fichiers de cache dans le répertoire "theme/blue". Si vous voulez
   faire cela, vous devez les grouper avec un même identifiant de cache,
   display('themes/blue/index.tpl','themes|blue'). Vous pouvez ensuite effacer les
   fichiers de cache pour blue et theme avec clear_cache(null,'theme|blue').
   </para>
   </note>
   </sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->