archived-doc-fr/install/ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 9ab074d32484672f93e5d822f42fb94ae9088207 Maintainer: yannick 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>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">
<![CDATA[
; PHP_MEMORY_LIMIT est repris depuis l'environnement
memory_limit = ${PHP_MEMORY_LIMIT}
; Si PHP_MAX_EXECUTION_TIME n'est pas défini, il prendra la valeur de repli 30.
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
]]>
   </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">
<![CDATA[
; tout texte sur une ligne, situé après un point-virgule ";" est ignoré
[php] ; les marqueurs de section (texte entre crochets) sont aussi ignorés
; Les valeurs booléennes peuvent être spécifiées comme ceci :
;    true, on, yes
; ou false, off, no, none
register_globals = off
track_errors = yes

; vous pouvez placer les chaînes de caractères entre guillemets
include_path = ".:/usr/local/lib/php"

; Les antislash sont traités comme n'importe quel caractère
include_path = ".;c:\php\lib"
]]>
    </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>
<![CDATA[
En supposant que PHP est configuré avec --with-config-file-scan-dir=/etc/php.d,
et que le séparateur de chemin est :...

$ php
  PHP va charger tous les fichiers présents dans /etc/php.d/*.ini comme fichiers
  de configuration.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP va charger tous les fichiers présents dans /usr/local/etc/php.d/*.ini 
  comme fichiers de configuration.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP va charger tous les fichiers présents dans /etc/php.d/*.ini, puis
  /usr/local/etc/php.d/*.ini comme fichiers de configuration.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP va charger tous les fichiers présents dans /usr/local/etc/php.d/*.ini, puis dans
  /etc/php.d/*.ini comme fichiers de configuration.
]]>
    </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>
    <!--
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 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">
<![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>
     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>

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