parse-ini-file.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a5346daf2bb2fab250fa03f0f6639a408d0b2240 Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<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> загружает
   ini-файл, указанный в аргументе <parameter>filename</parameter>,
   и возвращает его настройки в виде ассоциативного массива.
  </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[
; Это пример файла настроек
; Комментарии начинаются с ';', как в 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-файлах, так что если вы объявите константу
     в виде значения для ini-файла до вызова <function>parse_ini_file</function>,
     то константа будет корректно обработана. Только значения опций будут обрабатываться и значение должно быть просто константой.
     Например:
    </para>
    <programlisting role="php">
<![CDATA[
<?php

define('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] => Птица додо
    [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] => Птица додо
        )

    [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>Обработка файла php.ini функцией <function>parse_ini_file</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// Простая функция для сравнения результатов
function yesno($expression)
{
    return($expression ? 'Да' : 'Нет');
}

// Получаем путь к php.ini с помощью функции php_ini_loaded_file()
$ini_path = php_ini_loaded_file();

// Обрабатываем php.ini
$ini = parse_ini_file($ini_path);

// Выводим и сравниваем значения, учтите, что использование get_cfg_var()
// даст одинаковые результаты для используемых здесь значений parsed (загруженное из файла) и loaded (используемое в данный момент)
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 = Да
(loaded) magic_quotes_gpc = Да
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Интерполяция значений</title>
    <para>
     Помимо оценки констант, некоторые символы имеют особое значение в значении ini-файлах.
     Кроме того, переменные среды и ранее определённые параметры конфигурации (смотрите <function>get_cfg_var</function>)
     могут быть прочитаны с использованием синтаксиса <code>${}</code>.
    </para>
    <programlisting>
<![CDATA[
; | используется для побитового ИЛИ
three = 2|3

; & используется для побитового AND
four = 6&5

; ^ используется для побитового XOR
five = 3^6

; ~ используется для побитового отрицания
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 = "Она сказала \"Именно моя точка зрения\"." ; Результатом является строка с кавычками.
hint = "Используйте \\\", чтобы избежать двойных кавычек" ; Результат: Используйте \", чтобы избежать двойных кавычек
]]>
    </programlisting>
    <para>
     Для путей, подобных Windows, сделано исключение: можно не экранировать обратную косую черту в конце,
     если за строкой в кавычках следует разрыв строки:
    </para>
    <programlisting>
<![CDATA[
save_path = "C:\Temp\"
]]>
    </programlisting>
    <para>
     Если нужно экранировать двойные кавычки, за которыми следует перенос строки в многострочном значении,
     можно использовать конкатенацию значений следующим образом (за одной строкой в двойных кавычках непосредственно следует другая):
    </para>
    <programlisting>
<![CDATA[
long_text = "Lorem \"ipsum\"""
 dolor" ; Результат: 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 есть опция "no-auto-rehash", устанавливаемая в <filename>my.cnf</filename>,
    которая не имеет значения и игнорируется.
   </para>
  </note>
  <note>
   <para>
    ini-файлы обычно обрабатываются веб-серверами как простой текст и, таким образом, по запросу передаются браузерам.
    Это означает, что в целях безопасности вы должны либо хранить свои ini-файлы вне корневого каталога документов, либо перенастроить
    веб-сервер, чтобы они не обслуживались. Невыполнение любого из этих требований может создать угрозу безопасности.
   </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
-->