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<69>e pour acc<63>l<EFBFBD>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<63> sans qu'il ne soit n<>cessaire de reg<65>n<EFBFBD>rer le r<>sultat.
   Le syst<73>me de cache
   peut acc<63>l<EFBFBD>rer les traitements de faton impressionnante, en particulier les
   templates dont la compilation est tr<74>s longue. Comme le r<>sultat de
   display() ou de fetch() est dans le cache, un fichier de cache peut
   <20>tre compos<6F> 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<EFBFBD>r<EFBFBD>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 <20>tre int<6E>ressant de mettre cette page
   dans le cache pour une heure ou plus. A l'inverse, si vous affichez une page
   de m<>t<EFBFBD>o mises a jour toutes les minutes, mettre cette page en cache
   n'a aucun sens.
   </para>
   <sect1 id="caching.setting.up">
   <title>Param<EFBFBD>trer le cache</title>
   <para>
   La premi<6D>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<69>, 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<70>f<EFBFBD>r<EFBFBD> a la r<>utilisation
    du template.
    </para>
	<note>
	<title>Note technique</title>
	<para>
	Les fichiers situ<74>s dans $cache_dir sont nomm<6D>s de la m<>me faton que les templates.
	Bien qu'ils aient une extension ".php", ils ne sont pas vraiment ex<65>cutable.
	N'Tditez surtout pas ces fichiers !
	</para>
	</note>
	<para>
	Tout fichier de cache a une dur<75>e de vie limit<69>e d<>termin<69>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<75>e est
	d<>pass<73>e, le cache est reg<65>n<EFBFBD>r<EFBFBD>. Il est possible de donner
   une dur<75>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<EFBFBD>glage individuel de cache_lifetime</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

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

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

// r<>gle la dur<75>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<75>e de vie
// du fichier de cache de home.tpl a d<>ja Tt<54> r<>gl<67>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<66> pour d<>tecter une Tventuelle
  modification. Si l'un de ces fichiers a Tt<54> modifi<66> depuis que le fichier de cache a Tt<54>
  g<>n<EFBFBD>r<EFBFBD>, le cache est imm<6D>diatement reg<65>n<EFBFBD>r<EFBFBD>. Ce processus est covteux, donc,
  pour des raisons de performances, mettez ce param<61>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<65>n<EFBFBD>r<EFBFBD>s. Ceci revient finalement a
   d<>sactiver le cache. $force_compile est utilis<69> 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<71>te
   a une base de donn<6E>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 <20>tre mise en cache a part
    une banni<6E>re en bas a droite. En utilisant une fonction insert pour la
    banni<6E>re, vous pouvez garder cet Tl<54>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<61>s pour chacun d'eux. Vous
   pouvez faire cela en passant un identifiant de cache (cache_id) en
   deuxi<78>me param<61>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 <20>tre cr<63>T. Dans cet exemple,
    "article_id" a Tt<54> pass<73> dans l'URL et est utilis<69> 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<61>rer mauvais. L'identifiant
	de cache est utilis<69> pour cr<63>er un r<>pertoire sur le syst<73>me de fichiers,
	donc si l'utilisateur d<>cide de donner une tr<74>s grande valeur a article_id
	ou d'Tcrire un script qui envoie des article_id de faton al<61>atoire,
	cela pourra causer des probl<62>mes cot<6F> serveur. Assurez-vous de bien
	tester toute donn<6E>e pass<73>e en param<61>tre avant de l'utiliser. Dans cet
	exemple, peut-<2D>tre savez-vous que article_id a une longueur de 10
   caract<63>res, est exclusivement compos<6F> de caract<63>res alph-num<75>riques et
   doit avoir une valeur contenue dans la base de donn<6E>es. VTrifiez-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<61>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<6E>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 Tlabor<6F>s en param<61>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<73>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
-->