doc-fr/reference/session/functions/session-set-save-handler.xml

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

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>session_set_save_handler</refname>
  <refpurpose>Configure les fonctions de stockage de sessions</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>callable</type><parameter>open</parameter></methodparam>
   <methodparam><type>callable</type><parameter>close</parameter></methodparam>
   <methodparam><type>callable</type><parameter>read</parameter></methodparam>
   <methodparam><type>callable</type><parameter>write</parameter></methodparam>
   <methodparam><type>callable</type><parameter>destroy</parameter></methodparam>
   <methodparam><type>callable</type><parameter>gc</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>create_sid</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>validate_sid</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>
  </methodsynopsis>
  <para>
   Il est possible d'enregistrer le prototype suivant :
  </para>
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>object</type><parameter>sessionhandler</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>&true;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_set_save_handler</function> configure les fonctions
   de stockage de sessions, et permet de choisir des fonctions utilisateurs
   pour sauver et relire toutes les sessions. Cette fonction est
   très pratique lorsqu'il faut sauver les données de sessions
   en utilisant une autre technique que le système par fichier fourni
   par défaut, par exemple le stockage en base de données.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Cette fonction a deux prototypes.
   <variablelist>
    <varlistentry>
     <term><parameter>sessionhandler</parameter></term>
     <listitem>
      <para>
       Une instance d'une classe implémentant une ou plusieurs des interfaces suivantes:
       <interfacename>SessionHandlerInterface</interfacename>, et optionellement
       <interfacename>SessionIdInterface</interfacename>, et/ou
       <interfacename>SessionUpdateTimestampHandlerInterface</interfacename>,
       comme la classe <classname>SessionHandler</classname>,
       pour l'enregistrement comme gestionnaire de session.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>register_shutdown</parameter></term>
     <listitem>
      <para>
       Enregistre la fonction <function>session_write_close</function>
       comme fonction <function>register_shutdown_function</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   ou

   <variablelist>
    <varlistentry>
     <term><parameter>open</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>open</replaceable></methodname>
        <methodparam><type>string</type><parameter>savePath</parameter></methodparam>
        <methodparam><type>string</type><parameter>sessionName</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       La fonction de rappel <literal>open</literal> fonctionne comme un constructeur
       dans une classe, et est exécutée lorsque la session s'ouvre.
       C'est la première fonction de rappel exécutée lorsque la session
       démarre automatiquement ou manuellement avec la fonction
       <function>session_start</function>. La valeur retournée
       est &true; en cas de succès ou &false; si une erreur survient.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>close</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>close</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       La fonction de rappel <literal>close</literal> fonctionne comme un
       destructeur dans une classe, et est exécutée une fois que la fonction
       de rappel write de la session a terminé de s'exécuter. Elle est également
       appelé lorsque la fonction <function>session_write_close</function> est appelée.
       La valeur retournée est &true; en cas de succès, ou &false; si une erreur
       survient.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>string</type><methodname><replaceable>read</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       La fonction de rappel <parameter>read</parameter> doit toujours retournée
       une chaîne sérialisée contenant les données de session encodées
       ou une chaîne vide s'il n'y a aucune donnée à lire.
      </para>
      <para>
       Cette fonction de rappel est appelée en interne par PHP lorsque la session
       commence ou lorsque la fonction <function>session_start</function> est appelée.
       Avant que cette fonction de rappel ne soit invoquée, PHP invoquera
       la fonction de rappel <parameter>open</parameter>.
      </para>
      <para>
       La valeur retournée par cette fonction de rappel doit être exactement du même
       format de sérialisation que celui passé pour le stockage à la fonction
       de rappel <parameter>write</parameter>. La valeur retournée sera désérialisée
       automatiquement par PHP et utilisée pour peupler la variable superglobale
       <varname>$_SESSION</varname>. Malgré le fait que les données ressemblent fortement
       aux données issuées de la fonction <function>serialize</function>, notez que c'est bien
       un format différent, qui est spécifié via l'option de configuration
       <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>write</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
        <methodparam><type>string</type><parameter>data</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       La fonction de rappel <parameter>write</parameter> est appelée lorsque la session
       doit être sauvegardée et fermée. Cette fonction de rappel reçoit l'identifiant de
       la session courante ainsi qu'une version sérialisée du contenu de la variable
       superglobale <varname>$_SESSION</varname>. La méthode de sérialisation utilisée en
       interne par PHP est spécifiée via l'option de configuration
       <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
      <para>
       Les données de session sérialisées passées à cette fonction de rappel doivent être
       stockées en utilisant l'identifiant de session fournie. Lors de la récupération
       de ces données, la fonction de rappel <parameter>read</parameter> doit retourner
       la valeur exacte, originalement passée à la fonction de rappel <parameter>write</parameter>.
      </para>
      <para>
       Cette fonction de rappel est invoquée lorsque PHP s'arrête ou explicitement
       lorsque la fonction <function>session_write_close</function> est appelée.
       Notez qu'après l'exécution de cette fonction, PHP exécutera en interne la
       fonction de rappel <parameter>close</parameter>.
       <note>
        <para>
         Le gestionnaire d'écriture n'est pas exécuté tant que le flux de sortie
         n'aura pas été fermé. Aussi, la sortie des requêtes de débogage
         du gestionnaire "write" ne sera jamais affichée dans le navigateur.
         Si la sortie de débogage est nécessaire, il est suggéré qu'elle soit
         plutôt orientée dans un fichier.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>destroy</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>destroy</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Cette fonction de rappel est exécutée lorsqu'une session est détruite
       avec la fonction <function>session_destroy</function> ou avec
       <function>session_regenerate_id</function> avec le paramètre de destruction définie
       à &true;. La valeur retournée doit être &true; en cas de succès, ou &false; si une
       erreur survient.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>gc</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>gc</replaceable></methodname>
        <methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       La fonction de rappel de ramasse miettes (garbage collector) est invoquée en interne par PHP
       périodiquement afin de purger les anciennes données de session. La fréquence
       est contrôlé par les options de configuration
       <link linkend="ini.session.gc-probability">session.gc_probability</link> et
       <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
       La valeur de la durée de vie passée à cette fonction de rappel peut être
       définie via l'option de configuration <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link>.
       La valeur retournée doit être &true; en cas de succès, ou &false; si une erreur survient.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>create_sid</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>string</type><methodname><replaceable>create_sid</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       Cette fonction de rappel est exécutée lorsqu'un nouvel ID de session
       est nécessaire. Aucun paramètre n'est fourni, et la valeur retournée doit
       être une chaîne de caractères qui est un ID de session valide pour votre
       gestionnaire.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>validate_sid</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Cette fonction de rappel est exécuté quand une session va démarrer, un ID
       de session est fournie et que
       <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link>
       est activé.
       <parameter>key</parameter> est l'ID de session à valider.
       Un ID de session est valide, si une session avec cet ID existe déjà.
       La valeur de retour devrait être &true; en cas de succès, &false; en cas
       d'échec.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>update_timestamp</parameter></term>
     <listitem>
      <para>
       Une fonction de rappel avec la signature suivante :
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>update_timestamp</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
        <methodparam><type>string</type><parameter>val</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Cette fonction de rappel est exécuté quand une session est mise à jour.
       <parameter>key</parameter> est l'ID de session, <parameter>val</parameter>
       sont les données de session.
       La valeur de retour devrait être &true; en cas de succès, &false; en cas
       d'échec.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Gestionnaire de session personnalisé : voir le code complet
     dans la documentation sur l'interface <classname>SessionHandlerInterface</classname>.
    </title>
    <para>
     Nous montrons juste l'invocation ici, l'exemple complet peut être vu dans
     la documentation de l'interface
     <classname>SessionHandlerInterface</classname>.
    </para>
    <para>
     Notez que nous utilisons ici le prototype orienté objet avec
     <function>session_set_save_handler</function> et enregistrons la fonction
     d'arrêt en utilisant le drapeau dans le paramètre de la fonction. C'est généralement
     préférable lors de l'enregistrement d'objets comme gestionnaires de sauvegarde de session.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
class MySessionHandler implements SessionHandlerInterface
{
    // implémentation de l'interface ici
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// processus pour définir et récupérer les valeurs par leurs clés depuis $_SESSION
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    Les gestionnaires d'écriture <parameter>write</parameter> et de fermeture
    <parameter>close</parameter> sont appelés après la destruction des objets,
    et donc, ne peuvent pas utiliser les objets ou lancer des exceptions.
    Les exceptions ne peuvent donc pas être attrapées ni affichées,
    et l'exécution ne fera que s'arrêter de façon innatendue.
   </para>
   <para>
    Il est possible d'appeler <function>session_write_close</function> depuis
    le destructeur pour résoudre ce problème mais la façon la plus élégante
    est d'enregistrer la fonction d'arrêt tel que décrit ci-dessus.
   </para>
  </warning>
  <warning>
   <para>
    Le dossier de travail courant change suivant les SAPIs si la session
    est fermée à la fin du script. Il est possible de fermer la session
    plus tard, grâce à la fonction <function>session_write_close</function>.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     La directive de configuration <link linkend="ini.session.save-handler">session.save_handler</link>
    </member>
    <member>
     La directive de configuration
     <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
    </member>
    <member><function>register_shutdown_function</function></member>
    <member><function>session_register_shutdown</function></member>
    <member>
     Se reporter à <link xlink:href="&url.session-save-handler;">save_handler.inc</link>
     pour une mise en œuvre procédurales complète 
    </member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- 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
-->