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

<!-- EN-Revision: 12819 -->
<sect1 id="zend.loader.load">
    <title>Charger les fichiers et les classes dynamiquement</title>

    <para>La classe <classname>Zend_Loader</classname> inclut des méthodes afin de vous aider à charger des fichiers
    dynamiquement.</para>

    <tip>
        <title>Zend_Loader contre require_once()</title>

        <para>Les méthodes <classname>Zend_Loader</classname> sont les meilleures à utiliser si le nom de fichier que vous devez
        charger est variable. Par exemple, s'il est basé sur un paramètre de la saisie de l'utilisateur ou un argument
        de méthode. Si vous chargez un fichier ou une classe dont le nom est constant, il n'y a aucun avantage à
        l'utilisation de <classname>Zend_Loader</classname> sur l'utilisation de fonctions de PHP traditionnelles comme <ulink
        url="http://php.net/require_once"><code>require_once()</code></ulink>.</para>
    </tip>

    <sect2 id="zend.loader.load.file">
        <title>Charger des fichiers</title>

        <para>La méthode statique <classname>Zend_Loader::loadFile()</classname> charge un fichier PHP, qui peut contenir du code
        PHP arbitraire. Cette méthode enveloppe la fonction PHP <ulink
        url="http://php.net/include"><code>include()</code></ulink>, et retournera le booléen <code>false</code>
        si le fichier n'existe pas.</para>

        <example id="zend.loader.file.example">
            <title>Exemple d'utilisation de la méthode loadFile()</title>

            <programlisting role="php"><![CDATA[
Zend_Loader::loadFile($filename, $dirs=null, $once=false);
]]></programlisting>
        </example>

        <para>L'argument <code>$filename</code> définit le nom du fichier à charger, et il ne doit contenir aucune
        information concernant son chemin d'accès. Une vérification de sécurité est effectuée sur
        <code>$filename</code>. Le fichier <code>$filename</code> ne peut contenir que des caractères alphanumérique,
        des tirets ("-"), des tirets-bas ("_") ou des points ("."). Aucune de ces restrictions ne s'applique à
        l'argument <code>$dirs</code>.</para>

        <para>L'argument <code>$dirs</code> définit les dossiers où rechercher le fichier. Si <code>NULL</code>, la
        recherche s'effectuera uniquement dans les dossiers définis par la variable <code>include_path</code>. Si c'est
        une chaîne ou un tableau, le ou les répertoires spécifiés seront scannés, ainsi que les dossiers définis par la
        variable <code>include_path</code>.</para>

        <para>L'argument <code>$once</code> est un booléen. Si <code>true</code>, <classname>Zend_Loader::loadFile()</classname>
        utilise la fonction PHP <ulink url="http://php.net/include"><code>include_once()</code></ulink> pour charger le
        fichier sinon la fonction PHP <ulink url="http://php.net/include"><code>include()</code></ulink> est
        utilisée.</para>
    </sect2>

    <sect2 id="zend.loader.load.class">
        <title>Charger des classes</title>

        <para>La méthode statique <classname>Zend_Loader::loadClass($class, $dirs)</classname> charge un fichier PHP et vérifie
        l'existence de la classe.</para>

        <example id="zend.loader.load.class.example">
            <title>Exemple d'utilisation de la méthode loadClass()</title>

            <programlisting role="php"><![CDATA[
Zend_Loader::loadClass('Container_Tree',
    array(
        '/home/production/mylib',
        '/home/production/myapp'
    )
);
]]></programlisting>
        </example>

        <para>La chaîne spécifiant la classe est convertie en chemin relatif en remplaçant les tirets bas ("_") par le
        séparateur de dossier puis en ajoutant le bloc ".php". Dans l'exemple ci-dessus, "Container_Tree" devient
        "Container/Tree.php".</para>

        <para>Si <code>$dirs</code> est une chaîne ou un tableau, <classname>Zend_Loader::loadClass()</classname> va chercher dans
        les dossiers suivant l'ordre donné. Le premier fichier trouvé est chargé. Si le fichier n'existe pas dans les
        dossiers spécifiés <code>$dirs</code>, alors la recherche est effectuée dans <code>include_path</code> du
        PHP.</para>

        <para>Si le fichier n'est pas trouvé ou que la classe n'existe pas après le chargement,
        <classname>Zend_Loader::loadClass()</classname> lèvera une exception <classname>Zend_Exception</classname></para>

        <para><classname>Zend_Loader::loadFile()</classname> est utilisé pour le chargement, donc le nom de la classe ne peut
        contenir que des caractères alphanumériques et les caractères tiret ("-"), tiret bas ("_"), et point
        (".").</para>
    </sect2>

    <sect2 id="zend.loader.load.isreadable">
        <title>Tester si un fichier est lisible</title>

        <para>La méthode statique <classname>Zend_Loader::isReadable($pathname)</classname> retourne <code>true</code> si le
        fichier existe dans le dossier spécifié et qu'il est lisible, sinon <code>false</code>.</para>

        <example id="zend.loader.load.isreadable.example">
            <title>Exemple d'utilisation de la méthode isReadable()</title>

            <programlisting role="php"><![CDATA[
if (Zend_Loader::isReadable($filename)) {
    // puis manipulation avec $filename
}
]]></programlisting>
        </example>

        <para>L'argument <code>$filename</code> spécifie le nom du fichier à vérifier. Il peut contenir des informations
        concernant le chemin d'accès. Cette méthode enveloppe la fonction PHP <ulink
        url="http://php.net/is_readable"><code>is_readable()</code></ulink>. La fonction PHP ne recherche pas le fichier
        spécifié dans les répertoires de l'<code>include_path</code>, contrairement à
        <classname>Zend_Loader::isReadable()</classname>.</para>
    </sect2>

    <sect2 id="zend.loader.load.autoload">
        <title>Utiliser l'autoloader</title>

        <para>La classe Zend_Loader contient une méthode <classname>Zend_Loader::autoload()</classname> que vous pouvez inscrire
        dans le PHP SPL autoloader. Par commodité, <classname>Zend_Loader</classname> fournit la fonction
        <code>registerAutoload()</code> qui enregistre automatiquement sa méthode <code>autoload()</code>. Si
        l'extension <code>spl_autoload</code> n'est pas présente dans l'environnement PHP, alors la méthode
        <code>registerAutoload()</code> lèvera une <classname>Zend_Exception</classname>.</para>

        <example id="zend.loader.load.autoload.example">
            <title>Exemple d'inscription de la méthode de callback autoloader</title>

            <programlisting role="php"><![CDATA[
Zend_Loader::registerAutoload();
]]></programlisting>
        </example>

        <para>Après avoir inscrit le callback vers l'autoload de Zend Framework, vous pouvez appeler une classe de Zend
        Framework sans l'avoir explicitement chargé auparavant. La méthode autoload utilise automatiquement
        <classname>Zend_Loader::loadClass()</classname> quand vous appelez une classe.</para>

        <para>Si vous avez étendu la classe <classname>Zend_Loader</classname>, vous pouvez passer un argument optionnel à
        <code>registerAutoload()</code>, pour spécifier la classe de laquelle vous souhaitez enregistrer la méthode
        <code>autoload()</code>.</para>

        <example id="zend.loader.load.autoload.example-extended">
            <title>Exemple d'inscription de la méthode de callback autoloader d'une classe étendue</title>

            <para>A cause de la sémantique de référencement des fonctions statiques en PHP, vous devez implémenter le
            code pour les méthodes <code>loadClass()</code> et <code>autoload()</code>, et la méthode
            <code>autoload()</code> doit appeler <code>self::loadClass()</code>. Si votre méthode
            <code>autoload()</code> délégue à son parent l'appel <code>self::loadClass()</code>, alors cela appellerait
            la méthode de même nom dans la classe parente et non dans la sous-classe.</para>

            <programlisting role="php"><![CDATA[
class Mon_Chargeur extends Zend_Loader
{
    public static function loadClass($class, $dirs = null)
    {
        parent::loadClass($class, $dirs);
    }

    public static function autoload($class)
    {
        try {
            self::loadClass($class);
            return $class;
        } catch (Exception $e) {
            return false;
        }
    }}

Zend_Loader::registerAutoload('Mon_Chargeur');
]]></programlisting>
        </example>

        <para>Vous pouvez effacer un callback d'autoload. <code>registerAutoload()</code> a un paramètre optionnel, qui
        est réglé à <code>true</code> par défaut. S'il vaut <code>false</code>, le callback de l'autoload est alors
        effacé de la pile des autoload SPL.</para>
    </sect2>
</sect1>