parse-ini-file.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: a5346daf2bb2fab250fa03f0f6639a408d0b2240 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,mumumu -->
<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>
   成功した場合に設定を連想配列形式で返します。
   失敗した場合に &false; を返します。
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><filename>sample.ini</filename> の内容</title>
    <programlisting>
<![CDATA[
; これは設定ファイルのサンプルです。
; 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');

// セクションを無視してパースします。
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// セクションを意識してパースします。
$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 へのパスを the php_ini_loaded_file() 関数で取得します
$ini_path = php_ini_loaded_file();

// php.ini をパースします
$ini = parse_ini_file($ini_path);

// 結果を表示して比較します。get_cfg_var() を使用すると、
// ここでパースして読み込んだのと同じ結果が得られることに注意しましょう
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>ini ファイルの値の補完</title>
    <para>
     定数を評価することに加えて、文字によっては ini ファイルの値として特別な意味を持つものがあります。
     さらに、環境変数や以前定義された設定オプション
     (<function>get_cfg_var</function> も参照ください) は、
     <code>${}</code> を使って読み取ることができます。
    </para>
    <programlisting>
<![CDATA[
; | は ビット演算の OR
is used for bitwise OR
three = 2|3

; & は ビット演算の AND
four = 6&5

; ^ は ビット演算の XOR
five = 3^6

; ~ は ビット演算の NOT
negative_two = ~1

; () はグループ化に使います
seven = (8|7)&(6|5)

; 環境変数 PATH を展開します
path = ${PATH}

; 設定オプション 'memory_limit' を展開します
configured_memory_limit = ${memory_limit}
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>文字をエスケープする</title>
    <para>
     文字によっては、ダブルクォートで囲まれた文字列の中で特別な意味を持つ場合があり、
     その場合、バックスラッシュでエスケープしなければなりません。
     特別な意味を持つのは、文字列の境目の印となるダブルクォート <code>"</code>、
     および、バックスラッシュ <code>\</code> (この文字の後に特別な文字がひとつ続きます) そのものです。
    </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>
     Windows ライクなパスについては例外があります。
     クォートされた文字列のすぐ後に改行文字が続いた場合、
     末尾のバックスラッシュはエスケープする必要がないというものです。
    </para>
    <programlisting>
<![CDATA[
save_path = "C:\Temp\"
]]>
    </programlisting>
    <para>
     複数行にまたがる値で、改行文字が直後にあるダブルクォート文字をエスケープする必要がある場合、
     次のようにして値を連結することでそれを実現できます。
     (ダブルクォートで囲まれた文字列がひとつあり、その直後にもうひとつの文字列が続きます)
    </para>
    <programlisting>
<![CDATA[
long_text = "Lorem \"ipsum\"""
 dolor" ; Results in: Lorem "ipsum"\n dolor
]]>
    </programlisting>
    <para>
     特別な意味を持つ別の文字として、<code>$</code> (ドル記号) があります。
     これは、開き括弧が続く場合、エスケープしなければいけません:
    </para>
    <programlisting>
<![CDATA[
code = "\${test}"
]]>
    </programlisting>
    <para>
     文字のエスケープは、
     <constant>INI_SCANNER_RAW</constant> モードではサポートされていません。
     (このモードでは、全ての文字が "そのまま" 処理されます)
    </para>
    <para>
     ini ファイルのパーサーは、標準的なエスケープシーケンス
     (<code>\n</code>, <code>\t</code>, など) をサポートしていないことに注意して下さい。
     そのサポートが必要な場合、<function>parse_ini_file</function> の処理結果を
     <function>stripcslashes</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> などです。
    <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> となります。
    ただし、<constant>INI_SCANNER_TYPED</constant> モードを使っている場合は別です。
    次の文字 <literal>?{}|&amp;~!()^"</literal> は、キーで使ってはいけません。
    また、値の中で特別な意味を持ちます。
   </simpara>
  </note>
  <note>
   <para>
    等号が含まれないエントリは無視されます。
    つまり、"foo" というエントリは無視されますが、
    "bar =" は、空の値を持つエントリとして追加されます。
    たとえば MySQL の <filename>my.cnf</filename> には
    "no-auto-rehash" という設定項目がありますが、この項目には何も値を設定しません。
    そのため、この項目は無視されます。
   </para>
  </note>
  <note>
   <para>
    ini ファイルは、一般的にWebサーバーからはプレーンテキストとして扱われます。
    よって、ini ファイルにリクエストがあった場合、ブラウザにそのまま表示されます。
    これは、セキュリティを考慮すると、
    ini ファイルはドキュメントルートの外側に置くか、
    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
-->