ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e443388d4249fea383d6ec2d1a338be220cf95ee Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Configuración en tiempo de ejecución</title>

 <sect1 xml:id="configuration.file">
  <title>El fichero de configuración</title>

  <simpara>
   El fichero de configuración (&php.ini;)
   es leído al arrancar PHP. En las versiones en que PHP funciona como módulo de servidor,
   esto sucede únicamente cuando se inicia el servidor. En las versiones
   <acronym>CGI</acronym> y <acronym>CLI</acronym>, esto ocurre en
   cada ejecución.
  </simpara>
  <para>
   El fichero &php.ini; se busca en las siguientes ubicaciones (en orden):
   <itemizedlist>
    <listitem>
     <simpara>
      La ubicación específica de módulo SAPI (directiva <literal>PHPIniDir</literal>
      en Apache 2, opción de línea de comandos <literal>-c</literal> en CGI y CLI,
      parámetro <literal>php_ini</literal> en NSAPI,
      variable de entorno <literal>PHP_INI_PATH</literal> en THTTPD)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      La variable de entorno <varname>PHPRC</varname>. Antes de PHP 5.2.0,
      esta ubicación se comprobaba después de la clave de registro mencionada más abajo.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      A partir de PHP 5.2.0, se puede establecer la ubicación del fichero
      <literal>php.ini</literal> para diferentes versiones de PHP. Se examinan
      en orden las siguientes claves de registro:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> y
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, donde
      'x', 'y' y 'z' significan la versión mayor, menor, y de edición de PHP. Si existiera
      un valor para <literal>IniFilePath</literal> en cualquiera de estas claves, la primera en
      ser encontrada se utilizaría como ubicación del fichero <literal>php.ini</literal>
      (solo en Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>, valor de
      <literal>IniFilePath</literal> (solo en Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El directorio actual de trabajo (excepto CLI)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El directorio del servidor web (para módulos SAPI), o el directorio de PHP
      (excepto en Windows)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El directorio de Windows (<filename class="directory">C:\windows</filename>
      o <filename class="directory">C:\winnt</filename>) (para Windows), o la opción
      en tiempo de compilación <literal>--with-config-file-path</literal>.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Si existiera el fichero <filename>php-SAPI.ini</filename> (donde SAPI es la SAPI en uso,
   por ejemplo, <filename>php-cli.ini</filename> o
   <filename>php-apache.ini</filename>), se usaría éste en lugar de &php.ini;.
   Se puede determinar el nombre de la SAPI usando <function>php_sapi_name</function>.
  </para>
  <note>
   <para>
    El servidor web Apache cambia el directorio al raíz al arrancar, haciendo
    que PHP intente leer &php.ini; desde el sistema de ficheros raíz si existiera.
   </para>
  </note>
  <para>
   Las variables de entorno se pueden usar en &php.ini; como se muestra abajo.
  </para>
  <para>
   <example>
    <title>Variables de entorno de &php.ini;</title>
    <programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT se toma del entorno
memory_limit = ${PHP_MEMORY_LIMIT}
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Las directivas de &php.ini; manejadas por extensiones están documentadas
   en la propia página de cada extensión. Hay una <link linkend="ini">lista de
   directivas del núcleo</link> disponible en el apéndice. Es posible que no todas
   las directivas de PHP estén documentadas en el manual: para consultar una lista completa
   de las directivas disponibles en su versión de PHP, por favor, lea los comentarios del
   fichero &php.ini;. Adicionalmente, puede encontrar útil
   <link xlink:href="&url.php.git.phpini;">el último &php.ini;</link>
   desde Git.
  </para>
  <para>
   <example>
    <title>Ejemplo de &php.ini;</title>
    <programlisting role="ini">
<![CDATA[
; todo texto en una línea tras un punto y coma sin comillas (;) será ignorado
[php] ; los marcadores de sección (textos entre corchetes) también se ignoran
; Los valores de tipo boolean puede establecerse a:
;    true, on, yes
; o  false, off, no, none
register_globals = off
track_errors = yes

; se pueden encerrar los strings entre comillas dobles
include_path = ".:/usr/local/lib/php"

; las barras invertidas reciben el mismo tratamiento que el resto de caracteres
include_path = ".;c:\php\lib"
]]>
    </programlisting>
    <!-- TODO: add more details about values and expressions -->
   </example>
  </para>
  <para>
   A partir de PHP 5.1.0, es posible hacer referencia a variables .ini ya existentes desde
   el propio fichero .ini. Ejemplo: <literal>open_basedir = ${open_basedir}
   ":/new/dir"</literal>.
  </para>
  <sect2 xml:id="configuration.file.scan">
   <title>Directorios de búsqueda</title>

   <para>
    Es posible configurar PHP para que busque ficheros .ini en un directorio
    después de leer &php.ini;. Esto se puede realizar durante la compilación estableciento la
    opción <option role="configure">--with-config-file-scan-dir</option>. En
    PHP 5.2.0 y posteriores, el directorio de búsqueda puede ser sobrescrito durante la ejecución
    estableciendo la vairable de entorno <varname>PHP_INI_SCAN_DIR</varname>.
   </para>

   <para>
    Es posible buscar en varios directorios separándolos con el
    separador de rutas específico de cada plataforma (<literal>;</literal> en Windows, NetWare
    y RISC OS; <literal>:</literal> en las demás plataformas; el valor que PHP
    emplea está disponible como la constante <constant>PATH_SEPARATOR</constant>).
    Si se proporciona a <varname>PHP_INI_SCAN_DIR</varname> un directorio en blanco, PHP
    también buscará en el directorio dado durante la compilación mediante
    <option role="configure">--with-config-file-scan-dir</option>.
   </para>

   <para>
    PHP buscará dentro de cada directorio todos los ficheros que finalicen en
    <literal>.ini</literal> en orden alfabético. Se puede obtener una lista
    de los ficheros cargados, y en qué orden, llamando a
    <function>php_ini_scanned_files</function>, o ejecutando PHP con la
    opción <option>--ini</option>.
   </para>

   <informalexample>
    <screen>
<![CDATA[
Se asumen que PHP está configurado con --with-config-file-scan-dir=/etc/php.d,
y que el separador de rutas es :...

$ php
  PHP cargará todos los ficheros de /etc/php.d/*.ini como ficheros de configuración.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP cargará todos los ficheros de /usr/local/etc/php.d/*.ini como
  ficheros de configuración.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP cargará todos los ficheros de /etc/php.d/*.ini, y luego de
  /usr/local/etc/php.d/*.ini como ficheros de configuración.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP cargará todos los ficheros de /usr/local/etc/php.d/*.ini, y luego de
  /etc/php.d/*.ini como ficheros de configuración.
]]>
    </screen>
   </informalexample>
  </sect2>
  <sect2 xml:id="configuration.file.changelog">
   &reftitle.changelog;

   <para>
    <informaltable>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>&Version;</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>7.0.0</entry>
        <entry>
         Las almohadillas (<literal>#</literal>) ya no se reconocen como comentarios.
        </entry>
       </row>
       <row>
        <entry>5.3.0</entry>
        <entry>
         Las almohadillas (<literal>#</literal>) ya no deberían utilizarse como comentarios,
         ya que  lanzarán una advertencia de obsolescencia si se emplean.
        </entry>
       </row>
       <row>
        <entry>5.2.0</entry>
        <entry>
         La variable de entorno <varname>PHP_INI_SCAN_DIR</varname> se puede
         establecer para sobrescribir el directorio de búsqueda mediante el script de configuración.
        </entry>
       </row>
       <row>
        <entry>5.1.0</entry>
        <entry>
         Es posible referirse a variables .ini existentes dentrode ficheros .ini.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>
  </sect2>
 </sect1>

 <sect1 xml:id="configuration.file.per-user">
  <title>Ficheros .user.ini</title>

  <simpara>
   A partir de PHP 5.3.0 se incluye soporte para ficheros de configuración INI
   a nivel de directorios. Estos ficheros <emphasis>solo</emphasis> los procesa
   la SAPI CGI/FastCGI. Esta funcionalidad deja obsoleta la extensión PECL htscanner.
   Si está usando Apache, use los ficheros &htaccess; para lograr el mismo
   efecto.
  </simpara>

  <simpara>
   Además del fichero &php.ini; principal, PHP explora cada directorio en busca de
   ficheros INI, empezando por el directorio del fichero PHP solicitado, y
   continuando hasta el directorio raíz de documentos (tal y como esté establecido en
   <varname>$_SERVER['DOCUMENT_ROOT']</varname>). En el caso de que el fichero PHP se encuentre
   fuera del directorio raíz de documentos, sólo se explorará su directorio.
  </simpara>
  <simpara>
   En los ficheros INI estilo .user.ini sólo se reconocerán
   las configuraciones INI que tengan los modos
   <constant>INI_PERDIR</constant> y
   <constant>INI_USER</constant>.
  </simpara>

  <simpara>
   Las dos nuevas directivas INI,
   <link linkend="ini.user-ini.filename">user_ini.filename</link> y
   <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
   controlan el uso de los ficheros INI de usuarios.
  </simpara>

  <simpara>
   <link linkend="ini.user-ini.filename">user_ini.filename</link> establece el nombre del fichero que PHP buscará
   en cada directorio; si se establece un string vacío, PHP no realizará ninguna búsqueda.
   El nombre por omisión es <literal>.user.ini</literal>.
  </simpara>

  <simpara>
   <literal>user_ini.cache_ttl</literal> controla con qué frecuencia se releen los ficheros
   INI de usuario. El valor por omisión es 300 segundos (5 minutos).
  </simpara>
 </sect1>

 <sect1 xml:id="configuration.changes.modes">
  <title>Dónde se puede realizar un ajuste de configuración</title>

  <para>
   Estos modos determinan cuándo y dónde se debe o no asignar una directiva
   de PHP, y cada directiva del manual hace referencia a uno de estos
   modos. Por ejemplo, algunos ajustes pueden establecerse en scripts de PHP
   usando <function>ini_set</function>, mientras que otros requieren hacerlo en
   &php.ini; o en &httpd.conf;.
  </para>

  <para>
   Por ejemplo, el ajuste
   <link linkend="ini.output-buffering">output_buffering</link>
   es <constant>INI_PERDIR</constant> por tanto no puede establecerse usando
   <function>ini_set</function>. Sin embargo, la directiva
   <link linkend="ini.display-errors">display_errors</link> es
   <constant>INI_ALL</constant> por tanto se puede establecer en cualquier lugar,
   incluso con <function>ini_set</function>.
  </para>

  <para>
   <table>
    <title>Definición de los modos INI_*</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Modo</entry>
       <entry>Significado</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><constant>INI_USER</constant></entry>
       <entry>
        La entrada se puede establecer en scripts de usuario (como con <function>ini_set</function>)
        o en el <link linkend="configuration.changes.windows">registro de Windows</link>.
        Desde PHP 5.3, la entrada puede ser establecida en &user-ini;
       </entry>
      </row>
      <row>
       <entry><constant>INI_PERDIR</constant></entry>
       <entry>
        La entrada se puede establecer en &php.ini;, &htaccess;, &httpd.conf; o &user-ini;
        (desde PHP 5.3)
       </entry>
      </row>
      <row>
       <entry><constant>INI_SYSTEM</constant></entry>
       <entry>La entrada se puede establecer en &php.ini; o en &httpd.conf;</entry>
      </row>
      <row>
       <entry><constant>INI_ALL</constant></entry>
       <entry>La entrada se puede establecer en cualquier lugar</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>

 <sect1 xml:id="configuration.changes">
  <title>Cómo cambiar los ajustes de configuración</title>

  <sect2 xml:id="configuration.changes.apache">
   <title>Ejecutar PHP como un módulo de Apache</title>
   <simpara>
    Cuando se usa PHP como un módulo de Apache, se pueden cambiar los
    ajustes de configuración usando directivas en los ficheros de configuración
    de Apache (p.ej. &httpd.conf;) y en los ficheros &htaccess;. Se necesitarán
    los privilegios "AllowOverride Options" o "AllowOverride All" para poder hacerlo.
   </simpara>

   <para>
    Existen varias directivas de Apache que permiten
    cambiar la configuración de PHP desde los propios ficheros de configuración
    de Apache. Para un listado las directivas que son
    <constant>INI_ALL</constant>, <constant>INI_PERDIR</constant>,
    o <constant>INI_SYSTEM</constant>, consulte el apéndice de la
    <link linkend="ini.list">Lista de directivas de php.ini</link>.
   </para>

   <para>
    <variablelist>
     <varlistentry>
      <term>
       <systemitem role="directive">php_value</systemitem>
       <parameter>nombre</parameter>
       <parameter>valor</parameter>
      </term>
      <listitem>
       <para>
        Establece el valor de la directiva especificada.
        Sólo puede usarse con las directivas de tipo <constant>INI_ALL</constant> y <constant>INI_PERDIR</constant>.
        Para borrar un valor previamente establecido, use <literal>none</literal> como valor.
       </para>
       <note>
        <simpara>
         No use <systemitem role="directive">php_value</systemitem> para establecer valores boolean.
         Debe usarse en su lugar <systemitem role="directive">php_flag</systemitem> (ver más abajo).
        </simpara>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_flag</systemitem>
       <parameter>nombre</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Usado para establecer una directiva de configuración de tipo boolean.
        Sólo puede usarse con las directivas de tipo
        <constant>INI_ALL</constant> y <constant>INI_PERDIR</constant>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_value</systemitem>
       <parameter>nombre</parameter>
       <parameter>valor</parameter>
      </term>
      <listitem>
       <para>
        Establece el valor de la directiva especificada.
        Esto <emphasis>no se puede usar</emphasis> en ficheros &htaccess;.
        Ninguna directiva establecida con <systemitem role="directive">php_admin_value</systemitem>
        podrá ser sobrescrita por &htaccess; o por <function>ini_set</function>.
        Para borrar un valor establecido previamente use <literal>none</literal> como valor.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_flag</systemitem>
       <parameter>nombre</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Usado para establecer una directiva de configuración de tipo boolean.
        Esto <emphasis>no se puede usar</emphasis> en ficheros &htaccess;.
        Ninguna directiva establecida con <systemitem role="directive">php_admin_flag</systemitem>
        podrá ser sobrescrita por &htaccess; o por <function>ini_set</function>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    <example>
     <title>Ejemplo de configuración de Apache</title>
     <programlisting role="ini">
<![CDATA[
<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
]]>
     </programlisting>
    </example>
   </para>
   <caution>
    <para>
     Las constantes de PHP no existen fuera de PHP. Por ejemplo, en
     &httpd.conf; no se pueden usar constantes de PHP
     tales como <constant>E_ALL</constant> o <constant>E_NOTICE</constant>
     para establecer la directiva <link linkend="ini.error-reporting">error_reporting</link>
     puesto que no tendrán ningún significado y se evaluarán como
     <emphasis>0</emphasis>. Use en su lugar la máscara de bits asociada.
     Estas constantes sí pueden ser usadas en &php.ini;
    </para>
   </caution>
  </sect2>

  <sect2 xml:id="configuration.changes.windows">
   <title>Cambiar la configuración de PHP a través del registro de Windows</title>
   <simpara>
    Cuando se ejecuta PHP en Windows, se pueden modificar los valores
    de configuración a nivel de directorio usando el registro de Windows.
    Los valores de configuración se almacenan en la clave de registro
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,
    en las subclaves correspondientes a los nombres de ruta. Por ejemplo, los valores
    de configuración para el directorio <literal>c:\inetpub\wwwroot</literal>
    se almacenarían en la clave <literal>HKLM\SOFTWARE\PHP\Per Directory
    Values\c\inetpub\wwwroot</literal>. Los ajustes para el directorio
    estarán activos para cualquier script dentro de este directorio o
    en cualquiera de sus subdirectorios. Los valores bajo esta clave
    deberían tener el nombre de la directiva de configuración de PHP y el
    valor como string. Las constantes de PHP usadas como valor no serán procesadas.
    En cualquier caso, únicamente los valores de configuración
    modificables de <constant>INI_USER</constant> podrán establecerse
    con este método, mientras que los valores de <constant>INI_PERDIR</constant> no.
   </simpara>
  </sect2>

  <sect2 xml:id="configuration.changes.other">
   <title>Otras interfaces a PHP</title>
   <para>
    Independientemente de cómo ejecute PHP, se pueden cambiar determinados valores
    de los scripts en tiempo de ejecución mediante <function>ini_set</function>.
    Consulte la documentación de la página <function>ini_set</function> para más información.
   </para>
   <para>
    Si está interesado en una lista completa de los ajustes de configuración
    en su sistema con sus valores actuales, puede ejecutar la función
    <function>phpinfo</function>, y consultar la página mostrada.
    Puede también acceder a los valores de directivas de configuración
    concretas usando <function>ini_get</function> o
    <function>get_cfg_var</function>.
   </para>
  </sect2>
 </sect1>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->