<?xml version="1.0" encoding="utf-8"?>

<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">

</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">

</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>

</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>

<!--

<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">

</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>