documentation/manual/fr/module_specs/Zend_Loader.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21818 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.loader.load">
   5     <title>Charger les fichiers et les classes dynamiquement</title>
   6
   7     <para>
   8         La classe <classname>Zend_Loader</classname> inclut des méthodes afin de vous aider à
   9         charger des fichiers dynamiquement.
  10     </para>
  11
  12     <tip>
  13         <title>Zend_Loader contre require_once()</title>
  14
  15         <para>
  16             Les méthodes <classname>Zend_Loader</classname> sont les meilleures à utiliser si
  17             le nom de fichier que vous devez charger est variable. Par exemple, s'il est basé sur un
  18             paramètre de la saisie de l'utilisateur ou un argument de méthode. Si vous chargez un
  19             fichier ou une classe dont le nom est constant, il n'y a aucun avantage à l'utilisation
  20             de <classname>Zend_Loader</classname> sur l'utilisation de fonctions de <acronym>PHP</acronym>
  21             traditionnelles comme <ulink
  22             url="http://php.net/require_once"><methodname>require_once()</methodname></ulink>.
  23         </para>
  24     </tip>
  25
  26     <sect2 id="zend.loader.load.file">
  27         <title>Charger des fichiers</title>
  28
  29         <para>
  30             La méthode statique <methodname>Zend_Loader::loadFile()</methodname> charge un
  31             fichier <acronym>PHP</acronym>, qui peut contenir du code <acronym>PHP</acronym> arbitraire. Cette méthode enveloppe la
  32             fonction <acronym>PHP</acronym> <ulink url="http://php.net/include"><methodname>include()</methodname></ulink>, et
  33             retournera le booléen <constant>FALSE</constant> si le fichier n'existe pas.
  34         </para>
  35
  36         <example id="zend.loader.file.example">
  37             <title>Exemple d'utilisation de la méthode loadFile()</title>
  38
  39             <programlisting language="php"><![CDATA[
  40 Zend_Loader::loadFile($filename, $dirs=null, $once=false);
  41 ]]></programlisting>
  42         </example>
  43
  44         <para>
  45             L'argument <varname>$filename</varname> définit le nom du fichier à charger, et il ne
  46             doit contenir aucune information concernant son chemin d'accès. Une vérification de
  47             sécurité est effectuée sur <varname>$filename</varname>. Le fichier <varname>$filename</varname> ne
  48             peut contenir que des caractères alphanumérique, des tirets ("-"), des tirets-bas ("_")
  49             ou des points ("."). Aucune de ces restrictions ne s'applique à l'argument
  50             <varname>$dirs</varname>.
  51         </para>
  52
  53         <para>
  54             L'argument <varname>$dirs</varname> définit les dossiers où rechercher le fichier. Si
  55             <constant>NULL</constant>, la recherche s'effectuera uniquement dans les dossiers définis par la
  56             variable <code>include_path</code>. Si c'est une chaîne ou un tableau, le ou les
  57             répertoires spécifiés seront scannés, ainsi que les dossiers définis par la variable
  58             <code>include_path</code>.
  59         </para>
  60
  61         <para>
  62             L'argument <varname>$once</varname> est un booléen. Si <constant>TRUE</constant>,
  63             <methodname>Zend_Loader::loadFile()</methodname> utilise la fonction <acronym>PHP</acronym> <ulink
  64             url="http://php.net/include"><methodname>include_once()</methodname></ulink> pour charger le fichier
  65             sinon la fonction <acronym>PHP</acronym> <ulink url="http://php.net/include"><methodname>include()</methodname></ulink>
  66             est utilisée.
  67         </para>
  68     </sect2>
  69
  70     <sect2 id="zend.loader.load.class">
  71         <title>Charger des classes</title>
  72
  73         <para>
  74             La méthode statique <methodname>Zend_Loader::loadClass($class, $dirs)</methodname>
  75             charge un fichier <acronym>PHP</acronym> et vérifie l'existence de la classe.
  76         </para>
  77
  78         <example id="zend.loader.load.class.example">
  79             <title>Exemple d'utilisation de la méthode loadClass()</title>
  80
  81             <programlisting language="php"><![CDATA[
  82 Zend_Loader::loadClass('Container_Tree',
  83     array(
  84         '/home/production/mylib',
  85         '/home/production/myapp'
  86     )
  87 );
  88 ]]></programlisting>
  89         </example>
  90
  91         <para>
  92             La chaîne spécifiant la classe est convertie en chemin relatif en remplaçant les
  93             tirets bas ("_") par le séparateur de dossier puis en ajoutant le bloc ".php". Dans
  94             l'exemple ci-dessus, "Container_Tree" devient "Container\\Tree.php".
  95         </para>
  96
  97         <para>
  98             Si <varname>$dirs</varname> est une chaîne ou un tableau,
  99             <methodname>Zend_Loader::loadClass()</methodname> va chercher dans les dossiers suivant
 100             l'ordre donné. Le premier fichier trouvé est chargé. Si le fichier n'existe pas dans les
 101             dossiers spécifiés <varname>$dirs</varname>, alors la recherche est effectuée dans
 102             <code>include_path</code> du <acronym>PHP</acronym>.
 103         </para>
 104
 105         <para>
 106             Si le fichier n'est pas trouvé ou que la classe n'existe pas après le chargement,
 107             <methodname>Zend_Loader::loadClass()</methodname> lèvera une exception
 108             <classname>Zend_Exception</classname>
 109         </para>
 110
 111         <para>
 112             <methodname>Zend_Loader::loadFile()</methodname> est utilisé pour le chargement,
 113             donc le nom de la classe ne peut contenir que des caractères alphanumériques et les
 114             caractères tiret ("-"), tiret bas ("_"), et point (".").
 115         </para>
 116         <note>
 117             <title>Loading Classes from PHP Namespaces</title>
 118
 119             <para>
 120                 Starting in version 1.10.0, Zend Framework now allows loading classes from PHP
 121                 namespaces. This support follows the same guidelines and implementation as that
 122                 found in the <ulink
 123                     url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
 124                 Framework Interop Group PSR-0</ulink> reference implementation.
 125             </para>
 126
 127             <para>
 128                 Under this guideline, the following rules apply:
 129             </para>
 130
 131             <itemizedlist>
 132                 <listitem>
 133                     <para>
 134                         Each namespace separator is converted to a
 135                         <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
 136                     </para>
 137                 </listitem>
 138
 139                 <listitem>
 140                     <para>
 141                         Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
 142                         <constant>DIRECTORY_SEPARATOR</constant>.  The "_" character has no special
 143                         meaning in the namespace.
 144                     </para>
 145                 </listitem>
 146
 147                 <listitem>
 148                     <para>
 149                         The fully-qualified namespace and class is suffixed with ".php" when loading
 150                         from the file system.
 151                     </para>
 152                 </listitem>
 153             </itemizedlist>
 154
 155             <para>
 156                 As examples:
 157             </para>
 158
 159             <itemizedlist>
 160                 <listitem>
 161                     <para>
 162                         <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
 163                         <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
 164                     </para>
 165                 </listitem>
 166
 167                 <listitem>
 168                     <para>
 169                         <classname>\namespace\package\Class_Name</classname> =&gt;
 170                         <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
 171                     </para>
 172                 </listitem>
 173
 174                 <listitem>
 175                     <para>
 176                         <classname>\namespace\package_name\Class_Name</classname> =&gt;
 177                         <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
 178                     </para>
 179                 </listitem>
 180             </itemizedlist>
 181         </note>
 182     </sect2>
 183
 184     <sect2 id="zend.loader.load.isreadable">
 185         <title>Tester si un fichier est lisible</title>
 186
 187         <para>
 188             La méthode statique <methodname>Zend_Loader::isReadable($pathname)</methodname>
 189             retourne <constant>TRUE</constant> si le fichier existe dans le dossier spécifié et qu'il est
 190             lisible, sinon <constant>FALSE</constant>.
 191         </para>
 192
 193         <example id="zend.loader.load.isreadable.example">
 194             <title>Exemple d'utilisation de la méthode isReadable()</title>
 195
 196             <programlisting language="php"><![CDATA[
 197 if (Zend_Loader::isReadable($filename)) {
 198     // puis manipulation avec $filename
 199 }
 200 ]]></programlisting>
 201         </example>
 202
 203         <para>
 204             L'argument <varname>$filename</varname> spécifie le nom du fichier à vérifier. Il peut
 205             contenir des informations concernant le chemin d'accès. Cette méthode enveloppe la
 206             fonction <acronym>PHP</acronym> <ulink url="http://php.net/is_readable"><methodname>is_readable()</methodname></ulink>.
 207             La fonction <acronym>PHP</acronym> ne recherche pas le fichier spécifié dans les répertoires de
 208             l'<code>include_path</code>, contrairement à
 209             <methodname>Zend_Loader::isReadable()</methodname>.
 210         </para>
 211     </sect2>
 212
 213     <sect2 id="zend.loader.load.autoload">
 214         <title>Utiliser l'autoloader</title>
 215
 216         <para>
 217             La classe Zend_Loader contient une méthode
 218             <methodname>Zend_Loader::autoload()</methodname> que vous pouvez inscrire dans le <acronym>PHP</acronym> SPL
 219             autoloader. Par commodité, <classname>Zend_Loader</classname> fournit la fonction
 220             <methodname>registerAutoload()</methodname> qui enregistre automatiquement sa méthode
 221             <methodname>autoload()</methodname>. Si l'extension <code>spl_autoload</code> n'est pas présente
 222             dans l'environnement <acronym>PHP</acronym>, alors la méthode <methodname>registerAutoload()</methodname> lèvera une
 223             <classname>Zend_Exception</classname>.
 224         </para>
 225
 226         <example id="zend.loader.load.autoload.example">
 227             <title>Exemple d'inscription de la méthode de callback autoloader</title>
 228
 229             <programlisting language="php"><![CDATA[
 230 Zend_Loader::registerAutoload();
 231 ]]></programlisting>
 232         </example>
 233
 234         <para>
 235             Après avoir inscrit le callback vers l'autoload de Zend Framework, vous pouvez
 236             appeler une classe de Zend Framework sans l'avoir explicitement chargé auparavant. La
 237             méthode autoload utilise automatiquement <methodname>Zend_Loader::loadClass()</methodname>
 238             quand vous appelez une classe.
 239         </para>
 240
 241         <para>
 242             Si vous avez étendu la classe <classname>Zend_Loader</classname>, vous pouvez
 243             passer un argument optionnel à <methodname>registerAutoload()</methodname>, pour spécifier la classe
 244             de laquelle vous souhaitez enregistrer la méthode <methodname>autoload()</methodname>.
 245         </para>
 246
 247         <example id="zend.loader.load.autoload.example-extended">
 248             <title>Exemple d'inscription de la méthode de callback autoloader d'une classe
 249             étendue</title>
 250
 251             <para>
 252                 A cause de la sémantique de référencement des fonctions statiques en <acronym>PHP</acronym>, vous
 253                 devez implémenter le code pour les méthodes <methodname>loadClass()</methodname> et
 254                 <methodname>autoload()</methodname>, et la méthode <methodname>autoload()</methodname> doit appeler
 255                 <methodname>self::loadClass()</methodname>. Si votre méthode <methodname>autoload()</methodname> délégue à
 256                 son parent l'appel <methodname>self::loadClass()</methodname>, alors cela appellerait la méthode
 257                 de même nom dans la classe parente et non dans la sous-classe.
 258             </para>
 259
 260             <programlisting language="php"><![CDATA[
 261 class Mon_Chargeur extends Zend_Loader
 262 {
 263     public static function loadClass($class, $dirs = null)
 264     {
 265         parent::loadClass($class, $dirs);
 266     }
 267
 268     public static function autoload($class)
 269     {
 270         try {
 271             self::loadClass($class);
 272             return $class;
 273         } catch (Exception $e) {
 274             return false;
 275         }
 276     }}
 277
 278 Zend_Loader::registerAutoload('Mon_Chargeur');
 279 ]]></programlisting>
 280         </example>
 281
 282         <para>
 283             Vous pouvez effacer un callback d'autoload. <methodname>registerAutoload()</methodname> a un
 284             paramètre optionnel, qui est réglé à <constant>TRUE</constant> par défaut. S'il vaut
 285             <constant>FALSE</constant>, le callback de l'autoload est alors effacé de la pile des autoload
 286             SPL.
 287         </para>
 288     </sect2>
 289 </sect1>