repo_zf1/documentation/manual/fr/module_specs/Zend_Registry.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.registry.using">
    <title>Utiliser le registre</title>

    <para>
        Un registre est un conteneur pour stocker des objets et des valeurs dans l'espace
        d'application. En stockant la valeur dans le registre, le même objet est toujours disponible
        partout dans votre application. Ce mécanisme est une alternative à l'utilisation du stockage
        global.
    </para>

    <para>
        L'utilisation typique des registres dans Zend Framework est par des méthodes statiques
        dans la classe <classname>Zend_Registry</classname>. Alternativement, la classe est un
        tableau, donc vous pouvez avoir accès aux éléments stockés avec une interface semblable au
        tableau.
    </para>

    <sect2 id="zend.registry.using.storing">
        <title>Mettre des valeurs dans le registre</title>

        <para>
            Pour enregistrer une valeur dans le registre, il faut utiliser la méthode statique
            <methodname>set()</methodname>.
        </para>

        <example id="zend.registry.using.storing.example">
            <title>Exemple avec la méthode <methodname>set()</methodname></title>

            <programlisting language="php"><![CDATA[
Zend_Registry::set('index', $value);
]]></programlisting>
        </example>

        <para>
            La valeur peut être un objet, un tableau, ou un scalaire. Vous pouvez changer la
            valeur stockée dans une entrée spécifique du registre en utilisant <methodname>set()</methodname>
            pour enregistrer une nouvelle valeur.
        </para>

        <para>
            L'index peut être un scalaire (<constant>NULL</constant>, chaîne, ou nombre), comme un
            tableau ordinaire.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.retrieving">
        <title>Lire des valeurs du registre</title>

        <para>
            Pour récupérer une entrée dans le registre,il faut utiliser la méthode statique
            <methodname>get()</methodname>.
        </para>

        <example id="zend.registry.using.retrieving.example">
            <title>Exemple avec la méthode <methodname>get()</methodname></title>

            <programlisting language="php"><![CDATA[
$value = Zend_Registry::get('index');
]]></programlisting>
        </example>

        <para>
            La méthode <methodname>getInstance()</methodname> retourne l'objet registre en entier. Un
            objet registre est itératif, rendant les valeurs stockées facilement accessibles.
        </para>

        <example id="zend.registry.using.retrieving.example-iterating">
            <title>Exemple d'itération du registre</title>

            <programlisting language="php"><![CDATA[
$registry = Zend_Registry::getInstance();

foreach ($registry as $index => $value) {
    echo "Le registre index $index contient :\n";
    var_dump($value);
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.constructing">
        <title>Construire un objet registre</title>

        <para>
            En plus de pouvoir accéder au registre grâce aux méthodes statiques, vous pous
            pouvez créer une instance directement et l'utiliser en tant qu'objet.
        </para>

        <para>
            L'instance du registre à laquelle vous avez accès par les méthodes statiques est
            simplement une instance et il est plus commode qu'il soit stocké statiquement, afin d'y
            avoir accès partout dans votre application.
        </para>

        <para>
            Utiliser le constructeur traditionnel <emphasis>new</emphasis> pour créer une instance du
            registre. Ceci vous donne la possibilité d'initialiser les entrées du registre avec un
            tableau associatif.
        </para>

        <example id="zend.registry.using.constructing.example">
            <title>Exemple de construction d'un registre</title>

            <programlisting language="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));
]]></programlisting>
        </example>

        <para>
            Après avoir construit cette instance, vous pouvez l'utiliser avec les fonctions
            habituelles de tableau, ou vous pouvez rendre cette instance statique en utilisant la
            méthode <methodname>setInstance()</methodname>.
        </para>

        <example id="zend.registry.using.constructing.example-setinstance">
            <title>Exemple d'initialisation d'un registre statique</title>

            <programlisting language="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));

Zend_Registry::setInstance($registry);
]]></programlisting>
        </example>

        <para>
            La méthode <methodname>setInstance()</methodname> lèvera une
            <classname>Zend_Exception</classname> si un registre statique a déjà été initialisé lors
            de son premier accès.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.array-access">
        <title>Accéder au registre comme à un tableau</title>

        <para>
            Si vous avez plusieurs valeurs à récupérer ou à enregistrer, vous pouvez trouver
            intéressant d'avoir accès au registre avec une notation de type tableau.
        </para>

        <example id="zend.registry.using.array-access.example">
            <title>Exemple d'accès de type tableau</title>

            <programlisting language="php"><![CDATA[
$registry = Zend_Registry::getInstance();

$registry['index'] = $value;

var_dump( $registry['index'] );
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.array-object">
        <title>Accéder au registre comme à un objet</title>

        <para>
            Vous pouvez trouver aussi intéressant d'accéder au registre d'une manière orientée
            objet en utilisant les noms d'index comme des propriétés d'objet. Pour cela, vous devez
            spécifier au constructeur du registre l'option <constant>ArrayObject::ARRAY_AS_PROPS</constant>
            et initialiser l'instance statique. Vous devez faire ceci avant d'accéder au registre
            statique. <emphasis>Attention</emphasis> en utilisant cette option, puisque certaines
            versions de <acronym>PHP</acronym> ont des bugs quand il utilise le registre avec cette option.
        </para>

        <warning>
            <title>Problèmes connus avec l'option
            <constant>ArrayObject::ARRAY_AS_PROPS</constant></title>

            <para>
                Certaines versions de <acronym>PHP</acronym> sont réputées buggués lors de l'utilisation de
                l'option de registre <constant>ArrayObject::ARRAY_AS_PROPS</constant>.
            </para>
        </warning>

        <example id="zend.registry.using.array-object.example">
            <title>Exemple d'accès de type objet</title>

            <programlisting language="php"><![CDATA[
// Dans votre fichier de lancement de l'application
$registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS)
Zend_Registry::setInstance($registry);
$registry->tree='apple';

// Ailleurs dans l'application
$registry = Zend_Registry::getInstance();

echo $registry->tree; // affiche 'apple'
$registry->index = $value;

var_dump($registry->index);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.isset">
        <title>Vérifier si un index existe</title>

        <para>
            Pour savoir si un index particulier du registre a une valeur, il faut utiliser la
            méthode statique <methodname>isRegistered()</methodname>.
        </para>

        <example id="zend.registry.using.isset.example-isregistered">
            <title>Exemple avec la méthode i<methodname>sRegistered()</methodname></title>

            <programlisting language="php"><![CDATA[
if (Zend_Registry::isRegistered($index)) {
    $value = Zend_Registry::get($index);
}
]]></programlisting>
        </example>

        <para>
            Pour savoir si un index particulier du registre de type tableau a une valeur, il
            faut utiliser la fonction <methodname>isset()</methodname> comme vous le feriez avec un tableau
            ordinaire.
        </para>

        <example id="zend.registry.using.isset.example-isset">
            <title>Exemple avec la méthode <methodname>isset()</methodname></title>

            <programlisting language="php"><![CDATA[
$registry = Zend_Registry::getInstance();

// En utilisant la syntaxe de type tableau
if (isset($registry['index'])) {
    var_dump( $registry['index'] );
}

// En utilisant la syntaxe de type objet, si activé
if (isset($registry->index)) {
    var_dump( $registry->index );
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.subclassing">
        <title>Étendre le registre</title>

        <para>
            Le registre statique est une instance de la classe
            <classname>Zend_Registry</classname>. Si vous voulez ajouter une fonctionnalité au
            registre, vous pouvez créer une classe qui étend <classname>Zend_Registry</classname> et
            ensuite vous pouvez spécifier cette classe comme la classe à utiliser pour le registre
            statique. Utilisez la méthode statique <methodname>setClassName()</methodname> pour spécifier la
            classe.
        </para>

        <note>
            <para>La classe doit étendre <classname>Zend_Registry</classname>.</para>
        </note>

        <example id="zend.registry.using.subclassing.example">
            <title>Exemple d'affectation d'un nom de classe au registre</title>

            <programlisting language="php"><![CDATA[
Zend_Registry::setClassName('Mon_Registre');

Zend_Registry::set('index', $value);
]]></programlisting>
        </example>

        <para>
            L'enregistrement lève une <classname>Zend_Exception</classname> si vous essayez
            d'affecter un nom de classe après que le registre ait eu un premier accès. Il est
            recommandé de spécifier le nom de classe pour votre registre statique dans le fichier de
            lancement de votre application.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.unsetting">
        <title>Décharger le registre statique</title>

        <para>
            Bien que ce ne soit pas normalement nécessaire, vous pouvez décharger l'instance
            de votre registre. Utilisez la méthode statique <methodname>_unsetInstance()</methodname>.
        </para>

        <note>
            <title>Risque de perte de données</title>

            <para>
                Quand vous utilisez le code <methodname>_unsetInstance()</methodname>, toutes les données
                dans le registre statique sont perdues et ne peuvent pas être récupérées.
            </para>
        </note>

        <para>
            Vous pourriez utiliser cette méthode, par exemple, si vous voulez utiliser
            <methodname>setInstance()</methodname> ou <methodname>setClassName()</methodname> après que l'objet de registre
            statique a été initialisé. Décharger l'instance statique vous permet d'utiliser ces
            méthodes même après instanciation de l'objet registre. Utiliser
            <classname>Zend_Registry</classname> de cette manière n'est pas recommandé dans les
            applications.
        </para>

        <example id="zend.registry.using.unsetting.example">
            <title>Exemple avec la méthode <methodname>_unsetInstance()</methodname></title>

            <programlisting language="php"><![CDATA[
Zend_Registry::set('index', $value);

Zend_Registry::_unsetInstance();

// Changer la classe
Zend_Registry::setClassName('Mon_Registre');

Zend_Registry::set('index', $value);
]]></programlisting>
        </example>
    </sect2>
</sect1>