repo_zf1/documentation/manual/fr/module_specs/Zend_Loader-Autoloader.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.loader.autoloader">
    <title>L'autoloader</title>

    <para>
        <classname>Zend_Loader_Autoloader</classname> propose une solution intelligente et souple
        d'auto-chargement (autoload) pour Zend Framework. Il a été conçu pour remplir plusieurs
        objectifs:
    </para>

    <itemizedlist>
        <listitem><para>
            Proposer un autoloader à base d'espaces de noms. (Auparavant, les espaces de noms étaient
            intercéptés.)
        </para></listitem>

        <listitem><para>
            Proposer d'enregistrer des autoloads personnalisés, et les gérer comme une pile.
            (A l'heure actuelle, ceci permet de s'affranchir de certaines contraintes avec
            <code>spl_autoload</code>, qui ne permet pas le réenregistrement d'une fonction
            à base d'objet).
        </para></listitem>

        <listitem><para>
            Proposer un autoload optimisé pour les espaces de noms, qui permet une meilleure
            résolution des noms de classes.
        </para></listitem>
    </itemizedlist>

    <para>
        <classname>Zend_Loader_Autoloader</classname> est un singleton, il est donc
        universellement accessible. Ceci permet d'enregistrer des autoload depuis n'importe
        où dans votre code.
    </para>

    <sect2 id="zend.loader.autoloader.usage">
        <title>Utiler le chargeur automatique (autoloadeur)</title>

        <para>
            La première fois qu'une instance de l'autoloader est créee, il s'enregistre lui-même sur la
            fonction <code>spl_autoload</code>. Vous récupérez son instance via la méthode
            <code>getInstance()</code>:
        </para>

        <programlisting role="php"><![CDATA[
$autoloader = Zend_Loader_Autoloader::getInstance();
]]></programlisting>

        <para>
            Par défaut, l'autoloader est configurer pour capturer les espaces de noms "Zend_" et
            "ZendX_". Si votre propre librairie de code utilise un espace de noms différent, vous
            devez alors enregistrer celui-ci avec la méthode <code>registerNamespace()</code>.
            Par exemple, si votre librairie possède l'espace de noms "My_", vous devriez agir
            comme cela::
        </para>

        <programlisting role="php"><![CDATA[
$autoloader->registerNamespace('My_');
]]></programlisting>

        <note>
            <title>Préfixes des espaces de noms</title>

            <para>
                Notez que l'exemple précédent enregistre "My_" et non "My".
                Ceci car <classname>Zend_Loader_Autoloader</classname> est un autoloader
                global, et n'a aucune idée qu'un préfixe de classe possède un underscore.
                Si c'est <emphasis>votre </emphasis> cas, alors faites le apparaitre lors
                de son enregistrement dans l'autoloader.
            </para>
        </note>

        <para>
            Il est aussi possible que vous enregistriez vos propres fonctions d'autoload,
            optionnellement avec un espace de noms spécifique,
            <classname>Zend_Loader_Autoloader</classname> va alors tenter de l'utiliser lorsque
            nécessaire (lors de l'auto-chargement).
        </para>

        <para>
            Par exemple, vous pourriez avoir besoin d'un ou plusieurs composants eZcomponents
            avec votre application Zend Framework. Pour utiliser ses capacités d'autoload,
            ajoutez son autoloader à votre pile grâce à <code>pushAutoloader()</code>:
        </para>

        <programlisting role="php"><![CDATA[
$autoloader->pushAutoloader(array('ezcBase', 'autoload'), 'ezc');
]]></programlisting>

        <para>
            Ceci indique que les classes dont le nom commence par "ezc" devra utiliser cette
            fonction d'autoload.
        </para>

        <para>
            <code>unshiftAutoloader()</code>, elle, rajoute la méthode d'autoload au début de la pile.
        </para>

        <para>
            Par défaut, <classname>Zend_Loader_Autoloader</classname> ne supprime aucune erreur
            lorsqu'il utilise son autoloader interne, s'appuyant sur
            <classname>Zend_Loader::loadClass()</classname>. La plupart du temps, c'est le
            comportement recherché. Cependant, si vous voulez faire apparaitre les éventuelles
            erreurs de chargement, appelez alors <code>suppressNotFoundWarnings()</code>:
        </para>

        <programlisting role="php"><![CDATA[
$autoloader->suppressNotFoundWarnings(true);
]]></programlisting>

        <para>
            Enfin, il se peut que vous vouliez que l'autoloader par défaut charge toutes
            les classes de tous les espaces de noms. Par exemple, les librairies PEAR
            ne partagent pas un espace de noms commun, ce qui rend la tâche difficile
            si on veut associer chacun des espaces de noms internes. Utilisez alors
            <code>setFallbackAutoloader()</code> pour rendre l'autoloader "global"
            et charger tous les espaces de noms:
        </para>

        <programlisting role="php"><![CDATA[
$autoloader->setFallbackAutoloader(true);
]]></programlisting>
    </sect2>

    <sect2 id="zend.loader.autoloader.interface">
        <title>L'interface de l'autoloader</title>

        <para>
            Vous pouvez donc ajouter des fonctions de chargement par espace de noms, mais
            Zend Framework définit aussi une interface pour l'autoload,
            <classname>Zend_Loader_Autoloader_Interface</classname>:
        </para>

        <programlisting role="php"><![CDATA[
interface Zend_Loader_Autoloader_Interface
{
    public function autoload($class);
}
]]></programlisting>

        <para>
            L'utilisation de l'interface vous permet de passer un objet aux méthodes 
            <code>pushAutoloader()</code> et <code>unshiftAutoloader()</code> de
            <classname>Zend_Loader_Autoloader</classname>:
        </para>

        <programlisting role="php"><![CDATA[
// Foo_Autoloader implémente Zend_Loader_Autoloader_Interface:
$foo = new Foo_Autoloader();

$autoloader->pushAutoloader($foo, 'Foo_');
]]></programlisting>
    </sect2>

    <sect2 id="zend.loader.autoloader.reference">
        <title>Référence de l'autoloader</title>

        <para>
            Voici un guide des méthodes de <classname>Zend_Loader_Autoloader</classname>.
        </para>

        <table id="zend.loader.autoloader.reference.api">
            <title>Zend_Loader_Autoloader Methods</title>
            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>Méthode</entry>
                        <entry>Valeur de retour</entry>
                        <entry>Paramètres</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><code>getInstance()</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>N/A</entry>
                        <entry><para>
                            Retourne l'instance singleton de <classname>Zend_Loader_Autoloader</classname>
                            Au premier appel, enregistre l'autoloader avec <code>spl_autoload</code>.
                            Cette méthode est statique.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>resetInstance()</code></entry>
                        <entry><code>void</code></entry>
                        <entry>N/A</entry>
                        <entry><para>
                            Remet à zéro l'état interne de <classname>Zend_Loader_Autoloader</classname>
                            en désenregistrant les fonctions d'autoload éventuellement présentes, ainsi que
                            tous les espaces de noms.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>autoload($class)</code></entry>
                        <entry><code>string|false</code></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$class</code>, <emphasis>requis</emphasis>.
                                Une classe à charger.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Essaye de résoudre un nom de classe en fichier, et tente de la charger.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>setDefaultAutoloader($callback)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$callback</code>, <emphasis>requis</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Spécifie une fonction PHP à utiliser comme autoloader par défaut.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getDefaultAutoloader()</code></entry>
                        <entry><code>callback</code></entry>
                        <entry>N/A</entry>
                        <entry><para>
                            Retourne la fonction d'autoload par défaut, il s'agit par défaut de
                            <classname>Zend_Loader::loadClass()</classname>.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>setAutoloaders(array $autoloaders)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$autoloaders</code>, <emphasis>requis</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Passe une liste d'autoloaders (sous forme de noms
                            de fonctions PHP) à ajouter à la pile de ceux déja présents.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getAutoloaders()</code></entry>
                        <entry><code>array</code></entry>
                        <entry>N/A</entry>
                        <entry><para>
                            Récupère la pile d'autoloaders interne.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getNamespaceAutoloaders($namespace)</code></entry>
                        <entry><code>array</code></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$namespace</code>, <emphasis>requis</emphasis>
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Récupère tous les autoloaders qui sont associés à un certain
                            espace de noms.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>registerNamespace($namespace)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$namespace</code>, <emphasis>requis</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Enregistre un ou plusieurs espaces de noms, avec l'autoloader
                            par défaut. Si <code>$namespace</code> est une chaine, c'est cet
                            espace de noms qui sera enregistré, si c'est un tableau de chaines,
                            ils le seront tous.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>unregisterNamespace($namespace)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$namespace</code>, <emphasis>requis</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Désenregistre (supprime) un espace de noms depuis l'autoloader
                            par défaut. Si <code>$namespace</code> est une chaine, c'est cet
                            espace de noms qui sera désenregistré, si c'est un tableau de chaines,
                            ils le seront tous.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getRegisteredNamespace()</code></entry>
                        <entry><code>array</code></entry>
                        <entry>N/A</entry>
                        <entry><para>
                            Retourne un tableau comportant tous les espaces de noms enregistrés
                            avec l'autoloader par défaut.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>suppressNotFoundWarnings($flag = null)</code></entry>
                        <entry><code>boolean|Zend_Loader_Autoloader</code></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$flag</code>, <emphasis>optionnel</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Affecte ou récupère la valeur du paramètre indiquant si l'autoloader
                            par défaut doit supprimer les warnings "file not found". Si aucun argument
                            (ou null) lui est passé, il retourne sa valeur actuelle, dans le cas contraire,
                            il retournera l'instance de l'autoloader permettant le chainage des méthodes.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>setFallbackAutoloader($flag)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$flag</code>, <emphasis>requis</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Affecte la valeur du drapeau utilisé pour déterminer si l'autoloader par défaut
                            doit être utilisé comme "catch-all" pour charger tous les espaces de noms.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>isFallbackAutoloader()</code></entry>
                        <entry><code>boolean</code></entry>
                        <entry>N/A</entry>
                        <entry><para>
                            Retourne la valeur du drapeau utilisé pour déterminer si l'autoloader par défaut
                            doit être utilisé comme "catch-all" pour charger tous les espaces de noms.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getClassAutoloaders($class)</code></entry>
                        <entry><code>array</code></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$class</code>, <emphasis>requis</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Retourne une liste d'autoloaders d'espaces de noms qui pourraient
                            correspondre à la classe indiquée. Si aucun ne correspond, la liste de
                            tous les autoloaders globaux (non associés à des espaces de noms) sera
                            retournée.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>unshiftAutoloader($callback, $namespace = '')</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$callback</code>, <emphasis>requis</emphasis>.
                                Une fonction PHP valide.
                            </para></listitem>

                            <listitem><para>
                                <code>$namespace</code>, <emphasis>optionnel</emphasis>.
                                Une chaine représentant un préfixe de classe.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Ajoute un autoloader au début de la pile des autoloaders internes.
                            Si un espace de noms est fourni, il sera utilisé pour cet autoloader,
                            sinon l'autoloader sera global.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>pushAutoloader($callback, $namespace = '')</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$callback</code>, <emphasis>requis</emphasis>.
                                Une fonction PHP valide.
                            </para></listitem>

                            <listitem><para>
                                <code>$namespace</code>, <emphasis>optionnel</emphasis>.
                                Une chaine représentant un préfixe de classe.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Ajoute un autoloader à la fin de la pile des autoloaders internes.
                            Si un espace de noms est fourni, il sera utilisé pour cet autoloader,
                            sinon l'autoloader sera global.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>removeAutoloader($callback, $namespace = '')</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <code>$callback</code>, <emphasis>required</emphasis>.
                                Une fonction PHP valide.
                            </para></listitem>

                            <listitem><para>
                                <code>$namespace</code>, <emphasis>optional</emphasis>.
                                Une chaine représentant un préfixe de classe, ou un tableau
                                de chaines.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Supprime un autoloader de la pile interne. Si un espace de noms
                            est indiqué, supprime l'autoloader pour cet espace de noms uniquement.
                        </para></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>
</sect1>