examples.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<!-- CREDITS: DAnnebicque -->

<appendix xml:id="session.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id="session.examples.basic">
  <title>Utilisation simple</title>
   <para>
    Les sessions sont un moyen simple de stocker des données individuelles pour chaque
    utilisateur en utilisant un identifiant de session unique. Elles peuvent être utilisées
    pour faire persister des informations entre plusieurs pages. Les identifiants de session
    sont normalement envoyés au navigateur via des cookies de session, et l'identifiant
    est utilisé pour récupérer les données existantes de la session. L'absence d'un identifiant
    ou d'un cookie de session indique à PHP de créer une nouvelle session, et génère ainsi
    un nouvel identifiant de session.
   </para>
   <para>
    Les sessions suivent une cinématique simple. Lorsqu'une session est démarrée, PHP va
    soit récupérer une session existante en utilisant l'identifiant de session passé (habituellement
    depuis un cookie de session) ou si aucun identifiant de session n'est passé, il va créer une
    nouvelle session. PHP va ainsi peupler la variable superglobale <varname>$_SESSION</varname>
    avec toutes les données de session une fois la session démarrée. Lorsque PHP s'arrête,
    il va prendre automatiquement le contenu de la variable superglobale <varname>$_SESSION</varname>,
    le sérialiser, et l'envoyer pour stockage au gestionnaire de sauvegarde de session.
   </para>
   <para>
    Par défaut, PHP utilise en interne le gestionnaire de sauvegarde <parameter>files</parameter>
    qui est défini via la directive <link linkend="ini.session.save-handler">session.save_handler</link>.
    Les données de session seront sauvegardées sur le serveur à l'endroit spécifié par
    la directive de configuration <link linkend="ini.session.save-path">session.save_path</link>.
   </para>
   <para>
    Les sessions peuvent être démarrées manuellement en utilisant la fonction
    <function>session_start</function>. Si la directive de configuration
    <link linkend="ini.session.auto-start">session.auto_start</link> est définie à
    <parameter>1</parameter>, une session démarrera automatiquement lors du début
    de la demande.
   </para>
   <para>
    Les sessions s'arrêtent automatiquement lorsque PHP a terminé d'exécuter un script, mais
    peuvent être stoppées manuellement en utilisant la fonction
    <function>session_write_close</function>.
   </para>
  <para>
   <example>
    <title>
     Enregistrer une variable avec <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
if (!isset($_SESSION['count'])) {
  $_SESSION['count'] = 0;
} else {
  $_SESSION['count']++;
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>
     Retirer une variable de session avec la superglobale <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
unset($_SESSION['count']);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <caution>
    <para>
     N'utilisez PAS la fonction <function>unset</function>
     avec <varname>$_SESSION</varname> sous la forme
     <literal>unset($_SESSION)</literal> sinon, cela rendra impossible
     l'enregistrement de données dans la session en utilisant la super-globale
     <varname>$_SESSION</varname>.
    </para>
   </caution>
  </para>
  <warning>
   <para>
    Vous ne pouvez pas utiliser les références sur des variables de session
    car il n'y a aucune manière faisable de restaurer une référence vers une
    autre variable.
   </para>
  </warning>
  <note>
   <para>
    Les sessions basées sur un fichier (par défaut en PHP) verrouillent
    le fichier de session lorsqu'une session est ouverte via la fonction
    <function>session_start</function> ou implicitement via la directive
    de configuration <link linkend="ini.session.auto-start">session.auto_start</link>.
    Une fois verrouillée, aucun autre script ne peut accéder au même fichier
    de session tant que la session n'a pas été fermée par le script
    l'ayant ouverte, ou tant que la fonction
    <function>session_write_close</function> n'a pas été appelée.
   </para>
   <para>
    Ceci peut être génant pour les sites Web utilisant AJAX et produisant
    plusieurs requêtes concurrentes. La façon la plus simple pour contourner
    ce problème est d'appeler la fonction <function>session_write_close</function>
    dès lors que les modifications dans la session ont été effectuées,
    de préférence en début de script. Vous pouvez aussi utiliser
    un autre gestionnaire de session qui supporte la concurrence.
   </para>
  </note>
 </section>
 
 <section xml:id="session.idpassing">
  <title>Passer l'identifiant de session (session ID)</title>
  <para>
   Il y a deux méthodes de propagation de l'identifiant de session :
   <itemizedlist>
    <listitem>
     <simpara>
      Cookies
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Par URL
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Le module de session supporte les deux méthodes. Les cookies sont
   optimaux, mais comme ils ne sont pas sûrs (tous les internautes
   ne les acceptent pas), ils ne sont pas fiables. La seconde
   méthode place l'identifiant de session directement dans les URL.
  </para>
  <para>
   PHP est capable de faire cela de manière transparente.
   Si l'option de compilation
   <literal>session.use_trans_sid</literal> est activée, 
   les URLs relatives seront modifiées pour contenir l'identifiant
   de session automatiquement.
   <note>
    <para>
     L'option <link linkend="ini.arg-separator.output">arg_separator.output</link>
     de &php.ini; vous permet de personnaliser le séparateur d'arguments.
     Pour être complètement en accord avec les spécifications XHTML, spécifiez
     &amp;amp; ici.
    </para>
   </note>
  </para>
  <para>
   Alternativement, vous pouvez utiliser la constante <constant>SID</constant>
   qui est définie si la session a commencé. Si le client n'envoie pas un cookie de session
   approprié, il aura la forme <literal>session_name=session_id</literal>.
   Sinon, il vaudra une chaîne vide. Ainsi, vous pouvez dans tous les cas
   l'inclure dans l'URL.
  </para>
  <para>
   L'exemple suivant vous montre comment enregistrer une variable et comment
   réaliser un lien correct avec une autre page, avec
   <constant>SID</constant>.
   <example>
    <title>Compter le nombre de passages d'un utilisateur sur une page</title>
    <programlisting role="php">
<![CDATA[
<?php

session_start();

if (empty($_SESSION['count'])) {
   $_SESSION['count'] = 1;
} else {
   $_SESSION['count']++;
}
?>

<p>
 Bonjour visiteur, vous avez vu cette page <?php echo $_SESSION['count']; ?> fois.
</p>

<p>
 Pour continuer, <a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">cliquez ici</a>.
</p>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   La fonction <function>htmlspecialchars</function> est utilisée lors de l'affichage
   du <constant>SID</constant> dans le but de contrer les attaques XSS.
  </para>
  <para>
   L'affichage du <constant>SID</constant>, comme montré dans l'exemple
   ci-dessus, n'est pas nécessaire si <link
   linkend="ini.session.use-trans-sid">
   --enable-trans-sid</link> a été utilisé pour compiler
   PHP.
  </para>
  <note>
   <para>
    Les URL non-relatives sont considérées comme externes au site, et ne
    recevront pas le <constant>SID</constant>, car la fuite du <constant>SID</constant>
    vers un serveur différent présente un risque de sécurité important.
   </para>
  </note>
 </section>
 
 <section xml:id="session.customhandler">
  <title>Gestion personnalisée des sessions</title>
  <para>
   Pour implémenter un stockage en base de données, ou toute autre méthode,
   vous aurez besoin de la fonction <function>session_set_save_handler</function> pour
   paramétrer vos propres fonctions de stockage.
   Un gestionnaires de session peut être crée en utilisant l'interface
   <classname>SessionHandlerInterface</classname> ou en étendant les
   gestionnaires internes de PHP en héritant de la classe
   <classname>SessionHandler</classname>.
  </para>
  <para>
   Les fonctions de rappel précisées dans <function>session_set_save_handler</function> sont
   des méthodes appelées par PHP pendant le cycle de vie de la session: <parameter>open</parameter>,
   <parameter>read</parameter>, <parameter>write</parameter> et <parameter>close</parameter>
   ainsi que les fonctions de ménage <parameter>destroy</parameter> pour supprimer une session
   et <parameter>gc</parameter> pour une collecte périodique des gabarits.
  </para>
  <para>
   Ainsi, PHP a toujours besoin d'un gestionnaire de sessions. Par défaut il s'agit du gestionnaire
   interne 'files'. Un gestionnaire personnalisé peut être indiqué au moyen de
   <function>session_set_save_handler</function>. D'autres gestionnaires alternatifs peuvent être proposés
   par des extensions PHP, comme <parameter>sqlite</parameter>, <parameter>memcache</parameter>
   et <parameter>memcached</parameter> et peuvent être utilisés via
   <link linkend="ini.session.save-handler">session.save_handler</link>.
  </para>
  <para>
   Lorsque la session démarre, PHP appelera en interne la fonction <parameter>open</parameter> du gestionnaire, suivie de
   <parameter>read</parameter> qui doit alors retourner une chaine encodée exactement comme elle a été passée lors du stockage.
   Une fois que la fonction de rappel de <parameter>read</parameter> a retourné sa chaine, PHP va alors la décoder
   et peupler la super-globale <varname>$_SESSION</varname> en conséquence.
  </para>
  <para>
   Lorsque PHP se termine, (ou lorsque <function>session_write_close</function> est appelée), il va en
   interne encoder le contenu de <varname>$_SESSION</varname> et le passer avec l'ID de session à la
   fonction <parameter>write</parameter>. Après <parameter>write</parameter>, PHP invoquera <parameter>close</parameter>.
  </para>
  <para>
   Lorsqu'une session est détruite, PHP appelera <parameter>destroy</parameter> avec l'ID de session.
  </para>
  <para>
   PHP appelera la fonction de rappel <parameter>gc</parameter> de temps en temps pour nettoyer
   les sessions expirées en fonction de leur
   temps de vie maximum. Cet appel devrait mener à la destruction des enregistrements dans
   le support de stockage qui n'ont été accédés depuis <parameter>$lifetime</parameter>.
  </para>
 </section>
</appendix>

<!-- 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:"~/.phpdoc/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
-->