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 utilisTe pour accTlTrer l'appel de <link
   linkend="api.display">display()</link> ou de <link
   linkend="api.fetch">fetch()</link> en sauvegardant leur rTsultat
   dans un fichier. Si un fichier de cache est disponible lors d'un appel,
   il sera affichT sans qu'il ne soit nTcessaire de regTnTrer le rTsultat.
   Le systFme de cache
   peut accTlTrer les traitements de faton impressionnante, en particulier les
   templates dont la compilation est trFs longue. Comme le rTsultat de
   display() ou de fetch() est dans le cache, un fichier de cache peut
   Otre composT 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 gTnTrTs, 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 Otre intTressant de mettre cette page
   dans le cache pour une heure ou plus. A l'inverse, si vous affichez une page
   de mTtTo mises a jour toutes les minutes, mettre cette page en cache
   n'a aucun sens.
   </para>
   <sect1 id="caching.setting.up">
   <title>ParamTtrer le cache</title>
   <para>
   La premiFre 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 activT, la fonction display('index.tpl') va afficher
    le template mais sauvegardera par la mOme occasion une copie du rTsultat
    dans un fichier (de cache) du rTpertoire
    <link linkend="variable.cache.dir">$cache_dir</link>. Au prochain appel de
    display('index.tpl'), le fichier de cache sera prTfTrT a la rTutilisation
    du template.
    </para>
	<note>
	<title>Note technique</title>
	<para>
	Les fichiers situTs dans $cache_dir sont nommTs de la mOme faton que les templates.
	Bien qu'ils aient une extension ".php", ils ne sont pas vraiment exTcutable.
	N'Tditez surtout pas ces fichiers !
	</para>
	</note>
	<para>
	Tout fichier de cache a une durTe de vie limitTe dTterminTe par <link
	linkend="variable.cache.lifetime">$cache_lifetime</link>. La valeur par
	dTfaut est 3600 secondes, i.e. 1 heure. Une fois que cette durTe est
	dTpassTe, le cache est regTnTrT. Il est possible de donner
   une durTe d'expiration propre a chaque fichier de cache en rTglant
   $caching = 2.
   Se reporter a la documentation de <link
	linkend="variable.cache.lifetime">$cache_lifetime</link> pour plus de
	dTtails.
	</para>
    <example>
     <title>rTglage individuel de cache_lifetime</title>
     <programlisting>
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = 2; // rTgler la durTe de vie individuellement

// rTgle la durTe de vie du cache a 15 minutes pour index.tpl
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');

// rTgle la durTe de vie du cache a 1 heure pour home.tpl
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');

// NOTE : le rTglage suivant ne fonctionne pas quand $caching = 2. La durTe de vie
// du fichier de cache de home.tpl a dTja TtT rTglTe 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 vTrifiT pour dTtecter une Tventuelle
  modification. Si l'un de ces fichiers a TtT modifiT depuis que le fichier de cache a TtT
  gTnTrT, le cache est immTdiatement regTnTrT. Ce processus est covteux, donc,
  pour des raisons de performances, mettez ce paramFtre 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 regTnTrTs. Ceci revient finalement a
   dTsactiver le cache. $force_compile est utilisT a des fins de dTbogage,
   un moyen plus efficace de dTsactiver le cache est de rTgler
   <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 requOte
   a une base de donnTes, vous pouvez utiliser cette mTthode 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 Otre mise en cache a part
    une banniFre en bas a droite. En utilisant une fonction insert pour la
    banniFre, vous pouvez garder cet TlTment dynamique dans le contenu qui
    est en cache. Reportez-vous a la documentation
    <link linkend="language.function.insert">insert</link> pour plus de dTtails
    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 mOme appel
   aux fonctions display() ou fetch(). Imaginons qu'un appel a display('index.tpl')
   puisse avoir plusieurs rTsultats, en fonction de certaines conditions, et que
   vous vouliez des fichiers de cache sTparTs pour chacun d'eux. Vous
   pouvez faire cela en passant un identifiant de cache (cache_id) en
   deuxiFme paramFtre 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 Otre crTT. Dans cet exemple,
    "article_id" a TtT passT dans l'URL et est utilisT 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 rTsultat peut s'avTrer mauvais. L'identifiant
	de cache est utilisT pour crTer un rTpertoire sur le systFme de fichiers,
	donc si l'utilisateur dTcide de donner une trFs grande valeur a article_id
	ou d'Tcrire un script qui envoie des article_id de faton alTatoire,
	cela pourra causer des problFmes cotT serveur. Assurez-vous de bien
	tester toute donnTe passTe en paramFtre avant de l'utiliser. Dans cet
	exemple, peut-Otre savez-vous que article_id a une longueur de 10
   caractFres, est exclusivement composT de caractFres alph-numTriques et
   doit avoir une valeur contenue dans la base de donnTes. VTrifiez-le bien !
	</para>
	</note>
	<para>
	Assurez-vous de bien passer le mOme 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 paramFtre
    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 maniFre vous pouvez "grouper" vos fichiers de cache en leur
    donnant le mOme identifiant.
    </para>
   </sect1>
   <sect1 id="caching.groups">
    <title>groupes de fichiers de cache</title>
    <para>
    Vous pouvez faire des groupements plus TlaborTs en paramTtrant les
    groupes d'identifiant de cache. Il suffit de sTparer 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 dTsirez.
    </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 systFme 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 rTpertoire "theme/blue". Si vous voulez
   faire cela, vous devez les grouper avec un mOme 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
-->