php-doc-ru/install/ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 9ab074d32484672f93e5d822f42fb94ae9088207 Maintainer: mch Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>Конфигурация времени выполнения</title>

 <sect1 xml:id="configuration.file">
  <title>Файл конфигурации</title>

  <simpara>
   Файл конфигурации (&php.ini;)
   считывается при запуске PHP. Для версий серверных модулей PHP
   это происходит только один раз при запуске веб-сервера. Для
   <acronym>CGI</acronym>- и <acronym>CLI</acronym>-версии PHP —
   при каждом вызове.
  </simpara>
  <para>
   PHP ищёт файл &php.ini; в следующих местах (по порядку поиска):
   <itemizedlist>
    <listitem>
     <simpara>
      По расположению конкретного SAPI-модуля (директива <literal>PHPIniDir</literal>
      в веб-сервере Apache 2, параметр командной строки <literal>-c</literal> в CGI- и CLI-интерфейсе)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Переменная окружения <varname>PHPRC</varname>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Расположение файла <literal>php.ini</literal> зависит от версии PHP.
      Корень ключей реестра ОС зависит от разрядности ОС и PHP. При установке 32-разрядного PHP
      на 32-разрядной ОС Windows или 64-разрядного PHP на 64-разрядной Windows
      PHP исследует раздел реестра <literal>[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>,
      при установке 32-разрядного PHP на 64-разрядной Windows —
      раздел <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>.
      PHP проверяет следующие разделы реестра по порядку для установок
      с одинаковой разрядностью:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal>
      и <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>,
      где x, y и z подразумевают мажорную, минорную и точечную версии выпусков PHP.
      Для 32-разрядного PHP на 64-разрядной ОС Windows ключи реестра будут другими:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal>
      и <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>.
      PHP будет использовать первый найденный ключ как расположение файла
      <literal>php.ini</literal>, если ключи содержат
      значение <literal>IniFilePath</literal> (только для ОС Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Разделы <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>
      или <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, значение
      <literal>IniFilePath</literal> (только для Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Текущая рабочая директория (исключая CLI-интерфейс).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Директория веб-сервера (для SAPI-модулей) или директория PHP
      (иначе в Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Директория ОС Windows (<filename class="directory">C:\windows</filename>
      или <filename class="directory">C:\winnt</filename>) (для Windows)
      или опция времени компиляции <literal>--with-config-file-path</literal>.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Вместо файла &php.ini; PHP будет работать с файлом
   <filename>php-SAPI.ini</filename>, где SAPI — текущий интерфейс,
   например <filename>php-cli.ini</filename> или <filename>php-apache.ini</filename>,
   если файл SAPI-интерфейса существует.
   Название SAPI-интерфейса между веб-сервером и PHP
   узнают через функцию <function>php_sapi_name</function>.
  </para>
  <note>
   <para>
    Веб-сервер Apache изменяет текущую директорию на корневую при запуске,
    в результате чего PHP считывает файл &php.ini; из корневой файловой системы, если файл существует.
   </para>
  </note>
  <simpara>
   В значениях конфигурации в файле &php.ini; разрешается ссылаться на значения переменных окружения,
   как показывает следующий пример. Начиная PHP 8.3.0 доступно определение резервных значений,
   которые директивы принимают, если сослались на неопределённую
   переменную.
  </simpara>
  <example>
   <title>Переменные окружения в файле &php.ini;</title>
    <programlisting role="ini">
<![CDATA[
; Переменную PHP_MEMORY_LIMIT получили из окружения
memory_limit = ${PHP_MEMORY_LIMIT}
; Резервное значение директивы будет равняться 30, если переменную окружения PHP_MAX_EXECUTION_TIME не определили
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
]]>
   </programlisting>
  </example>
  <para>
   Директивы файла &php.ini;, которые обрабатываются модулями, описывают
   страницы модулей. Список директив ядра приводит
   приложение «<link linkend="ini">Директивы php.ini</link>».
   Не каждая PHP-директива задокументирована в руководстве:
   полный список доступных в установленной версии PHP директив
   изложили в подробных комментариях файла &php.ini;.
   <link xlink:href="&url.php.git.phpini;">Последнюю версию &php.ini;</link>
   содержит Git-репозиторий.
  </para>
  <para>
   <example>
    <title>Пример &php.ini;</title>
    <programlisting role="ini">
<![CDATA[
; любой текст в строке после точки с запятой (;) без кавычек игнорируется
[php] ; маркеры разделов (текст в квадратных скобках) также игнорируется
; Могут быть установлены следующие логические значения:
;    true, on, yes
; или false, off, no, none
register_globals = off
track_errors = yes

; вы можете заключать строки в двойные кавычки
include_path = ".:/usr/local/lib/php"

; обратный слеш обрабатывается так же, как любые другие символы
include_path = ".;c:\php\lib"
]]>
    </programlisting>
    <!-- TODO: добавить больше информации о значениях и выражениях -->
   </example>
  </para>
  <para>
   Возможно обращаться к существующим ini-переменным из
   ini-файлов. Пример: <literal>open_basedir = ${open_basedir}
   ":/new/dir"</literal>.
  </para>
  <sect2 xml:id="configuration.file.scan">
   <title>Сканирование директорий</title>

   <para>
    Существует возможность сконфигурировать PHP для сканирования директорий
    в поисках .ini-файлов после считывания &php.ini;. Это можно сделать
    на моменте компиляции, указав опцию <option role="configure">--with-config-file-scan-dir</option>.
    Сканирование директорий может быть переопределено
    во время исполнения установкой переменной среды <varname>PHP_INI_SCAN_DIR</varname>.
   </para>

   <para>
    Можно сканировать несколько директорий, разделяя их разделителем,
    используемом в вашей операционной системе (<literal>;</literal> в Windows, NetWare
    и RISC OS; <literal>:</literal> на всех остальных платформах; в PHP есть
    константа <constant>PATH_SEPARATOR</constant>, которую можно использовать)
    Если <varname>PHP_INI_SCAN_DIR</varname> пуста, то PHP также будет
    сканировать директорию, заданную на этапе компиляции с помощью
    <option role="configure">--with-config-file-scan-dir</option>.
   </para>

   <para>
    В каждой директории PHP сканирует все файлы заканчивающиеся на <literal>.ini</literal>
    в алфавитном порядке. Список всех загруженных файлов в том порядке,
    в котором они были загружены, доступен с помощью функции
    <function>php_ini_scanned_files</function>, либо при запуске PHP с опцией <option>--ini</option>.
   </para>

   <informalexample>
    <screen>
<![CDATA[
Допустим, что PHP сконфигурирован с --with-config-file-scan-dir=/etc/php.d,
и разделитель путей :...

$ php
  PHP загрузит все файлы /etc/php.d/*.ini как конфигурационные.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP загрузит все файлы /usr/local/etc/php.d/*.ini как конфигурационные.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP загрузит все файлы /etc/php.d/*.ini, а потом
  /usr/local/etc/php.d/*.ini как конфигурационные.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP загрузит все файлы /usr/local/etc/php.d/*.ini, а потом
  /etc/php.d/*.ini как конфигурационные.
]]>
    </screen>
   </informalexample>
  </sect2>
 </sect1>

 <sect1 xml:id="configuration.file.per-user">
  <title>Файлы .user.ini</title>

  <simpara>
   Включена поддержка INI-файлов в стиле .htaccess на
   уровне каталога. Эти файлы обрабатываются <emphasis>только</emphasis> CGI/FastCGI SAPI.
   Эта функция делает ненужным модуль PECL htscanner.
   Если PHP работает как модуль Apache, то для достижения того же эффекта,
   работают с файлами &htaccess;.
  </simpara>

  <simpara>
   В дополнение к основному файлу &php.ini; PHP ищет INI-файлы в каждой
   директории, начиная с директории запрошенного PHP-файла и продолжает
   поиск до корневой директории (установленной в
   элементе <varname>$_SERVER['DOCUMENT_ROOT']</varname>). Если PHP-файл лежит
   вне корневой директории, то сканируется только его директория.
  </simpara>
  <simpara>
   Только INI-настройки
   с режимами <constant>INI_PERDIR</constant>
   и <constant>INI_USER</constant> распознаются в INI-файлах в стиле .user.ini.
  </simpara>

  <simpara>
   Две новых INI-директивы —
   <link linkend="ini.user-ini.filename">user_ini.filename</link>
   и <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> —
   контролируют работу с пользовательскими INI-файлами.
  </simpara>

  <simpara>
   Директива <link linkend="ini.user-ini.filename">user_ini.filename</link> устанавливает имя файла,
   по которому PHP производит поиск в каждой директории; если установили пустую строку, PHP не производит поиск.
   Значение по умолчанию — <literal>.user.ini</literal>.
  </simpara>

  <simpara>
   Директива <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> устанавливает,
   насколько часто пользовательские INI-файлы будут обновляться. По умолчанию период обновления
   составляет 300 секунд (5 минут).
  </simpara>
 </sect1>

 <sect1 xml:id="configuration.changes.modes">
  <title>Места установки параметров конфигурации</title>

  <para>
   Режимы определяют, когда и где разрешается или не разрешается устанавливать
   PHP-директиву, и у каждой директивы руководства свой режим.
   Например, одни настройки разрешается устанавливать в PHP-скрипте
   функцией <function>ini_set</function>, тогда как другим нужен файл
   &php.ini; или &httpd.conf;.
  </para>

  <para>
   Приведём пример. Директива
   <link linkend="ini.output-buffering">output_buffering</link> соответствует
   режиму <constant>INI_PERDIR</constant>, поэтому её нельзя устанавливать
   функцией <function>ini_set</function>, а директива
   <link linkend="ini.display-errors">display_errors</link> соответствует
   режиму <constant>INI_ALL</constant>, поэтому настройку разрешается устанавливать где угодно,
   включая функцию <function>ini_set</function>.
  </para>

  <para>
   <variablelist>
<!--
Replace everything inside the <variablelist> element with an <xi:include>
once libxml2 gets XInclude 1.1 attribute copying support.
The below <xi:include> will include the appropriate elements
but needs all top-level xml:id's removed (see XInclude 1.1 set-xml-id).

    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('constant.ini-mode')/*)"><xi:fallback/></xi:include>
-->
    <title>Константы INI-режима</title>
    <varlistentry>
     <term>
      <constant>INI_USER</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Запись разрешается устанавливать в пользовательских скриптах (например, функцией
       <function xmlns="http://docbook.org/ns/docbook">ini_set</function>)
       или в <link xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.windows">реестре Windows</link>.
       Запись разрешается устанавливать в файле &user-ini;.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_PERDIR</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Запись разрешается устанавливать в файлах &php.ini;, &htaccess;, &httpd.conf; или &user-ini;.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_SYSTEM</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Запись разрешается устанавливать в файле &php.ini; или &httpd.conf;.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_ALL</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Запись разрешается устанавливать где угодно.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>

 <sect1 xml:id="configuration.changes">
  <title>Как изменить настройки конфигурации</title>

  <sect2 xml:id="configuration.changes.apache">
   <title>Запуск PHP в качестве модуля Apache</title>
   <simpara>
    Когда PHP работает как модуль Apache,
    настройки конфигурации изменяют через директивы в файлах конфигурации Apache
    (например, &httpd.conf;) и файлах &htaccess;. Для этого потребуются
    привилегии «AllowOverride Options» или «AllowOverride All».
   </simpara>

   <para>
    В Apache предусмотрели директивы, которые разрешают
    изменить конфигурацию PHP в файлах конфигурации Apache.
    Список директив <constant>INI_ALL</constant>, <constant>INI_PERDIR</constant>
    и <constant>INI_SYSTEM</constant> смотрите в приложении
    «<link linkend="ini.list">Список директив php.ini</link>».
   </para>

   <para>
    <variablelist>
     <varlistentry>
      <term>
       <systemitem role="directive">php_value</systemitem>
       <parameter>name</parameter>
       <parameter>value</parameter>
      </term>
      <listitem>
       <para>
        Устанавливает значение директивы.
        Разрешено указывать только с директивами
        типа <constant>INI_ALL</constant> и <constant>INI_PERDIR</constant>.
        Чтобы очистить ранее установленное значение,
        в качестве значения указывают <literal>none</literal>.
       </para>
       <note>
        <simpara>
         Не используйте директиву
         <systemitem role="directive">php_value</systemitem> для установки логических значений.
         Эту функцию выполняет
         директива <systemitem role="directive">php_flag</systemitem>; её описание ниже.
        </simpara>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_flag</systemitem>
       <parameter>name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Устанавливает директивам логические значения.
        Разрешено указывать только с директивами типа <constant>INI_ALL</constant> и
        <constant>INI_PERDIR</constant>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_value</systemitem>
       <parameter>name</parameter>
       <parameter>value</parameter>
      </term>
      <listitem>
       <para>
        Устанавливает значение директивы.
        <emphasis>Нельзя указывать</emphasis> в файлах &htaccess;.
        Директивы любого типа, установленные через директиву
        <systemitem role="directive">php_admin_value</systemitem>,
        нельзя переопределять через файлы &htaccess; или функцию <function>ini_set</function>.
        Чтобы очистить ранее установленное значение, указывают значение <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>
        Устанавливает директивам логические значения.
        <emphasis>Нельзя указывать</emphasis> в файлах &htaccess;.
        Директивы любого типа, установленные через директиву
        <systemitem role="directive">php_admin_flag</systemitem>,
        нельзя переопределять через файлы &htaccess; или функцию <function>ini_set</function>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    <example>
     <title>Пример конфигурации 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>
     PHP-константы недоступны вне PHP. Например, в
     &httpd.conf; вы не можете использовать константы PHP
     такие как <constant>E_ALL</constant> или <constant>E_NOTICE</constant>,
     чтобы установить директиву <link linkend="ini.error-reporting">error_reporting</link>,
     так как они не будут иметь значения и будут приравниваться к <emphasis>0</emphasis>.
     Используйте вместо этого соответствующие значения типа bitmask (битовая маска).
     Эти константы могут быть использованы в &php.ini;
    </para>
   </caution>
  </sect2>

  <sect2 xml:id="configuration.changes.windows">
   <title>Изменение конфигурации PHP через реестр Windows</title>
   <simpara>
    При использовании PHP в Windows значения конфигурации могут быть
    изменены на уровне директории посредством реестра Windows.
    Значения конфигурации хранятся в ключе реестра
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,
    в подключах, включающих полный путь. Например, значения конфигурации для директории
    <literal>c:\inetpub\wwwroot</literal> могут храниться в ключе
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot</literal>.
    Настройки для директории будут действительны для любых скриптов, запущенных из
    этой директории или её поддиректории. Значения ключа должны иметь название
    конфигурационной директивы PHP и строковое значение.
    PHP-константы в значениях игнорируются.
    Однако только значения конфигурации, изменяемые в
    <constant>INI_USER</constant> могут быть установлены таким образом,
    значения же <constant>INI_PERDIR</constant> не могут,
    потому что эти значения конфигурации перечитываются для каждого запроса.
   </simpara>
  </sect2>

  <sect2 xml:id="configuration.changes.other">
   <title>Другие интерфейсы в PHP</title>
   <para>
    Независимо от того, как вы запускаете PHP, вы можете изменять некоторые значения
    во время выполнения ваших скриптов c помощью <function>ini_set</function>. Для более
    детальной информации смотрите документацию на странице функции <function>ini_set</function>.
   </para>
   <para>
    Если вам интересен полный список конфигурационных настроек
    вашей системы с текущими значениями, то вы можете запустить функцию
    <function>phpinfo</function> и просмотреть результирующую
    страницу. Вы также можете получить доступ к значениям индивидуально сконфигурированных
    директив в процессе выполнения, используя <function>ini_get</function> или
    <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
-->