parse-ini-file.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a5346daf2bb2fab250fa03f0f6639a408d0b2240 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.parse-ini-file" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>parse_ini_file</refname>
  <refpurpose>Analyse un fichier de configuration</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>parse_ini_file</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>process_sections</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>scanner_mode</parameter><initializer><constant>INI_SCANNER_NORMAL</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>parse_ini_file</function> charge le fichier
   <parameter>filename</parameter> et retourne les
   configurations qui s'y trouvent sous forme d'un tableau
   associatif.
  </para>
  <para>
   La structure des fichiers de configuration lus est similaire
   à celle de &php.ini;.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Le nom du fichier de configuration à analyser. Si un chemin relatif
       est utilisé, il est évalué relatif au dossier courrant actuel, puis
       selon le <link linkend="ini.include-path">include_path</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>process_sections</parameter></term>
     <listitem>
      <para>
       En passant le paramètre <parameter>process_sections</parameter>
       à &true;, vous obtiendrez
       un tableau multidimensionnel avec les noms des sections.
       La valeur par défaut de ce paramètre est &false;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>scanner_mode</parameter></term>
     <listitem>
      <para>
       Peut être <constant>INI_SCANNER_NORMAL</constant> (défaut) ou
       <constant>INI_SCANNER_RAW</constant>. Si <constant>INI_SCANNER_RAW</constant>
       est fourni, alors les valeurs en option ne seront pas analysées.
      </para>
      &ini.scanner.typed;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   La configuration est retournée sous la forme d'un tableau associatif
   en cas de succès, et &false; si une erreur survient.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Contenu du fichier <filename>sample.ini</filename></title>
    <programlisting>
<![CDATA[
; Ceci est un fichier de configuration
; Les commentaires commencent par ';', comme dans php.ini

[first_section]
one = 1
five = 5
animal = BIRD

[second_section]
path = "/usr/local/bin"
URL = "http://www.example.com/~username"

[third_section]
phpversion[] = "5.0"
phpversion[] = "5.1"
phpversion[] = "5.2"
phpversion[] = "5.3"

urls[svn] = "http://svn.php.net"
urls[git] = "http://git.php.net"
]]>
    </programlisting>
   </example>
   <example>
    <title>Exemple avec <function>parse_ini_file</function></title>
    <para>
     Les <link linkend="language.constants">constantes</link> (mais pas les
     "constantes magiques" tel que <constant>__FILE__</constant>) peuvent aussi
     être utilisées dans le fichier .ini, ce qui fait que si vous définissez
     une constante avant d'exécuter <function>parse_ini_file</function>, elle
     sera intégrée dans les résultats. Seules les valeurs de configuration
     sont évaluées, et la valeur doit juste être la constante. Par exemple :
    </para>
    <programlisting role="php">
<![CDATA[
<?php

define('BIRD', 'Dodo bird');

// Analyse sans sections
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// Analyse avec sections
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);

?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [one] => 1
    [five] => 5
    [animal] => Dodo bird
    [path] => /usr/local/bin
    [URL] => http://www.example.com/~username
    [phpversion] => Array
        (
            [0] => 5.0
            [1] => 5.1
            [2] => 5.2
            [3] => 5.3
        )

    [urls] => Array
        (
            [svn] => http://svn.php.net
            [git] => http://git.php.net
        )

)
Array
(
    [first_section] => Array
        (
            [one] => 1
            [five] => 5
            [animal] => Dodo bird
        )

    [second_section] => Array
        (
            [path] => /usr/local/bin
            [URL] => http://www.example.com/~username
        )

    [third_section] => Array
        (
            [phpversion] => Array
                (
                    [0] => 5.0
                    [1] => 5.1
                    [2] => 5.2
                    [3] => 5.3
                )
            [urls] => Array
                (
                    [svn] => http://svn.php.net
                    [git] => http://git.php.net
                )

)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>parse_ini_file</function> pour analyser un fichier php.ini</title>
    <programlisting role="php">
<![CDATA[
<?php
// Une fonction simple pour comparer les résultats ci-dessous
function yesno($expression)
{
    return($expression ? 'Yes' : 'No');
}

// Lit le chemin du php.ini en utilisant php_ini_loaded_file()
$ini_path = php_ini_loaded_file();

// Analyse de php.ini
$ini = parse_ini_file($ini_path);

// Affichage et comparatif des valeurs. Notez que get_cfg_var()
// va donner les mêmes résultats entre les résultats analysés et chargés
echo '(analysé) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(chargé ) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
(analysé) magic_quotes_gpc = Yes
(chargé ) magic_quotes_gpc = Yes
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Interpolation de Valeur</title>
    <para>
     En plus d'évaluer les constantes, certains caractères ont une signification
     particulière dans une valeur ini.
     Additionnellement, les variables d'environment et options de configuration
     définies précédemment (voir <function>get_cfg_var</function>) peuvent être
     lu en utilisant la syntaxe <code>${}</code>.
    </para>
    <programlisting>
<![CDATA[
; | is used for bitwise OR
three = 2|3

; & is used for bitwise AND
four = 6&5

; ^ is used for bitwise XOR
five = 3^6

; ~ is used for bitwise negate
negative_two = ~1

; () is used for grouping
seven = (8|7)&(6|5)

; Interpoler la variable d'environnement PATH
path = ${PATH}

; Interpoler l'option de configuration 'memory_limit'
configured_memory_limit = ${memory_limit}
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Échapper des Caractères</title>
    <para>
     Certains caractères ont une signification particulière dans les chaînes à guillemets doubles et doivent
     être échappé en les préfixant d'un antislash.
     Tout d'abord, ce sont les guillemets double <code>"</code> comme le marqueur de frontière,
     et l'antislash <code>\</code> lui-même (si suivit d'un des caractères spéciaux) :
    </para>
    <programlisting>
<![CDATA[
quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote
]]>
    </programlisting>
    <para>
     Il y a une exception pour les chemins Windows-esque : il est possible de ne pas échapper
     l'antislash traînant si la chaîne cité est directement suivit d'un retour à la ligne :
    </para>
    <programlisting>
<![CDATA[
save_path = "C:\Temp\"
]]>
    </programlisting>
    <para>
     Si l'on doit échapper une guillemet double suivit d'un retour à la ligne dans une
     valeur multiligne, il est possible d'utiliser la concaténation de valeur de la manière
     suivante (il y a une chaîne guillemet double directement suivit d'une autre) :
    </para>
    <programlisting>
<![CDATA[
long_text = "Lorem \"ipsum\"""
 dolor" ; Results in: Lorem "ipsum"\n dolor
]]>
    </programlisting>
    <para>
     Un autre caractère avec une signification particulière est <code>$</code> (le signe dollar).
     Il doit être échappé s'il est suivit d'une accolade ouvrante :
    </para>
    <programlisting>
<![CDATA[
code = "\${test}"
]]>
    </programlisting>
    <para>
     L'échappement de caractères n'est pas supporté dans le mode <constant>INI_SCANNER_RAW</constant>
     (dans ce mode tous les caractères sont traité "tel quel").
    </para>
    <para>
     Il est à noter que l'analyseur INI ne supporte pas les séquences d'échappement standard
     (<code>\n</code>, <code>\t</code>, etc.).
     Si nécessaire, le résultat de <function>parse_ini_file</function> doit
     être post-procédé avec la fonction <function>stripcslashes</function>.
    </para>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Cette fonction n'a rien a voir avec le fichier
    &php.ini;. Ce dernier a déjà été traité lorsque
    vous commencez à exécuter votre script. Cette fonction
    peut vous permettre de lire vos propres fichiers de
    configuration.
   </para>
  </note>
  <note>
   <para>
    Si une valeur du fichier ini contient des
    données non-alphanumériques, il faut la protéger en la plaçant 
    entre guillemets doubles (").
   </para>
  </note>
  <note>
   <simpara>
    Il existe des mots réservés qui ne doivent pas être utilisés en tant que clés
    dans les fichiers ini. Cela inclut : <literal>null</literal>,
    <literal>yes</literal>, <literal>no</literal>, <literal>true</literal>,
    <literal>false</literal>, <literal>on</literal> et <literal>off</literal>.
    Les valeurs <literal>null</literal>, <literal>off</literal>, <literal>no</literal>
    et <literal>false</literal> donnent "" (chaîne vide). Les valeurs
    <literal>on</literal>, <literal>yes</literal> et
    <literal>true</literal> donnent "1", à moins que le mode
    <constant>INI_SCANNER_TYPED</constant> ne soit utilisé.
    Les caractères <literal>?{}|&amp;~!()^"</literal> ne doivent pas être utilisés
    n'importe où dans la clé et ont une signification spéciale dans la valeur.
   </simpara>
  </note>
  <note>
   <para>
    Les entrées sans un signal égal seront ignorées. Par exemple, "foo"
    sera ignoré alors que "bar =" sera analysé et ajouté avec une valeur vide.
    Par exemple, MySQL a une option de configuration "no-auto-rehash" dans
    le fichier <filename>my.cnf</filename> qui ne prend pas de valeur, aussi,
    elle sera ignorée.
   </para>
  </note>
  <note>
   <para>
    Les fichiers ini sont généralement traité comme des fichiers de texte brut
    par les servers web, et donc envoyé au navigateur si demandé. Ceci signifie
    que pour la sécurité soit les fichiers ini doivent être stockés en dehors
    de la racine docroot, soit reconfigurer le serveur web pour ne pas les servir.
    L'échec de faire l'une de ces mesures peut introduire un risque de sécurité.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>parse_ini_string</function></member>
   </simplelist>
  </para>
 </refsect1>
 
</refentry>
<!-- 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
-->