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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- 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&#160;:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Proposer un autoloader à base d'espaces de noms (auparavant, les espaces de
                noms étaient intercepté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>Utiliser le chargeur automatique (autoloader)</title>

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

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

        <para>
            Par défaut, l'autoloader est configuré 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 <methodname>registerNamespace()</methodname>. Par
            exemple, si votre librairie possède l'espace de noms "My_", vous devriez agir comme
            cela&#160;:
        </para>

        <programlisting language="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 apparaître 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 à <methodname>pushAutoloader()</methodname>&#160;:
        </para>

        <programlisting language="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>
            <methodname>unshiftAutoloader()</methodname>, 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
            <methodname>Zend_Loader::loadClass()</methodname>. La plupart du temps, c'est le
            comportement recherché. Cependant, si vous voulez faire apparaître les éventuelles
            erreurs de chargement, appelez alors <methodname>suppressNotFoundWarnings()</methodname>&#160;:
        </para>

        <programlisting language="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 <methodname>setFallbackAutoloader()</methodname> pour
            rendre l'autoloader "global" et charger tous les espaces de noms&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setFallbackAutoloader(true);
]]></programlisting>
        <note>
            <title>Loading Classes from PHP Namespaces</title>

            <para>
                Starting in version 1.10.0, Zend Framework now allows loading classes from PHP
                namespaces. This support follows the same guidelines and implementation as that
                found in the <ulink
                    url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
                Framework Interop Group PSR-0</ulink> reference implementation.
            </para>

            <para>
                Under this guideline, the following rules apply:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        Each namespace separator is converted to a
                        <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
                        <constant>DIRECTORY_SEPARATOR</constant>.  The "_" character has no special
                        meaning in the namespace.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        The fully-qualified namespace and class is suffixed with ".php" when loading
                        from the file system.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                As examples:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package_name\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
                    </para>
                </listitem>
            </itemizedlist>
        </note>
    </sect2>

    <sect2 id="zend.loader.autoloader.zf-version">
        <title>Selecting a Zend Framework version</title>

        <para>
            Typically, you will use the version of Zend Framework that the autoloader you
            instantiate came with. However, when developing a project, it's often useful to track
            specific versions, major or minor branches, or just the latest version.
            <classname>Zend_Loader_Autoloader</classname>, as of version 1.10, offers some features
            to help manage this task.
        </para>

        <para>
            Imagine the following scenario:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    During <emphasis>development</emphasis>, you want to track the latest version of
                    Zend Framework you have installed, so that you can ensure the application works
                    when you upgrade between versions.
                </para>

                <para>
                    When pushing to <emphasis>Quality Assurance</emphasis>, however, you need to
                    have slightly more stability, so you want to use the latest installed revision
                    of a specific minor version.
                </para>

                <para>
                    Finally, when you push to <emphasis>production</emphasis>, you want to pin to a
                    specific installed version, to ensure no breakage occurs if or when you add new
                    versions of Zend Framework to you server.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            The autoloader allows you to do this with the method
            <methodname>setZfPath()</methodname>. This method takes two arguments, a
            <emphasis>path</emphasis> to a set of Zend Framework installations, and a
            <emphasis>version</emphasis> to use. Once invoked, it prepends a path to the
            <constant>include_path</constant> pointing to the appropriate Zend Framework
            installation library.
        </para>

        <para>
            The directory you specify as your <emphasis>path</emphasis> should have a tree such as
            the following:
        </para>

        <programlisting language="text"><![CDATA[
ZendFramework/
|-- 1.9.2/
|   |-- library/
|-- ZendFramework-1.9.1-minimal/
|   |-- library/
|-- 1.8.4PL1/
|   |-- library/
|-- 1.8.4/
|   |-- library/
|-- ZendFramework-1.8.3/
|   |-- library/
|-- 1.7.8/
|   |-- library/
|-- 1.7.7/
|   |-- library/
|-- 1.7.6/
|   |-- library/
]]></programlisting>

        <para>
            (where <emphasis>path</emphasis> points to the directory "ZendFramework" in the above
            example)
        </para>

        <para>
            Note that each subdirectory should contain the directory <filename>library</filename>,
            which contains the actual Zend Framework library code. The individual subdirectory names
            may be version numbers, or simply be the untarred contents of a standard Zend Framework
            distribution tarball/zipfile.
        </para>

        <para>
            Now, let's address the use cases. In the first use case, in
            <emphasis>development</emphasis>, we want to track the latest source install. We can do
            that by passing "latest" as the version:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setZfPath($path, 'latest');
]]></programlisting>

        <para>
            In the example from above, this will map to the directory
            <filename>ZendFramework/1.9.2/library/</filename>; you can verify this by checking the
            return value of <methodname>getZfPath()</methodname>.
        </para>

        <para>
            In the second situation, for <emphasis>quality assurance</emphasis>, let's say we want
            to pin to the 1.8 minor release, using the latest install you have for that release. You
            can do so as follows:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setZfPath($path, '1.8');
]]></programlisting>

        <para>
            In this case, it will find the directory
            <filename>ZendFramework/1.8.4PL1/library/</filename>.
        </para>

        <para>
            In the final case, for <emphasis>production</emphasis>, we'll pin to a specific version
            -- 1.7.7, since that was what was available when Quality Assurance tested prior to our
            release.
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setZfPath($path, '1.7.7');
]]></programlisting>

        <para>
            Predictably, it finds the directory <filename>ZendFramework/1.7.7/library/</filename>.
        </para>

        <para>
            You can also specify these values in the configuration file you use with
            <filename>Zend_Application</filename>. To do so, you'd specify the following
            information:
        </para>

        <programlisting language="ini"><![CDATA[
[production]
autoloaderZfPath = "path/to/ZendFramework"
autoloaderZfVersion = "1.7.7"

[qa]
autoloaderZfVersion = "1.8"

[development]
autoloaderZfVersion = "latest"
]]></programlisting>

        <para>
            Note the different environment sections, and the different version specified in each
            environment; these factors will allow <classname>Zend_Application</classname> to
            configure the autoloader appropriately.
        </para>

        <warning>
            <title>Performance implications</title>

            <para>
                For best performance, either do not use this feature, or specify a specific Zend
                Framework version (i.e., not "latest", a major revision such as "1", or a minor
                revision such as "1.8"). Otherwise, the autoloader will need to scan the provided
                path for directories matching the criteria -- a somewhat expensive operation to
                perform on each request.
            </para>
        </warning>
    </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>&#160;:
        </para>

        <programlisting language="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
            <methodname>pushAutoloader()</methodname> et <methodname>unshiftAutoloader()</methodname> de
            <classname>Zend_Loader_Autoloader</classname>&#160;:
        </para>

        <programlisting language="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>Méthodes de Zend_Loader_Autoloader</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><methodname>getInstance()</methodname></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><methodname>resetInstance()</methodname></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><methodname>autoload($class)</methodname></entry>
                        <entry><code>string|false</code></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$class</varname>, <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><methodname>setDefaultAutoloader($callback)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>,
                                        <emphasis>requis</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>
                        <entry>
                            <para>
                                Spécifie une fonction <acronym>PHP</acronym> à utiliser comme autoloader par défaut.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getDefaultAutoloader()</methodname></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 <methodname>Zend_Loader::loadClass()</methodname>.
                            </para>
                        </entry>
                    </row>

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

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

                    <row>
                        <entry><methodname>getNamespaceAutoloaders($namespace)</methodname></entry>
                        <entry><type>Array</type></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <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><methodname>registerNamespace($namespace)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <emphasis>requis</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>
                        <entry>
                            <para>
                                Enregistre un ou plusieurs espaces de noms, avec
                                l'autoloader par défaut. Si <varname>$namespace</varname> est une chaîne,
                                c'est cet espace de noms qui sera enregistré, si c'est un tableau de
                                chaînes, ils le seront tous.
                            </para>
                        </entry>
                    </row>

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

                    <row>
                        <entry><methodname>getRegisteredNamespaces()</methodname></entry>
                        <entry><type>Array</type></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><methodname>suppressNotFoundWarnings($flag = null)</methodname></entry>
                        <entry><code>boolean|Zend_Loader_Autoloader</code></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para><varname>$flag</varname>, <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><methodname>setFallbackAutoloader($flag)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para><varname>$flag</varname>, <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><methodname>isFallbackAutoloader()</methodname></entry>
                        <entry><type>Boolean</type></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><methodname>getClassAutoloaders($class)</methodname></entry>
                        <entry><type>Array</type></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para><varname>$class</varname>, <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><methodname>unshiftAutoloader($callback, $namespace = '')</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>requis</emphasis>. Une
                                        fonction <acronym>PHP</acronym> valide.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>, <emphasis>optionnel</emphasis>.
                                        Une chaîne 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><methodname>pushAutoloader($callback, $namespace = '')</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>requis</emphasis>. Une
                                        fonction <acronym>PHP</acronym> valide.
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>, <emphasis>optionnel</emphasis>.
                                        Une chaîne 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><methodname>removeAutoloader($callback, $namespace = '')</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>requis</emphasis>. Une
                                        fonction <acronym>PHP</acronym> valide.
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>, <emphasis>optionnel</emphasis>.
                                        Une chaîne représentant un préfixe de classe, ou un tableau
                                        de chaînes.
                                    </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>