php · lacatoire · Aug 31, 2026
@@ -1,76 +1,72 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 4a87d61dbfcaddeafeebe5fd9546c5d9c6bc9ea2 Maintainer: lex Status: ready -->
+<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: lex Status: ready -->
 <!-- Reviewed: no -->
 <book xml:id="book.yaconf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <?phpdoc extension-membership="pecl" ?>
- <title>Модуль ini-конфигураций Yaconf</title>
+ <title>Yaconf</title>
  <titleabbrev>Yaconf</titleabbrev>
 
  <preface xml:id="intro.yaconf">
   &reftitle.intro;
-  <para>
-   Модуль <literal>Yet Another Configurations Container</literal>,
-   или <acronym>Yaconf</acronym>, — ещё один контейнер конфигураций,
-   который разбирает <literal>INI</literal>-файлы и сохраняет результат
-   в PHP при запуске, результат сохраняется на протяжении жизненного цикла PHP.
-  </para>
-  <para>
-   Yaconf-контейнер сохраняет каждую конфигурацию
-   как интернированную строку или неизменяемый массив. Для таких данных не ведётся
-   подсчёт ссылок, как при работе механизма refcount. Поэтому <acronym>Yaconf</acronym>-конфигурации
-   извлекаются быстро — близко к механизму zero-copy по приросту производительности.
-  </para>
-  <para>
-   Yaconf поддерживает в <literal>INI</literal>-файлах разделы и наследование разделов конфигураций.
-   Модуль Yaconf поддерживает автоматическую перезагрузку конфигураций после изменений <literal>INI</literal>-файлов,
-   если PHP собрали в непотокобезопасном режиме — без поддержки ZTS.
-  </para>
-  <para>
+  <simpara>
+   Модуль <literal>Yet Another Configurations Container</literal>
+   (<acronym>Yaconf</acronym>) — контейнер конфигураций. Он разбирает
+   <literal>INI</literal>-файлы при запуске PHP и хранит результат
+   в постоянной памяти в течение всего жизненного цикла PHP, поэтому
+   каждое обращение — это быстрый поиск в хеш-таблице без обращений
+   к файлам и без разбора на каждый запрос.
+  </simpara>
+  <simpara>
+   Yaconf хранит каждую конфигурацию как интернированную строку или
+   неизменяемый массив. Для таких данных не ведётся подсчёт ссылок,
+   поэтому извлечение конфигурации из Yaconf фактически обходится
+   без копирования. Начиная с Yaconf 1.2.0 всё разобранное дерево
+   конфигураций вдобавок уплотняется в один непрерывный блок, что
+   снижает накладные расходы по памяти и улучшает локальность кеша.
+  </simpara>
+  <simpara>
+   Разобранная конфигурация находится в постоянной памяти, которую все
+   рабочие процессы PHP-FPM разделяют механизмом копирования при записи:
+   пока файл конфигурации не изменился, рабочие процессы делят одни
+   и те же физические страницы памяти, сколько бы их ни запустили.
+  </simpara>
+  <simpara>
+   Yaconf поддерживает в INI-файлах разделы и наследование разделов.
+   В сборках без ZTS модуль вдобавок автоматически перезагружает файлы
+   при их изменении; в потокобезопасных сборках (ZTS) конфигурации
+   загружаются при запуске, и чтобы подхватить изменения, требуется
+   перезапуск.
+  </simpara>
+  <simpara>
+   Начиная с Yaconf 1.2.0 подкаталоги настроенного каталога загружаются
+   рекурсивно, на глубину до 16 уровней, и адресуются с названием каталога
+   как уровнем ключа: например, вызов
+   <literal>Yaconf::get("users.database.master")</literal> читает ключ
+   <literal>master</literal> из файла <filename>database.ini</filename>,
+   который положили в подкаталог <filename>users/</filename>.
+  </simpara>
+  <simpara>
+   Хранение чувствительных конфигураций вне веб-дерева вдобавок снижает
+   поверхность атаки. Файлы конфигураций под корнем веб-сервера
+   злоумышленник может получить, например через уязвимость раскрытия
+   файлов. С модулем Yaconf файлы <filename>.ini</filename> вместо этого
+   размещают в каталоге, который доступен на чтение только root,
+   например <filename>/etc/yaconf</filename>: главный процесс PHP-FPM
+   загружает конфигурации при запуске службы, а порождённым рабочим
+   процессам, которые работают от непривилегированного пользователя
+   и обрабатывают веб-запросы, доступ к этому каталогу не нужен
+   и не предоставляется.
+  </simpara>
+  <simpara>
    Для работы модуля Yaconf требуется PHP 7.0 или выше.
-  </para>
-  <example>
-   <title>Пример INI-файла</title>
-   <programlisting role="ini">
-<![CDATA[
-;Простая пара ключ-значение
-key=val
-
-;Хеш
-hash.a=val
-
-;Массив
-arr.0=val
-;или так
-arr[]=val
-
-;PHP-константа
-version=PHP_VERSION
-
-;Переменная окружения
-env=${PATH}
-]]>
-   </programlisting>
-  </example>
-  <example>
-   <title>Пример INI-файла с разделами</title>
-   <programlisting role="ini">
-<![CDATA[
-[SectionA]
-key=val
-hash.a=val
-
-;Раздел SectionB наследует раздел SectionA
-[SectionB:SectionA]
-key=new_val ;переопределение параметра key из раздела SectionA
-]]>
-   </programlisting>
-  </example>
+  </simpara>
  </preface>
 
  &reference.yaconf.setup;
  &reference.yaconf.yaconf;
 
 </book>
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: lex Status: ready -->
+<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: lex Status: ready -->
 <!-- Reviewed: no -->
 
 <section xml:id="yaconf.configuration" xmlns="http://docbook.org/ns/docbook">
@@ -19,14 +19,14 @@
     </thead>
     <tbody>
      <row>
-      <entry><link linkend="ini.yaconf.check-delay">yaconf.check_delay</link></entry>
-      <entry>300</entry>
+      <entry><link linkend="ini.yaconf.directory">yaconf.directory</link></entry>
+      <entry><literal>""</literal></entry>
       <entry><constant>INI_SYSTEM</constant></entry>
       <entry><!-- leave empty, this will be filled by an automatic script --></entry>
      </row>
      <row>
-      <entry><link linkend="ini.yaconf.directory">yaconf.directory</link></entry>
-      <entry>/tmp/conf/</entry>
+      <entry><link linkend="ini.yaconf.check-delay">yaconf.check_delay</link></entry>
+      <entry><literal>300</literal></entry>
       <entry><constant>INI_SYSTEM</constant></entry>
       <entry><!-- leave empty, this will be filled by an automatic script --></entry>
      </row>
@@ -39,30 +39,84 @@
 
  <para>
   <variablelist>
-   <varlistentry xml:id="ini.yaconf.check-delay">
+   <varlistentry xml:id="ini.yaconf.directory">
      <term>
-      <parameter>yaconf.check_delay</parameter>
-      <type>int</type>
+      <parameter>yaconf.directory</parameter>
+      <type>string</type>
      </term>
      <listitem>
-      <para>
-        Интервал времени, в течение которого Yaconf будет определять изменение файла ini (по времени изменения директории),
-        если установлен ноль, требуется перезапуск PHP для перезагрузки конфигураций.
-      </para>
+      <simpara>
+       Каталог, в котором размещают все INI-файлы конфигураций. Загружаются
+       только файлы с расширением <filename>.ini</filename>.
+       Подкаталоги загружаются рекурсивно, на глубину до 16 уровней; каждый
+       из них выступает уровнем ключа, поэтому файл
+       <filename>database.ini</filename>, который положили в подкаталог
+       <filename>users/</filename>, адресуют как
+       <literal>"users.database"</literal>. Доступно начиная с Yaconf 1.2.0;
+       раньше загружались только файлы непосредственно в самом каталоге.
+      </simpara>
+      <simpara>
+       Примеры ниже предполагают, что в настроенном каталоге лежит следующий
+       файл <filename>database.ini</filename>, а рядом с ним —
+       файл <filename>features.ini</filename> с настройками отдельных
+       возможностей.
+      </simpara>
+      <example>
+       <title>Синтаксис INI-файла</title>
+       <programlisting role="ini">
+<![CDATA[
+; database.ini
+name=production                        ; скалярное значение
+version=PHP_VERSION                    ; PHP-константы раскрываются
+connection_string=${DATABASE_URL}      ; переменные окружения раскрываются
+options.max_connections=50             ; вложенный ключ хеша
+options.timeout=30
+
+; элементы массива, обе записи равнозначны
+replicas.0=replica-1.example.com
+replicas[]=replica-2.example.com
+]]>
+       </programlisting>
+      </example>
+      <example>
+       <title>Пример разделов INI-файла</title>
+       <programlisting role="ini">
+<![CDATA[
+; features.ini
+[default]
+cache_enabled=on
+rate_limit=100
+
+; раздел «premium» наследует каждый ключ раздела «default»
+; и переопределяет те, которые задаёт заново
+[premium:default]
+rate_limit=1000
+]]>
+       </programlisting>
+      </example>
      </listitem>
-    </varlistentry>
-    <varlistentry xml:id="ini.yaconf.directory">
+   </varlistentry>
+   <varlistentry xml:id="ini.yaconf.check-delay">
      <term>
-      <parameter>yaconf.directory</parameter>
-      <type>string</type>
+      <parameter>yaconf.check_delay</parameter>
+      <type>int</type>
      </term>
      <listitem>
-      <para>
-        Путь к директории, в которой находятся все файлы конфигурации INI.
-      </para>
+      <simpara>
+       Интервал в секундах, с которым Yaconf проверяет, изменился ли какой-нибудь
+       из загруженных INI-файлов, и перезагружает изменившиеся; изменение
+       определяют сравнением времени изменения каталогов.
+       Значение <literal>0</literal> заставляет Yaconf проверять при каждом запросе.
+      </simpara>
+      <note>
+       <simpara>
+        Директиву регистрируют только в сборках без ZTS. В потокобезопасных
+        сборках (ZTS) конфигурации загружаются при запуске, автоматическая
+        перезагрузка недоступна; чтобы подхватить изменения, PHP перезапускают.
+       </simpara>
+      </note>
      </listitem>
-    </varlistentry>
-
+   </varlistentry>
   </variablelist>
  </para>
 </section>

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: aebf045bfb7f4f2350db5e1e908cf290be334075 Maintainer: lex Status: ready -->
+<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: lex Status: ready -->
 <!-- Reviewed: no -->
 <chapter xml:id="yaconf.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.setup;
@@ -13,6 +13,10 @@
 
  <section xml:id="yaconf.installation">
   &reftitle.install;
+  <simpara>
+   Модуль Yaconf устанавливают одним из трёх способов: через PECL, через PIE
+   или сборкой из исходного кода.
+  </simpara>
   <para>
    &pecl.moved;
   </para>
@@ -23,6 +27,42 @@
   <para>
    &pecl.windows.download.avail;
   </para>
+  <example>
+   <title>Установка Yaconf через PECL</title>
+   <programlisting role="shell">
+<![CDATA[
+pecl install yaconf
+]]>
+   </programlisting>
+  </example>
+  <simpara>
+   Начиная с Yaconf 1.2.0 модуль устанавливают установщиком PHP-модулей
+   &link.pie;, для чего выполняют в командной строке следующее.
+  </simpara>
+  <example>
+   <title>Установка Yaconf через PIE</title>
+   <programlisting role="shell">
+<![CDATA[
+pie install laruence/yaconf
+]]>
+   </programlisting>
+  </example>
+  <simpara>
+   Исходный код размещается на
+   <link xlink:href="&url.git.hub;laruence/yaconf">GitHub</link>. Чтобы собрать
+   модуль из исходного кода, выполняют в командной строке следующее, заменив
+   пути на пути локальной установки PHP.
+  </simpara>
+  <example>
+   <title>Сборка Yaconf из исходного кода</title>
+   <programlisting role="shell">
+<![CDATA[
+/path/to/phpize
+./configure --with-php-config=/path/to/php-config
+make && make install
+]]>
+   </programlisting>
+  </example>
  </section>
 
  &reference.yaconf.ini;