documentation/manual/es/module_specs/Zend_Loader.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20243 -->
   3     <!-- Reviewed: no -->
   4 <sect1 id="zend.loader.load">
   5
   6     <title>Cargando archivos y clases dinámicamente</title>
   7
   8     <para> La clase <classname>Zend_Loader</classname> incluye métodos para
   9         ayudar a cargar archivos dinámicamente. </para>
  10
  11     <tip>
  12         <title>Zend_Loader vs. require_once()</title>
  13         <para> Los métodos de <classname>Zend_Loader</classname> tienen más
  14             utilidad si el nombre de archivo que necesita cargar es variable.
  15             Por ejemplo, si éste se basa en un parametro de entrada del usuario
  16             o argumento de un método. Si carga un archivo o clase cuyo nombre es
  17             constante, no hay ningún beneficio al usar
  18                 <classname>Zend_Loader</classname> sobre el uso de funciones
  19             tradicionales de <acronym>PHP</acronym> como <ulink
  20                 url="http://php.net/require_once">
  21                 <methodname>require_once()</methodname>
  22             </ulink> . </para>
  23     </tip>
  24
  25     <sect2 id="zend.loader.load.file">
  26
  27         <title>Cargando Archivos</title>
  28
  29         <para> El método estático
  30                 <methodname>Zend_Loader::loadFile()</methodname> carga un
  31             archivo <acronym>PHP</acronym> . El archivo cargado puede contener
  32             cualquier código <acronym>PHP</acronym> . El método se comporta como
  33             un envoltorio para la función <acronym>PHP</acronym>
  34             <ulink url="http://php.net/include">
  35                 <methodname>include()</methodname>
  36             </ulink> . Este método devuelve un booleano
  37                 <constant>FALSE</constant> en caso de fallo, por ejemplo, si el
  38             archivo especificado no existe. </para>
  39
  40         <example id="zend.loader.load.file.example">
  41             <title>Ejemplo del Método loadFile()</title>
  42             <programlisting language="php"><![CDATA[
  43 Zend_Loader::loadFile($filename, $dirs=null, $once=false);
  44 ]]></programlisting>
  45         </example>
  46
  47         <para> El argumento <varname>$filename</varname> especifica el archivo
  48             que se va a cargar, el cual no debe contener ninguna información de
  49             rutas. Una verificación de seguridad es efectuada sobre
  50                 <varname>$filename</varname> . El archivo
  51                 <varname>$filename</varname> sólo puede contener caracteres
  52             alfanuméricos, guiones ("-"), barras bajas ("_"), o puntos ("."). No
  53             hay ninguna restricción en el argumento <varname>$dirs</varname> . </para>
  54
  55         <para> El parámetro <varname>$dirs</varname> especifica en qué carpetas
  56             buscar el archivo. Si el valor es <constant>NULL</constant> , sólo
  57             se buscará en el <methodname>include_path</methodname> ; si el valor
  58             es un string o un array, se buscará en la carpeta o carpetas
  59             especificadas , seguidas del <methodname>include_path</methodname> . </para>
  60
  61         <para> El argumento <varname>$once</varname> es un booleano. Si es
  62                 <constant>TRUE</constant> ,
  63                 <methodname>Zend_Loader::loadFile()</methodname> esa la función
  64                 <acronym>PHP</acronym>
  65             <ulink url="http://php.net/include">
  66                 <methodname>include_once()</methodname>
  67             </ulink> para cargar el archivo, de lo contrario se utiliza la
  68             función <acronym>PHP</acronym>
  69             <ulink url="http://php.net/include_once">
  70                 <methodname>include()</methodname>
  71             </ulink> . </para>
  72
  73     </sect2>
  74
  75     <sect2 id="zend.loader.load.class">
  76
  77         <title>Cargando Clases</title>
  78
  79         <para> El método estático <methodname>Zend_Loader::loadClass($class,
  80                 $dirs)</methodname> carga un archivo <acronym>PHP</acronym> y
  81             comprueba la existencia de la clase. </para>
  82
  83         <example id="zend.loader.load.class.example">
  84             <title>Ejemplo del método loadClass()</title>
  85             <programlisting language="php"><![CDATA[
  86 Zend_Loader::loadClass('Container_Tree',
  87     array(
  88         '/home/production/mylib',
  89         '/home/production/myapp'
  90     )
  91 );
  92 ]]></programlisting>
  93         </example>
  94
  95         <para> La cadena que especifica la clase es convertida a una ruta
  96             relativa sustituyendo las barras bajas (_) por el separador de
  97             carpeta de su Sistema Operativo, y añadiendo '.php'. En el ejemplo
  98             de arriba, 'Container_Tree' se convierte en 'Container\\Tree.php' en
  99             Windows. </para>
 100
 101         <para> Si <varname>$dirs</varname> es una cadena o un array,
 102                 <methodname>Zend_Loader::loadClass()</methodname> busca las
 103             carpetas en el orden suministrado. El primer archivo encontrado es
 104             cargado. Si el archivo no existe en el <varname>$dirs</varname>
 105             especificado, entonces se busca en el
 106                 <methodname>include_path</methodname> del entorno
 107                 <acronym>PHP</acronym> . </para>
 108
 109         <para> Si el archivo no es encontrado o la clase no existe después de la
 110             carga, <methodname>Zend_Loader::loadClass()</methodname> lanza una
 111                 <classname>Zend_Exception</classname> . </para>
 112
 113         <para>
 114             <methodname>Zend_Loader::loadFile()</methodname> se usa para cargar,
 115             así que el nombre de la clase puede contener únicamente caracteres
 116             alfanuméricos, guiones ('-'), barras bajas ('_'), y puntos ('.'). </para>
 117
 118             <note>
 119             <title>Loading Classes from PHP Namespaces</title>
 120
 121             <para>
 122                 Starting in version 1.10.0, Zend Framework now allows loading classes from PHP
 123                 namespaces. This support follows the same guidelines and implementation as that
 124                 found in the <ulink
 125                     url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
 126                 Framework Interop Group PSR-0</ulink> reference implementation.
 127             </para>
 128
 129             <para>
 130                 Under this guideline, the following rules apply:
 131             </para>
 132
 133             <itemizedlist>
 134                 <listitem>
 135                     <para>
 136                         Each namespace separator is converted to a
 137                         <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
 138                     </para>
 139                 </listitem>
 140
 141                 <listitem>
 142                     <para>
 143                         Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
 144                         <constant>DIRECTORY_SEPARATOR</constant>.  The "_" character has no special
 145                         meaning in the namespace.
 146                     </para>
 147                 </listitem>
 148
 149                 <listitem>
 150                     <para>
 151                         The fully-qualified namespace and class is suffixed with ".php" when loading
 152                         from the file system.
 153                     </para>
 154                 </listitem>
 155             </itemizedlist>
 156
 157             <para>
 158                 As examples:
 159             </para>
 160
 161             <itemizedlist>
 162                 <listitem>
 163                     <para>
 164                         <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
 165                         <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
 166                     </para>
 167                 </listitem>
 168
 169                 <listitem>
 170                     <para>
 171                         <classname>\namespace\package\Class_Name</classname> =&gt;
 172                         <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
 173                     </para>
 174                 </listitem>
 175
 176                 <listitem>
 177                     <para>
 178                         <classname>\namespace\package_name\Class_Name</classname> =&gt;
 179                         <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
 180                     </para>
 181                 </listitem>
 182             </itemizedlist>
 183         </note>
 184     </sect2>
 185
 186     <sect2 id="zend.loader.load.isreadable">
 187
 188         <title>Comprobando si un Archivo Puede Ser Leído</title>
 189
 190         <para> El método estático
 191                 <methodname>Zend_Loader::isReadable($pathname)</methodname>
 192             devuelve <constant>TRUE</constant> si el archivo en la ruta
 193             $pathname existe y tiene permisos de lectura,
 194                 <constant>FALSE</constant> en caso contrario. </para>
 195
 196         <example id="zend.loader.load.isreadable.example">
 197             <title>Ejemplo del método isReadable()</title>
 198             <programlisting language="php"><![CDATA[
 199 if (Zend_Loader::isReadable($filename)) {
 200     // hace algo con $filename
 201 }
 202 ]]></programlisting>
 203         </example>
 204
 205         <para> El argumento <varname>$filename</varname> especifica el nombre de
 206             archivo que comprobar. Puede contener información de la ruta. Este
 207             método envuelve la función <acronym>PHP</acronym>
 208             <ulink url="http://php.net/is_readable">
 209                 <methodname>is_readable()</methodname>
 210             </ulink> . La función <acronym>PHP</acronym> no busca en
 211                 <methodname>include_path</methodname> , mientras que
 212                 <methodname>Zend_Loader::isReadable()</methodname> sí. </para>
 213
 214     </sect2>
 215
 216     <sect2 id="zend.loader.load.autoload">
 217
 218         <title>Usando el Autoloader</title>
 219
 220         <para> La clase <classname>Zend_Loader</classname> contiene un método
 221             que se puede registrar con <acronym>PHP</acronym> SPL autoloader.
 222                 <methodname>Zend_Loader::autoload()</methodname> es el método
 223             callback. Por comodidad, <classname>Zend_Loader</classname> permite
 224             a la función <methodname>registerAutoload()</methodname> registrar
 225             su método <methodname>autoload()</methodname> . Si la extensión
 226                 <methodname>spl_autoload</methodname> no está presente en el
 227             entorno <acronym>PHP</acronym> , entonces el método
 228                 <methodname>registerAutoload()</methodname> lanza una
 229                 <classname>Zend_Exception</classname> . </para>
 230
 231         <example id="zend.loader.load.autoload.example">
 232             <title>Ejemplo de registro del método callback del
 233                 autoloader</title>
 234             <programlisting language="php"><![CDATA[
 235 Zend_Loader::registerAutoload();
 236 ]]></programlisting>
 237         </example>
 238
 239         <para> Después de registrar el callback de autoload de Zend Framework,
 240             se pueden referenciar clases de Zend Framework sin tener que
 241             cargarlas explícitamente. El método
 242                 <methodname>autoload()</methodname> usa automáticamente
 243                 <methodname>Zend_Loader::loadClass()</methodname> cuando
 244             referencie una clase. </para>
 245
 246         <para> Si ha extendido la clase <classname>Zend_Loader</classname> , se
 247             puede pasar un argumento opcional a
 248                 <methodname>registerAutoload()</methodname> , para especificar
 249             la clase a partir de la cual registrar un método
 250                 <methodname>autoload()</methodname> . </para>
 251
 252         <example id="zend.loader.load.autoload.example-extended">
 253             <title>Ejemplo de registro del método de callback autoload desde una
 254                 clase extendida</title>
 255             <para> Debido a la semántica de referencia de funciones estáticas en
 256                     <acronym>PHP</acronym> , se debe implementar código tanto
 257                 para la clase <methodname>loadClass()</methodname> como
 258                     <methodname>autoload()</methodname> , y
 259                     <methodname>autoload()</methodname> debe llamar a
 260                     <methodname>self::loadClass()</methodname> . Si su método
 261                     <methodname>autoload()</methodname> delega en su padre la
 262                 llamada a <methodname>self::loadClass()</methodname> , entonces
 263                 llamará al método con ese nombre en la clase padre, no la
 264                 subclase. </para>
 265             <programlisting language="php"><![CDATA[
 266 class My_Loader extends Zend_Loader
 267 {
 268     public static function loadClass($class, $dirs = null)
 269     {
 270         parent::loadClass($class, $dirs);
 271     }
 272
 273     public static function autoload($class)
 274     {
 275         try {
 276             self::loadClass($class);
 277             return $class;
 278         } catch (Exception $e) {
 279             return false;
 280         }
 281     }
 282 }
 283
 284 Zend_Loader::registerAutoload('My_Loader');
 285 ]]></programlisting>
 286         </example>
 287
 288         <para> Se puede eliminar un callback de autoload.
 289                 <methodname>registerAutoload()</methodname> tiene un segundo
 290             parámetro opcional, que es <constant>TRUE</constant> por defecto. Si
 291             este parámetro es <constant>FALSE</constant> , el callback de
 292             autoload será borrado de la pila de autoload SPL. </para>
 293
 294     </sect2>
 295
 296 </sect1>