<?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>Configuration à l'exécution</title>

<sect1 xml:id="configuration.file">

<title>Le fichier de configuration</title>

<simpara>

Le fichier de configuration (&php.ini;) est lu par PHP au démarrage. Si PHP

a été compilé en module, le fichier n'est lu qu'une seule

fois, au lancement du serveur web. Pour les versions

<acronym>CGI</acronym> et <acronym>CLI</acronym> le fichier est lu à

chaque invocation.

</simpara>

<para>

Le &php.ini; est cherché dans ces endroits (et dans cet ordre) :

<itemizedlist>

<listitem>

<simpara>

L'endroit spécifique du module SAPI (la directive <literal>PHPIniDir</literal>

d'Apache 2, l'option de la ligne de commande <literal>-c</literal> en CGI et en CLI)

</simpara>

</listitem>

<listitem>

<simpara>

La variable d'environnement <varname>PHPRC</varname>.

</simpara>

</listitem>

<listitem>

<simpara>

L'endroit où se trouve le fichier <literal>php.ini</literal>

peut être défini pour différentes versions de PHP.

La racine des clés de registre dépend de l'architecture 32 ou 64 bit de l'OS et de PHP.

Pour un OS et PHP 32 bit ou un OS et PHP 64 bit, utiliser

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> pour PHP 32 bit

sur un OS 64 bit, utiliser

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>

à la place.

Pour une installation avec la même architecture, les clés de registre suivantes sont cherchées dans cet ordre :

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> et

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, où

x, y et z signifient les versions majeures, mineures et normales.

Pour une architecture 32 bit de PHP sur un OS 64 bit, les clés de

registre suivantes sont cherchées dans cet ordre :

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> et

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, où

x, y et z signifient les versions majeures, mineures et normales.

S'il y a une valeur pour <literal>IniFilePath</literal> dans ces clés,

la première trouvée sera utilisée comme endroit où se trouve le fichier

<literal>php.ini</literal> (uniquement sous Windows).

</simpara>

</listitem>

<listitem>

<simpara>

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> ou

<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, valeur de

<literal>IniFilePath</literal> (uniquement sous Windows).

</simpara>

</listitem>

<listitem>

<simpara>

Le dossier courant de travail (sauf pour CLI)

</simpara>

</listitem>

<listitem>

<simpara>

Le dossier du serveur web (pour les modules SAPI), ou le dossier contenant PHP

(autrement sous Windows)

</simpara>

</listitem>

<listitem>

<simpara>

Le dossier Windows (<filename class="directory">C:\windows</filename>

ou <filename class="directory">C:\winnt</filename>) (pour Windows), ou

l'option de compilation <literal>--with-config-file-path</literal> lors de la compilation

</simpara>

</listitem>

</itemizedlist>

</para>

<para>

Si le fichier <filename>php-SAPI.ini</filename> existe (où SAPI utilise SAPI, donc le

nom du fichier est par exemple <filename>php-cli.ini</filename> ou

<filename>php-apache.ini</filename>), il sera utilisé à la place du &php.ini;.

Le nom SAPI peut être déterminé en utilisant la fonction <function>php_sapi_name</function>.

</para>

<note>

<para>

Le serveur web Apache change ce dossier en dossier root au démarrage, ce qui fait

que PHP essaye de lire &php.ini; depuis le système de fichiers racine s'il existe.

</para>

</note>

<simpara>

Les variables d'environnement peuvent être référencées dans les valeurs

de configuration de &php.ini; comme illustré ci-dessous. À partir de PHP 8.3.0,

une valeur de repli peut être spécifiée, qui sera utilisée lorsque la variable

référencée n'est pas définie.

</simpara>

<example>

<title>Variables d'environnement dans &php.ini;</title>

<programlisting role="ini">

</programlisting>

</example>

<para>

Les directives &php.ini; sont directement documentées, par extensions,

sur les pages respectives du manuel de ces extensions. La

<link linkend="ini">liste des directives internes</link> est disponible

en annexe. Il est probable que toutes les directives PHP ne sont pas documentées

dans le manuel. Pour une liste complète des directives disponibles dans la version de PHP utilisée,

il convient de lire les commentaires du fichier &php.ini;.

Il est également possible de trouver la

<link xlink:href="&url.php.git.phpini;">dernière version du &php.ini;</link>

sur Git.

</para>

<para>

<example>

<title>Extrait du &php.ini;</title>

<programlisting role="ini">

</programlisting>

<!-- TODO: add more details about values and expressions -->

</example>

</para>

<para>

Il est possible de se référer à des variables .ini

depuis des fichiers .ini. Par exemple : <literal>open_basedir = ${open_basedir}

":/new/dir"</literal>.

</para>

<sect2 xml:id="configuration.file.scan">

<title>Parcourir des répertoires</title>

<para>

Il est possible de configurer PHP pour lire les fichiers .ini présents dans un dossier,

après la lecture de &php.ini;. Cela est réglé lors de la compilation avec l'argument

<option role="configure">--with-config-file-scan-dir</option>.

Le dossier à lire peut être modifié lors de l'exécution

par la définition de la variable d'environnement <varname>PHP_INI_SCAN_DIR</varname>.

</para>

<para>

Il est possible de lire plusieurs dossiers en les séparant avec un

séparateur de chemin spécifique à la plateforme (<literal>;</literal> pour Windows, NetWare

et RISC OS; <literal>:</literal> pour toutes les autres plateformes; la valeur utilisée par PHP est

disponible dans la constante <constant>PATH_SEPARATOR</constant>).

Si un dossier vide est fourni dans

<varname>PHP_INI_SCAN_DIR</varname>, PHP

lira également le dossier fourni à la compilation via

<option role="configure">--with-config-file-scan-dir</option>.

</para>

<para>

Dans chaque répertoire, PHP lira tous les fichiers terminant par

<literal>.ini</literal> dans l'ordre alphabétique. Une liste des fichiers qui

ont été chargés et dans quel ordre est disponible en appelant la fonction

<function>php_ini_scanned_files</function>, ou en exécutant PHP avec l'option

<option>--ini</option>.

</para>

<informalexample>

<screen>

</screen>

</informalexample>

</sect2>

</sect1>

<sect1 xml:id="configuration.file.per-user">

<title>Fichiers .user.ini</title>

<simpara>

PHP inclut la prise en charge des fichiers INI de configuration

par répertoire. Ces fichiers sont analysés <emphasis>uniquement</emphasis>

par le SAPI CGI/FastCGI. Cette fonctionnalité rend obsolète l'extension PECL

<literal>htscanner</literal>. Lors de l'exécution de PHP en tant que module Apache,

l'utilisation des fichiers &htaccess; produit le même effet.

</simpara>

<simpara>

En plus du fichier &php.ini; principal, PHP analyse les fichiers INI

contenus dans chaque dossier, en commençant par le dossier depuis lequel

le fichier PHP courant est appelé, et parcourt les dossiers jusqu'au

dossier racine courant (tel que défini par la variable

<varname>$_SERVER['DOCUMENT_ROOT']</varname>). Dans le cas où le fichier PHP

est hors de la racine web, seul son dossier est scanné.

</simpara>

<simpara>Seules les configurations INI avec les modes <constant>INI_PERDIR</constant>

et <constant>INI_USER</constant> seront reconnues dans les fichiers INI

.user.ini-style.

</simpara>

<simpara>

Deux nouvelles directives INI,

<link linkend="ini.user-ini.filename">user_ini.filename</link> et

<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>

contrôlent l'utilisation des fichiers INI définis par l'utilisateur.

</simpara>

<simpara>

<link linkend="ini.user-ini.filename">user_ini.filename</link> définit le nom du fichier cherché

par PHP dans chaque dossier ; si cette directive est définie à une chaîne vide,

PHP n'analysera rien du tout. Par défaut, vaut <literal>.user.ini</literal>.

</simpara>

<simpara>

<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> contrôle la durée entre 2 re-lectures

des fichiers INI définis par l'utilisateur. Par défaut, vaut

300 secondes (5 minutes).

</simpara>

</sect1>

<sect1 xml:id="configuration.changes.modes">

<title>Où une directive de configuration peut être modifiée</title>

<para>

Ces modes déterminent quand et où une directive PHP peut ou ne peut pas

être modifiée, et chaque directive du manuel fait référence à un de ces modes.

Par exemple, certaines directives peuvent être modifiées dans un script PHP

avec la fonction <function>ini_set</function>, alors que d'autres ont besoin

d'être modifiées dans les fichiers &php.ini; ou &httpd.conf;.

</para>

<para>

Par exemple, la directive

<link linkend="ini.output-buffering">output_buffering</link> a le mode

<constant>INI_PERDIR</constant> alors elle ne peut pas être modifiée

avec la fonction <function>ini_set</function>. D'un autre côté, la directive

<link linkend="ini.display-errors">display_errors</link> a le mode

<constant>INI_ALL</constant>, et peut être modifiée n'importe où,

y compris avec la fonction <function>ini_set</function>.

</para>

<para>

<variablelist>

<!--

<title>Constantes de mode INI</title>

<varlistentry>

<term>

<constant>INI_USER</constant>

(<type>int</type>)

</term>

<listitem>

<simpara>

L'entrée peut être définie dans des scripts utilisateur (comme avec <function xmlns="http://docbook.org/ns/docbook">ini_set</function>)

ou dans le <link xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.windows">registre Windows</link>.

L'entrée peut être définie dans &user-ini;

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term>

<constant>INI_PERDIR</constant>

(<type>int</type>)

</term>

<listitem>

<simpara>

L'entrée peut être définie dans &php.ini;, &htaccess;, &httpd.conf; ou &user-ini;

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term>

<constant>INI_SYSTEM</constant>

(<type>int</type>)

</term>

<listitem>

<simpara>

L'entrée peut être définie dans &php.ini; ou &httpd.conf;

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term>

<constant>INI_ALL</constant>

(<type>int</type>)

</term>

<listitem>

<simpara>

L'entrée peut être définie n'importe où

</simpara>

</listitem>

</varlistentry>

</variablelist>

</para>

</sect1>

<sect1 xml:id="configuration.changes">

<title>Comment modifier la configuration</title>

<sect2 xml:id="configuration.changes.apache">

<title>Exécuter PHP comme module Apache</title>

<simpara>

Lors de l'utilisation du module Apache, il est aussi possible de changer

les paramètres de configuration en utilisant les directives

dans les fichiers de configuration d'Apache (&httpd.conf;) et dans

les fichiers &htaccess;. Les privilèges

"AllowOverride Options" ou "AllowOverride All" sont nécessaires.

</simpara>

<para>

Il y a de nombreuses directives

Apache qui permettent de modifier la configuration de PHP

à partir des fichiers de configuration Apache. Pour une liste des

directives qui sont <constant>INI_ALL</constant>,

<constant>INI_PERDIR</constant> ou <constant>INI_SYSTEM</constant>

se reporter à l'annexe <link linkend="ini.list">Liste des directives

du php.ini</link>.

</para>

<para>

<variablelist>

<varlistentry>

<term>

<systemitem role="directive">php_value</systemitem>

<parameter>nom</parameter>

<parameter>valeur</parameter>

</term>

<listitem>

<para>

Modifie la valeur de la directive spécifiée.

Cette instruction n'est utilisable qu'avec les directives PHP de type

<constant>INI_ALL</constant> et <constant>INI_PERDIR</constant>.

Pour annuler une valeur qui aurait été modifiée au préalable,

utiliser la valeur <literal>none</literal>.

</para>

<note>

<simpara>

Ne pas utiliser <systemitem role="directive">php_value</systemitem>

pour configurer des valeurs booléennes.

<systemitem role="directive">php_flag</systemitem> (voir plus bas)

doit être utilisée.

</simpara>

</note>

</listitem>

</varlistentry>

<varlistentry>

<term>

<systemitem role="directive">php_flag</systemitem>

<parameter>nom</parameter>

<parameter>on|off</parameter>

</term>

<listitem>

<para>

Cette instruction est utilisée pour activer ou

désactiver une option.

Cette instruction n'est utilisable qu'avec les directives

PHP de type <constant>INI_ALL</constant> et

<constant>INI_PERDIR</constant>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<systemitem role="directive">php_admin_value</systemitem>

<parameter>nom</parameter>

<parameter>valeur</parameter>

</term>

<listitem>

<para>

Cette instruction affecte une valeur à la variable spécifiée.

Cette instruction <emphasis>NE peut PAS être utilisée</emphasis> dans un fichier

&htaccess;. Toute directive de PHP configurée avec le type

<systemitem role="directive">php_admin_value</systemitem> ne peut pas être

modifiée en utilisant le fichier &htaccess; ou la fonction <function>ini_set</function>.

Pour annuler une valeur qui aurait été modifiée au préalable, utiliser la

valeur <literal>none</literal>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<systemitem role="directive">php_admin_flag</systemitem>

<parameter>nom</parameter>

<parameter>on|off</parameter>

</term>

<listitem>

<para>

Cette directive est utilisée pour activer ou désactiver une option.

Cette instruction <emphasis>NE peut PAS être utilisée</emphasis> dans un fichier

&htaccess;. Toute directive de PHP configurée avec le type

<systemitem role="directive">php_admin_flag</systemitem> ne peut pas être

modifiée en utilisant le fichier &htaccess; ou par la fonction <function>ini_set</function>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

<example>

<title>Exemple de configuration Apache</title>

<programlisting role="ini">

</programlisting>

</example>

</para>

<caution>

<para>

Les constantes PHP n'existent pas en dehors de PHP. Par

exemple, dans le fichier &httpd.conf;,

il n'est pas possible d'utiliser des constantes PHP telles que

<constant>E_ALL</constant> ou <constant>E_NOTICE</constant> pour spécifier

le niveau de <link linkend="ini.error-reporting">rapport d'erreur</link>,

car ces constantes n'ont pas de signification pour Apache,

et seront remplacées par <emphasis>0</emphasis>.

Utiliser les valeurs numériques à la place.

Les constantes peuvent être utilisées dans le &php.ini;

</para>

</caution>

</sect2>

<sect2 xml:id="configuration.changes.windows">

<title>Modifier la configuration de PHP via la base de registre Windows</title>

<simpara>

Lors de l'utilisation de PHP sur Windows, la configuration peut

être modifiée dossier par dossier en utilisant la base de registres

de Windows. Les valeurs de configuration sont stockées

avec la clé de registre

<literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,

dans les sous-clés correspondantes aux noms de dossier. Par exemple,

la valeur d'une option dans le dossier <literal>c:\inetpub\wwwroot</literal>

sera stockée dans la clé

<literal>HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot</literal>.

La valeur de cette option sera utilisée pour tous les

scripts qui fonctionnent dans ce dossier ou ses sous-dossiers.

Les valeurs sous la clé doivent avoir le nom d'une

directive de configuration PHP,

et la valeur correspondante. Les constantes PHP ne sont

pas utilisables : il faut mettre la valeur entière.

Cependant, seules les valeurs des configurations dans

<constant>INI_USER</constant> peuvent être fixées de cette manière,

celles dans <constant>INI_PERDIR</constant> ne peuvent l'être,

car ces valeurs de configurations sont relues à chaque requête.

</simpara>

</sect2>

<sect2 xml:id="configuration.changes.other">

<title>Autres interfaces de configuration de PHP</title>

<para>

Suivant la façon dont PHP est exécuté, il est possible de changer certaines valeurs

durant l'exécution des scripts en utilisant <function>ini_set</function>.

Voir la documentation de la fonction <function>ini_set</function> pour plus

d'informations.

</para>

<para>

Pour obtenir une liste complète des options configurées

sur le système avec leurs valeurs courantes, il est possible d'exécuter

la fonction <function>phpinfo</function> et de consulter la page résultante.

Il est aussi possible d'accéder individuellement aux directives de configuration

pendant l'exécution des scripts en utilisant soit la fonction

<function>ini_get</function>, soit la fonction <function>get_cfg_var</function>.

</para>

</sect2>

</sect1>

</chapter>