parse-ini-file.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: a5346daf2bb2fab250fa03f0f6639a408d0b2240 Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<refentry xml:id="function.parse-ini-file" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>parse_ini_file</refname>
  <refpurpose>解析一个配置文件</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> 载入一个由
   <parameter>filename</parameter> 指定的 ini
   文件，并将其中的设置作为一个关联数组返回。
  </para>
  <para>
   ini 文件的结构和 &php.ini; 的相同。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       要解析的 ini 文件的文件名。如果使用相对路径，则优先在相对于当前工作目录的目录中查找文件，如果未找到则在
       <link linkend="ini.include-path">include_path</link> 中查找文件进行解析。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>process_sections</parameter></term>
     <listitem>
      <para>
       如果将 <parameter>process_sections</parameter> 参数设为
       &true;，将得到多维数组，包括了配置文件中的节名和配置。<parameter>process_sections</parameter>
       的默认值是 &false;。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>scanner_mode</parameter></term>
     <listitem>
      <para>
       可以是 <constant>INI_SCANNER_NORMAL</constant>（默认），也可以是
       <constant>INI_SCANNER_RAW</constant>。如果提供了
       <constant>INI_SCANNER_RAW</constant>，然后将不会解析选项值。
      </para>
      &ini.scanner.typed;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   成功时以关联数组 <type>array</type> 返回设置，失败时返回 &false;。
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><filename>sample.ini</filename> 的内容</title>
    <programlisting>
<![CDATA[
; This is a sample configuration file
; Comments start with ';', as in 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><function>parse_ini_file</function> 例子</title>
    <para>
     <link linkend="language.constants">常量</link>（并非像
     <constant>__FILE__</constant> 之类的“魔术常量”）也可以在 ini
     文件中被解析，因此如果在运行 <function>parse_ini_file</function>
     之前定义了常量作为 ini 的值，将会被集成到结果中去。只有 ini
     的值会被求值，且该值必须是常量。例如：
    </para>
    <programlisting role="php">
<![CDATA[
<?php

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

// Parse without sections
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// Parse with 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> 格式化 php.ini 文件</title>
    <programlisting role="php">
<![CDATA[
<?php
// 简单的函数，用于比较下面的结果
function yesno($expression)
{
    return($expression ? 'Yes' : 'No');
}

// 使用 php_ini_loaded_file() 函数获取 php.ini 的路径
$ini_path = php_ini_loaded_file();

// 解析 php.ini
$ini = parse_ini_file($ini_path);

// Print and compare the values, note that using get_cfg_var()
// will give the same results for parsed and loaded here
echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
(parsed) magic_quotes_gpc = Yes
(loaded) magic_quotes_gpc = Yes
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>内插值</title>
    <para>
     除了对常量求值之外，某些字符在 ini 值中具有特殊含义。此外，可以使用 <code>${}</code>
     语法读取环境变量和之前定义的配置项（参阅 <function>get_cfg_var</function>）。
    </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)

; Interpolate the PATH environment variable
path = ${PATH}

; Interpolate the configuration option 'memory_limit'
configured_memory_limit = ${memory_limit}

]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>转义字符</title>
    <para>
     Some characters have special meaning in double-quoted strings and must be escaped by the backslash prefix.
     First of all, these are the double quote <code>"</code> as the boundary marker, and the backslash <code>\</code> itself
     (if followed by one of the special characters):
    </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>
     There is an exception made for Windows-like paths: it's possible to not escape trailing backslash
     if the quoted string is directly followed by a linebreak:
    </para>
    <programlisting>
<![CDATA[
save_path = "C:\Temp\"
]]>
    </programlisting>
    <para>
     If one does need to escape double quote followed by linebreak in a multiline value,
     it's possible to use value concatenation in the following way
     (there is one double-quoted string directly followed by another one):
    </para>
    <programlisting>
<![CDATA[
long_text = "Lorem \"ipsum\"""
 dolor" ; Results in: Lorem "ipsum"\n dolor
]]>
    </programlisting>
    <para>
     Another character with special meaning is <code>$</code> (the dollar sign).
     It must be escaped if followed by the open curly brace:
    </para>
    <programlisting>
<![CDATA[
code = "\${test}"
]]>
    </programlisting>
    <para>
     <constant>INI_SCANNER_RAW</constant> 模式不支持转义字符（在此模式下，所有字符都会“不做任何处理”）。
    </para>
    <para>
     注意 ini 解析器不支持标准转义序列（<code>\n</code>、<code>\t</code> 等）。如有必要，使用
     <function>stripcslashes</function> 函数对 <function>parse_ini_file</function>
     后的结果进行后处理。
    </para>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    本函数和 &php.ini;
    文件无关，该文件在运行脚本时就已经处理过了。本函数可以用来读取应用程序的配置文件。
   </para>
  </note>
  <note>
   <para>
    如果 ini 文件中的值包含任何非字母数字的字符，需要将其括在双引号中（"）。
   </para>
  </note>
  <note>
   <simpara>
    有些保留字不能作为 ini
    文件中的键名，包括：<literal>null</literal>、<literal>yes</literal>、<literal>no</literal>、<literal>true</literal>、<literal>false</literal>、<literal>on</literal>、<literal>off</literal>、<literal>none</literal>。除非使用
    <constant>INI_SCANNER_TYPED</constant> 模式，否则
    <literal>null</literal>、<literal>off</literal>、<literal>no</literal> 和
    <literal>false</literal> 的值等效于
    <literal>""</literal>，<literal>on</literal>、<literal>yes</literal> 和 <literal>true</literal>
    的值等效于 <literal>"1"</literal>。字符 <literal>?{}|&amp;~!()^"</literal>
    也不能用在键名的任何地方，而且这些字符在选项值中有着特殊的意义。
   </simpara>
  </note>
  <note>
   <para>
    不带等号的条目会忽略。例如“foo”会忽略，而“bar =”将会解析并添加空值。例如，会忽略
    MySQL 在 <filename>my.cnf</filename> 中不带值的“no-auto-rehash”设置。
   </para>
  </note>
  <note>
   <para>
    ini 文件通常被 Web 服务器视为纯文本，因此在请求时会提供给浏览器。这意味着为了安全起见，必须将 ini
    文件保存在 docroot 之外，或者重新配置 Web 服务器，不会提供这些文件。如果不这么做，可能会带来安全风险。
   </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
-->