doc-fr/install/ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4eeb07225f615fcde68cbefb84df2fc9bf278f1f Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <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 vous
   avez compilé PHP 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éfinis 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> and
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, où
      x, y et z signifie 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> and
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, où
      x, y et z signifie 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 e.g. <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>
  <para>
   Les variables d'environnements peuvent être utilisées dans le fichier
   &php.ini; comme ci-dessous.
  </para>
  <para>
   <example>
    <title>Les variables d'environnement dans un fichier &php.ini;</title>
     <programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT est repris depuis l'environnement
memory_limit = ${PHP_MEMORY_LIMIT}
]]>
     </programlisting>
    </example>
  </para>
  
  <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 votre version de PHP,
   merci de lire les commentaires de votre propre fichier &php.ini;. 
   Vous pouvez également 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>Lire un répertoire</title>

   <para>
    Il est possible de configurer PHP pour lire les fichiers .ini présent 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 plateforme; la valeur utilisée par PHP est
    disponible dans la contante <constant>PATH_SEPARATOR</constant>).
    Si un dossier vide est fourni dans 
    <varname>PHP_INI_SCAN_DIR</varname>, PHP
    lira également le dossier fournis à 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é 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[
Assuming PHP is configured with --with-config-file-scan-dir=/etc/php.d,
and that the path separator is :...

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

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

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

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP va charger tous les fichiers présent dans /usr/local/etc/php.d/*.ini, puis dans
  /etc/php.d/*.ini comme fichier 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>. Si vous exécutez 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>PHP_INI_PERDIR</constant>
   et <constant>PHP_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 est dirigée par 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 
   <literal>PHP_INI_PERDIR</literal> alors elle ne peut pas être modifiée
   avec la fonction <function>ini_set</function>. D'un autre coté, la directive
   <link linkend="ini.display-errors">display_errors</link> a le mode
   <literal>PHP_INI_ALL</literal>, et peut être modifiée n'importe où,
   y compris avec la fonction <function>ini_set</function>.
  </para>
  
  <para>
   <table>
    <title>Définition des modes PHP_INI_*</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Mode</entry>
       <entry>Signification</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>PHP_INI_USER</literal></entry>
       <entry>
        La directive peut être modifiée dans un script utilisateur, 
        avec la fonction <function>ini_set</function>, ou via        
        la <link linkend="configuration.changes.windows">base de registre Windows</link>.
        L'entrée peut être définie dans &user-ini;.
       </entry>
      </row>
      <row>
       <entry><literal>PHP_INI_PERDIR</literal></entry>
       <entry>
        La directive peut être modifiée dans les fichiers &php.ini;,
        &htaccess;, &httpd.conf; ou &user-ini;
       </entry>
      </row>
      <row>
       <entry><literal>PHP_INI_SYSTEM</literal></entry>
       <entry>La directive peut être modifiée dans les fichiers &php.ini; ou &httpd.conf;</entry>
      </row>
      <row>
       <entry><literal>PHP_INI_ALL</literal></entry>
       <entry>La directive peut être modifiée n'importe où</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </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>
    Lorsque vous utilisez le module Apache, vous pouvez aussi changer
    les paramètres de configuration en utilisant les directives
    dans les fichiers de configuration d'Apache (&httpd.conf;) et dans
    les fichiers &htaccess;. Vous aurez besoin des privilèges
    "AllowOverride Options" ou "AllowOverride All".
   </simpara>
   
   <para>
    Il y a de nombreuses directives
    Apache qui vous permettent de modifier la configuration de PHP
    à partir des fichiers de configuration Apache. Pour une liste des
    directives qui sont <constant>PHP_INI_ALL</constant>,
    <constant>PHP_INI_PERDIR</constant> ou <constant>PHP_INI_SYSTEM</constant>
    reportez-vous à 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>PHP_INI_ALL</constant> et <constant>PHP_INI_PERDIR</constant>.
        Pour annuler une valeur qui aurait été modifiée au préalable,
        utilisez la valeur <literal>none</literal>.
       </para>
       <note>
        <simpara>
         N'utilisez pas <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>PHP_INI_ALL</constant> et
        <constant>PHP_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, utilisez la
        valeur <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>
        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;,
     vous ne pouvez pas 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>.
     Utilisez 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>
    Lorsque vous utilisez 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
    <link linkend="configuration">direction de configuration PHP</link>,
    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>PHP_INI_USER</constant> peuvent être fixées de cette manière,
    celles dans <constant>PHP_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 vous exécutez PHP, vous pouvez changer certaines valeurs
    durant l'exécution de vos scripts en utilisant <function>ini_set</function>.
    Voir la documentation de la fonction <function>ini_set</function> pour plus
    d'informations.
   </para>
   <para>
    Si vous êtes intéressé par une liste complète des options configurées
    sur votre système avec leurs valeurs courantes, vous pouvez exécuter
    la fonction <function>phpinfo</function> et consulter la page résultante.
    Vous pouvez aussi accéder individuellement aux directives de configuration
    pendant l'exécution de vos 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
-->