archived-doc-es/install/ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 9ab074d32484672f93e5d822f42fb94ae9088207 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
 <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 por PHP al inicio. Si se ha compilado PHP como módulo, el fichero solo se lee una vez, al inicio del servidor web. Para las versiones
   <acronym>CGI</acronym> y <acronym>CLI</acronym> el fichero es leído en cada invocación.
  </simpara>
  <para>
   El &php.ini; se busca en estos lugares (y en este orden) :
   <itemizedlist>
    <listitem>
     <simpara>
      El lugar específico del módulo SAPI (la directiva <literal>PHPIniDir</literal>
      de Apache 2, la opción de la línea de comandos <literal>-c</literal> en CGI y en CLI)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      La variable de entorno <varname>PHPRC</varname>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El lugar donde se encuentra el fichero <literal>php.ini</literal>
      puede ser definido para diferentes versiones de PHP.
      La raíz de las claves de registro depende de la arquitectura de 32 o 64 bits del SO y de PHP.
      Para un SO y PHP de 32 bits o un SO y PHP de 64 bits, utilizar
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> para PHP de 32 bits
      en un SO de 64 bits, utilizar
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>
      en su lugar.
      Para una instalación con la misma arquitectura, las siguientes claves de registro se buscan en este orden :
      <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 las versiones mayores, menores y normales.
      Para una arquitectura de 32 bits de PHP en un SO de 64 bits, las siguientes claves de
      registro se buscan en este orden :
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> y
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, donde
      x, y y z significan las versiones mayores, menores y normales.
      Si hay un valor para <literal>IniFilePath</literal> en estas claves,
      el primero encontrado será utilizado como el lugar donde se encuentra el fichero
      <literal>php.ini</literal> (solo en Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> o
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, valor de
      <literal>IniFilePath</literal> (solo en Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El directorio de trabajo actual (excepto para CLI)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El directorio del servidor web (para los módulos SAPI), o el directorio que contiene PHP
      (de otro modo en Windows)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      El directorio Windows (<filename class="directory">C:\windows</filename>
      o <filename class="directory">C:\winnt</filename>) (para Windows), o
      la opción de compilación <literal>--with-config-file-path</literal> durante la compilación
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Si el fichero <filename>php-SAPI.ini</filename> existe (donde SAPI utiliza SAPI, por lo que
   el nombre del fichero es e.g. <filename>php-cli.ini</filename> o
   <filename>php-apache.ini</filename>), se utilizará en lugar de &php.ini;.
   El nombre SAPI puede ser determinado utilizando la función <function>php_sapi_name</function>.
  </para>
  <note>
   <para>
    El servidor web Apache cambia este directorio al directorio root al inicio, lo que hace
    que PHP intente leer &php.ini; desde el sistema de ficheros raíz si existe.
   </para>
  </note>
  <simpara>
   Las variables de entorno pueden ser referenciadas en los valores
   de configuración de &php.ini; como se ilustra a continuación. A partir de PHP 8.3.0,
   un valor de repliegue puede ser especificado, que será utilizado cuando la variable
   referenciada no esté definida.
  </simpara>
  <example>
   <title>Variables de entorno en &php.ini;</title>
   <programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT se toma desde el entorno
memory_limit = ${PHP_MEMORY_LIMIT}
; Si PHP_MAX_EXECUTION_TIME no está definido, tomará el valor de repliegue 30.
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
]]>
   </programlisting>
  </example>
  <para>
   Las directivas &php.ini; están directamente documentadas, por extensiones,
   en las páginas respectivas del manual de estas extensiones. La
   <link linkend="ini">lista de directivas internas</link> está disponible
   en el anexo. Es probable que no todas las directivas PHP estén documentadas
   en el manual. Para una lista completa de las directivas disponibles en su versión de PHP,
   lea los comentarios de su propio fichero &php.ini;.
   También se puede encontrar la
   <link xlink:href="&url.php.git.phpini;">última versión del &php.ini;</link>
   en Git.
  </para>
  <para>
   <example>
    <title>Extracto del &php.ini;</title>
    <programlisting role="ini">
<![CDATA[
; todo texto en una línea, situado después de un punto y coma ";" es ignorado
[php] ; los marcadores de sección (texto entre corchetes) también son ignorados
; Los valores booleanos pueden ser especificados así :
;    true, on, yes
; o false, off, no, none
register_globals = off
track_errors = yes

; se pueden colocar las cadenas de caracteres entre comillas
include_path = ".:/usr/local/lib/php"

; Las barras invertidas se tratan como cualquier carácter
include_path = ".;c:\php\lib"
]]>
    </programlisting>
    <!-- TODO: add more details about values and expressions -->
   </example>
  </para>
  <para>
   Es posible referirse a variables .ini
   desde ficheros .ini. Por ejemplo : <literal>open_basedir = ${open_basedir}
   ":/new/dir"</literal>.
  </para>
    <sect2 xml:id="configuration.file.scan">
   <title>Leer un directorio</title>

   <para>
    Es posible configurar PHP para leer los ficheros .ini presentes en un directorio.
    después de la lectura de &php.ini;. Esto se ajusta durante la compilación con el argumento
    <option role="configure">--with-config-file-scan-dir</option>.
    El directorio a leer puede ser modificado durante la ejecución
    por la definición de la variable de entorno <varname>PHP_INI_SCAN_DIR</varname>.
   </para>

   <para>
    Es posible leer varios directorios separándolos con un
    separador de ruta específico de la plataforma (<literal>;</literal> para Windows, NetWare
    y RISC OS; <literal>:</literal> para todas las otras plataformas; el valor utilizado por PHP es
    disponible en la constante <constant>PATH_SEPARATOR</constant>).
    Si se proporciona un directorio vacío en
    <varname>PHP_INI_SCAN_DIR</varname>, PHP
    también leerá el directorio proporcionado durante la compilación a través de
    <option role="configure">--with-config-file-scan-dir</option>.
   </para>

   <para>
    En cada directorio, PHP leerá todos los ficheros que terminen por
    <literal>.ini</literal> en orden alfabético. Una lista de los ficheros que
    han sido cargados y en qué orden está disponible llamando a la función
    <function>php_ini_scanned_files</function>, o ejecutando PHP con la opción
    <option>--ini</option>.
   </para>

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

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

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

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

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP cargará todos los ficheros presentes en /usr/local/etc/php.d/*.ini, luego en
  /etc/php.d/*.ini como fichero de configuración.
]]>
    </screen>
   </informalexample>
  </sect2>
 </sect1>

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

  <simpara>
   PHP incluye el soporte para ficheros INI de configuración
   por directorio. Estos ficheros son analizados <emphasis>solo</emphasis>
   por el SAPI CGI/FastCGI. Esta funcionalidad hace obsoleta la extensión PECL
   <literal>htscanner</literal>. Si se ejecuta PHP como módulo Apache,
   el uso de los ficheros &htaccess; produce el mismo efecto.
  </simpara>

  <simpara>
   Además del fichero &php.ini; principal, PHP analiza los ficheros INI
   contenidos en cada directorio, comenzando por el directorio desde el cual
   el fichero PHP actual es llamado, y recorre los directorios hasta el
   directorio raíz actual (tal como se define por la variable
   <varname>$_SERVER['DOCUMENT_ROOT']</varname>). En el caso de que el fichero PHP
   esté fuera de la raíz web, solo su directorio será escaneado.
  </simpara>
  <simpara>Solo las configuraciones INI con los modos <constant>INI_PERDIR</constant>
   y <constant>INI_USER</constant> serán reconocidas en los ficheros INI
   .user.ini-style.
  </simpara>

  <simpara>
   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 definidos por el usuario.
  </simpara>

  <simpara>
   <link linkend="ini.user-ini.filename">user_ini.filename</link> define el nombre del fichero buscado
   por PHP en cada directorio ; si esta directiva está definida a una cadena vacía,
   PHP no analizará nada en absoluto. Por defecto, vale <literal>.user.ini</literal>.
  </simpara>

  <simpara>
   <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> controla la duración entre 2 relecturas
   de los ficheros INI definidos por el usuario. Por defecto, vale
   300 segundos (5 minutos).
  </simpara>
 </sect1>

 <sect1 xml:id="configuration.changes.modes">
  <title>Dónde una directiva de configuración puede ser modificada</title>

  <para>
   Estos modos determinan cuándo y dónde una directiva PHP puede o no puede
   ser modificada, y cada directiva del manual está dirigida por uno de estos modos.
   Por ejemplo, algunas directivas pueden ser modificadas en un script PHP
   con la función <function>ini_set</function>, mientras que otras necesitan
   ser modificadas en los ficheros &php.ini; o &httpd.conf;.
  </para>

  <para>
   Por ejemplo, la directiva
   <link linkend="ini.output-buffering">output_buffering</link> tiene el modo
   <constant>INI_PERDIR</constant> por lo que no puede ser modificada
   con la función <function>ini_set</function>. Por otro lado, la directiva
   <link linkend="ini.display-errors">display_errors</link> tiene el modo
   <constant>INI_ALL</constant>, y puede ser modificada en cualquier lugar,
   incluyendo con la función <function>ini_set</function>.
  </para>

  <para>
   <variablelist>
    <!--
Replace everything inside the <variablelist> element with an <xi:include>
once libxml2 gets XInclude 1.1 attribute copying support.
The below <xi:include> will include the appropriate elements
but needs all top-level xml:id's removed (see XInclude 1.1 set-xml-id).
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('constant.ini-mode')/*)"><xi:fallback/>
</xi:include>
-->
    <title>Constantes de modo INI</title>
    <varlistentry>
     <term>
      <constant>INI_USER</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       La entrada puede ser definida en scripts de usuario (como con <function xmlns="http://docbook.org/ns/docbook">ini_set</function>)
       o en el <link xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.windows">registro Windows</link>.
       La entrada puede ser definida en &user-ini;
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_PERDIR</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       La entrada puede ser definida en &php.ini;, &htaccess;, &httpd.conf; o &user-ini;
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_SYSTEM</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       La entrada puede ser definida en &php.ini; o &httpd.conf;
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_ALL</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       La entrada puede ser definida en cualquier lugar
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>

 <sect1 xml:id="configuration.changes">
  <title>Cómo modificar la configuración</title>

  <sect2 xml:id="configuration.changes.apache">
   <title>Ejecutar PHP como módulo Apache</title>
   <simpara>
    Cuando se utiliza el módulo Apache, también se pueden cambiar
    los parámetros de configuración utilizando las directivas
    en los ficheros de configuración de Apache (&httpd.conf;) y en
    los ficheros &htaccess;. Se necesitarán los privilegios
    "AllowOverride Options" o "AllowOverride All".
   </simpara>

   <para>
    Hay muchas directivas
    Apache que permiten modificar la configuración de PHP
    desde los ficheros de configuración de Apache. Para una lista de las
    directivas que son <constant>INI_ALL</constant>,
    <constant>INI_PERDIR</constant> o <constant>INI_SYSTEM</constant>
    consulte el anexo <link linkend="ini.list">Lista de directivas
    del php.ini</link>.
   </para>

   <para>
    <variablelist>
     <varlistentry>
      <term>
       <systemitem role="directive">php_value</systemitem>
       <parameter>nombre</parameter>
       <parameter>valor</parameter>
      </term>
      <listitem>
       <para>
        Modifica el valor de la directiva especificada.
        Esta instrucción solo es utilizable con las directivas PHP de tipo
        <constant>INI_ALL</constant> y <constant>INI_PERDIR</constant>.
        Para anular un valor que hubiera sido modificado previamente,
        utilice el valor <literal>none</literal>.
       </para>
       <note>
        <simpara>
         No utilice <systemitem role="directive">php_value</systemitem>
         para configurar valores booleanos.
         <systemitem role="directive">php_flag</systemitem> (ver más abajo)
         debe ser utilizada.
        </simpara>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_flag</systemitem>
       <parameter>nombre</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Esta instrucción se utiliza para activar o
        desactivar una opción.
        Esta instrucción solo es utilizable con las directivas
        PHP 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>
        Esta instrucción asigna un valor a la variable especificada.
        Esta instrucción <emphasis>NO puede ser utilizada</emphasis> en un fichero
        &htaccess;. Cualquier directiva de PHP configurada con el tipo
        <systemitem role="directive">php_admin_value</systemitem> no puede ser
        modificada utilizando el fichero &htaccess; o la función <function>ini_set</function>.
        Para anular un valor que hubiera sido modificado previamente, utilice la
        valor <literal>none</literal>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_flag</systemitem>
       <parameter>name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Esta directiva se utiliza para activar o desactivar una opción.
        Esta instrucción <emphasis>NO puede ser utilizada</emphasis> en un fichero
        &htaccess;. Cualquier directiva de PHP configurada con el tipo
        <systemitem role="directive">php_admin_flag</systemitem> no puede ser
        modificada utilizando el fichero &htaccess; o por la función <function>ini_set</function>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    <example>
     <title>Ejemplo de configuración 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 PHP no existen fuera de PHP. Por
     ejemplo, en el fichero &httpd.conf;,
     no se pueden utilizar constantes PHP como
     <constant>E_ALL</constant> o <constant>E_NOTICE</constant> para especificar
     el nivel de <link linkend="ini.error-reporting">informe de errores</link>,
     ya que estas constantes no tienen significado para Apache,
     y serán reemplazadas por <emphasis>0</emphasis>.
     Utilice los valores numéricos en su lugar.
     Las constantes pueden ser utilizadas en el &php.ini;
    </para>
   </caution>
  </sect2>

  <sect2 xml:id="configuration.changes.windows">
   <title>Modificar la configuración de PHP a través del registro de Windows</title>
   <simpara>
    Cuando se utiliza PHP en Windows, la configuración puede
    ser modificada directorio por directorio utilizando el registro de Windows. Los valores de configuración se almacenan
    con la clave de registro
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,
    en las subclaves correspondientes a los nombres de directorio. Por ejemplo,
    el valor de una opción en el directorio <literal>c:\inetpub\wwwroot</literal>
    se almacenará en la clave
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot</literal>.
    El valor de esta opción será utilizado para todos los
    scripts que funcionen en este directorio o sus subdirectorios.
    Los valores bajo la clave deben tener el nombre de una
    dirección de configuración PHP,
    y el valor correspondiente. Las constantes PHP no son utilizables : hay que poner el valor entero.
    Sin embargo, solo los valores de las configuraciones en
    <constant>INI_USER</constant> pueden ser fijados de esta manera,
    los de <constant>INI_PERDIR</constant> no pueden serlo,
    ya que estos valores de configuración son releídos en cada solicitud.
   </simpara>
  </sect2>

  <sect2 xml:id="configuration.changes.other">
   <title>Otras interfaces de configuración de PHP</title>
   <para>
    Según la forma en que se ejecute PHP, se pueden cambiar algunos valores
    durante la ejecución de los scripts utilizando <function>ini_set</function>.
    Consulte la documentación de la función <function>ini_set</function> para más
    información.
   </para>
   <para>
    Si está interesado en una lista completa de las opciones configuradas
    en su sistema con sus valores actuales, puede ejecutar
    la función <function>phpinfo</function> y consultar la página resultante.
    También se puede acceder individualmente a las directivas de configuración
    durante la ejecución de los scripts utilizando la función
    <function>ini_get</function> o la función <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
-->