repo_zf1/documentation/manual/fr/module_specs/Zend_Session-BasicUsage.xml

<!-- EN-Revision: 12759 -->
<sect1 id="zend.session.basic_usage">
    <title>Usage basique</title>

    <para>Les instances <classname>Zend_Session_Namespace</classname> fournissent l'API primaire pour manipuler les données de
    session dans Zend Framework. Les espaces de noms sont utilisés pour isoler toutes les données de session, bien
    qu'un espace de noms par défaut existe pour ceux qui veulent juste un endroit pour stocker toutes leurs données de
    session. <classname>Zend_Session</classname> utilise ext/session et sa superglobale spéciale <code>$_SESSION</code> comme
    mécanisme de stockage pour les données d'état de session. Bien que <code>$_SESSION</code> est toujours disponible
    dans l'espace global de PHP, les développeurs devraient s'abstenir d'accéder directement à elle, alors que
    <classname>Zend_Session</classname> et <classname>Zend_Session_Namespace</classname> fournissent plus efficacement et plus solidement
    leur suite de fonctionnalités liées à session.</para>

    <para>Chaque instance de <classname>Zend_Session_Namespace</classname> correspond à une entrée dans le tableau de la
    superglobale <code>$_SESSION</code>, où l'espace de noms est utilisée comme une clé. <programlisting
    role="php"><![CDATA[
$monNamespace = new Zend_Session_Namespace('monNamespace');

// $monNamespace corresponds to $_SESSION['monNamespace']
]]></programlisting> Il est possible d'utiliser
    <classname>Zend_Session</classname> conjointement avec d'autre code utilisant directement <code>$_SESSION</code>. Cependant,
    pour éviter les problèmes, il est fortement recommandé que ce code utilise seulement les parties de
    <code>$_SESSION</code> ne correspondant pas aux instances de <classname>Zend_Session_Namespace</classname>.</para>

    <sect2 id="zend.session.basic_usage.basic_examples">
        <title>Tutoriel d'exemples</title>

        <para>Si aucun espace de noms n'est spécifié lors de l'instanciation de <classname>Zend_Session_Namespace</classname>,
        toutes les données sont stockées de manière transparente dans un espace de noms appelé "<code>Default</code>".
        <classname>Zend_Session</classname> n'est pas prévu pour fonctionner directement sur le contenu des conteneurs des espaces
        de noms. Au lieu de cela, nous utilisons <classname>Zend_Session_Namespace</classname>. L'exemple ci-dessous montre
        l'utilisation de cet espace de noms par défaut, en montrant comment compter le nombre de fois qu'un utilisateur
        a vu une page sur le site Web. Pour tester cet exemple, ajouter le code suivant à votre fichier d'amorçage ZF
        :</para>

        <example id="zend.session.basic_usage.basic_examples.example.counting_page_views">
            <title>Compter le nombre de pages vues</title>

            <programlisting role="php"><![CDATA[
$defaultNamespace = new Zend_Session_Namespace('Default');

if (isset($defaultNamespace->numberOfPageRequests)) {
    $defaultNamespace->numberOfPageRequests++;
    // ceci s'incrémente à chaque chargement de page.
} else {
    $defaultNamespace->numberOfPageRequests = 1;
    // première page
}

echo "Page demandée lors de cette session : ",
     $defaultNamespace->numberOfPageRequests;
]]></programlisting>
        </example>

        <para>Quand de multiples modules utilisent des instances de <classname>Zend_Session_Namespace</classname> ayant différents
        espaces de noms, chaque module obtient une encapsulation pour ses propres données de session. Le constructeur de
        <classname>Zend_Session_Namespace</classname> peut recevoir un paramètre facultatif <code>$namespace</code>, qui permet
        aux développeurs la partition des données de session dans des espaces de noms séparés. Les espaces de noms
        fournissent une manière efficace et populaire de protéger un sous-ensemble de données de session contre un
        changement accidentel dû à des collisions de noms.</para>

        <para>Les noms des espaces de noms sont limités à des chaînes de caractères PHP non-vides qui ne commencent par
        un tiret-bas ("<code>_</code>"). De plus, seuls les composants coeur de Zend Framework devraient employer un nom
        d'espace de noms commençant par "<code>Zend</code>".</para>

        <example id="zend.session.basic_usage.basic_examples.example.namespaces.new">
            <title>Nouvelle méthode : les espaces de noms évitent les collisions</title>

            <programlisting role="php"><![CDATA[
// Dans le composant Zend_Auth
$authNamespace = new Zend_Session_Namespace('Zend_Auth');
$authNamespace->user = "monusername";

// Dans un composant service web
$webServiceNamespace = new Zend_Session_Namespace('Un_Service_Web');
$webServiceNamespace->user = "monwebusername";
]]></programlisting>
        </example>

        <para>L'exemple ci-dessus réalise la même chose que celui ci-dessous, excepté que les objets de session
        ci-dessus préserve l'encapsulation des données de session dans leur espace de noms respectif.</para>

        <example id="zend.session.basic_usage.basic_examples.example.namespaces.old">
            <title>Ancienne méthode : accès aux sessions PHP</title>

            <programlisting role="php"><![CDATA[
$_SESSION['Zend_Auth']['user'] = "monusername";
$_SESSION['Un_Service_Web']['user'] = "monwebusername";
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.session.basic_usage.iteration">
        <title>Énumérer les espaces de noms de session</title>

        <para><classname>Zend_Session_Namespace</classname> fournit une <ulink
        url="http://www.php.net/~helly/php/ext/spl/interfaceIteratorAggregate.html">interface IteratorAggregate</ulink>
        complète, incluant le support de l'instruction <code>foreach</code> :</para>

        <example id="zend.session.basic_usage.iteration.example">
            <title>Énumération des sessions</title>

            <programlisting role="php"><![CDATA[
$unNamespace =
    new Zend_Session_Namespace('un_namespace_avec_des_donnes_presentes');

foreach ($unNamespace as $index => $valeur) {
    echo "unNamespace->$index = '$valeur';\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.session.basic_usage.accessors">
        <title>Accesseurs pour les espaces de noms de session</title>

        <para><classname>Zend_Session_Namespace</classname> implémente <code>__get()</code>, <code>__set()</code>,
        <code>__isset()</code>, et <code>__unset()</code>. <ulink
        url="http://www.php.net/manual/fr/language.oop5.overloading.php">Les méthodes magiques</ulink> ne devraient pas
        être utilisées directement, excepté à l'intérieur d'une sous-classe. Au lieu de cela, utilisez les opérateurs
        normaux pour appeler ces méthodes magiques, comme :</para>

        <example id="zend.session.basic_usage.accessors.example">
            <title>Accéder aux données de session</title>

            <programlisting role="php"><![CDATA[
$namespace = new Zend_Session_Namespace();
// Espace de noms par défaut

$namespace->foo = 100;

echo "\$namespace->foo = $namespace->foo\n";

if (!isset($namespace->bar)) {
    echo "\$namespace->bar n'existe pas\n";
}

unset($namespace->foo);
]]></programlisting>
        </example>
    </sect2>
</sect1>