diff --git a/reference/yaconf/book.xml b/reference/yaconf/book.xml index 83ee2b0fc1..8abf1a925e 100644 --- a/reference/yaconf/book.xml +++ b/reference/yaconf/book.xml @@ -1,76 +1,72 @@ - + - Модуль ini-конфигураций Yaconf + Yaconf Yaconf &reftitle.intro; - - Модуль Yet Another Configurations Container, - или Yaconf, — ещё один контейнер конфигураций, - который разбирает INI-файлы и сохраняет результат - в PHP при запуске, результат сохраняется на протяжении жизненного цикла PHP. - - - Yaconf-контейнер сохраняет каждую конфигурацию - как интернированную строку или неизменяемый массив. Для таких данных не ведётся - подсчёт ссылок, как при работе механизма refcount. Поэтому Yaconf-конфигурации - извлекаются быстро — близко к механизму zero-copy по приросту производительности. - - - Yaconf поддерживает в INI-файлах разделы и наследование разделов конфигураций. - Модуль Yaconf поддерживает автоматическую перезагрузку конфигураций после изменений INI-файлов, - если PHP собрали в непотокобезопасном режиме — без поддержки ZTS. - - + + Модуль Yet Another Configurations Container + (Yaconf) — контейнер конфигураций. Он разбирает + INI-файлы при запуске PHP и хранит результат + в постоянной памяти в течение всего жизненного цикла PHP, поэтому + каждое обращение — это быстрый поиск в хеш-таблице без обращений + к файлам и без разбора на каждый запрос. + + + Yaconf хранит каждую конфигурацию как интернированную строку или + неизменяемый массив. Для таких данных не ведётся подсчёт ссылок, + поэтому извлечение конфигурации из Yaconf фактически обходится + без копирования. Начиная с Yaconf 1.2.0 всё разобранное дерево + конфигураций вдобавок уплотняется в один непрерывный блок, что + снижает накладные расходы по памяти и улучшает локальность кеша. + + + Разобранная конфигурация находится в постоянной памяти, которую все + рабочие процессы PHP-FPM разделяют механизмом копирования при записи: + пока файл конфигурации не изменился, рабочие процессы делят одни + и те же физические страницы памяти, сколько бы их ни запустили. + + + Yaconf поддерживает в INI-файлах разделы и наследование разделов. + В сборках без ZTS модуль вдобавок автоматически перезагружает файлы + при их изменении; в потокобезопасных сборках (ZTS) конфигурации + загружаются при запуске, и чтобы подхватить изменения, требуется + перезапуск. + + + Начиная с Yaconf 1.2.0 подкаталоги настроенного каталога загружаются + рекурсивно, на глубину до 16 уровней, и адресуются с названием каталога + как уровнем ключа: например, вызов + Yaconf::get("users.database.master") читает ключ + master из файла database.ini, + который положили в подкаталог users/. + + + Хранение чувствительных конфигураций вне веб-дерева вдобавок снижает + поверхность атаки. Файлы конфигураций под корнем веб-сервера + злоумышленник может получить, например через уязвимость раскрытия + файлов. С модулем Yaconf файлы .ini вместо этого + размещают в каталоге, который доступен на чтение только root, + например /etc/yaconf: главный процесс PHP-FPM + загружает конфигурации при запуске службы, а порождённым рабочим + процессам, которые работают от непривилегированного пользователя + и обрабатывают веб-запросы, доступ к этому каталогу не нужен + и не предоставляется. + + Для работы модуля Yaconf требуется PHP 7.0 или выше. - - - Пример INI-файла - - - - - - Пример INI-файла с разделами - - - - + &reference.yaconf.setup; &reference.yaconf.yaconf; + +
@@ -19,14 +19,14 @@ - yaconf.check_delay - 300 + yaconf.directory + "" INI_SYSTEM - yaconf.directory - /tmp/conf/ + yaconf.check_delay + 300 INI_SYSTEM @@ -39,30 +39,84 @@ - + - yaconf.check_delay - int + yaconf.directory + string - - Интервал времени, в течение которого Yaconf будет определять изменение файла ini (по времени изменения директории), - если установлен ноль, требуется перезапуск PHP для перезагрузки конфигураций. - + + Каталог, в котором размещают все INI-файлы конфигураций. Загружаются + только файлы с расширением .ini. + Подкаталоги загружаются рекурсивно, на глубину до 16 уровней; каждый + из них выступает уровнем ключа, поэтому файл + database.ini, который положили в подкаталог + users/, адресуют как + "users.database". Доступно начиная с Yaconf 1.2.0; + раньше загружались только файлы непосредственно в самом каталоге. + + + Примеры ниже предполагают, что в настроенном каталоге лежит следующий + файл database.ini, а рядом с ним — + файл features.ini с настройками отдельных + возможностей. + + + Синтаксис INI-файла + + + + + + Пример разделов INI-файла + + + + - - + + - yaconf.directory - string + yaconf.check_delay + int - - Путь к директории, в которой находятся все файлы конфигурации INI. - + + Интервал в секундах, с которым Yaconf проверяет, изменился ли какой-нибудь + из загруженных INI-файлов, и перезагружает изменившиеся; изменение + определяют сравнением времени изменения каталогов. + Значение 0 заставляет Yaconf проверять при каждом запросе. + + + + Директиву регистрируют только в сборках без ZTS. В потокобезопасных + сборках (ZTS) конфигурации загружаются при запуске, автоматическая + перезагрузка недоступна; чтобы подхватить изменения, PHP перезапускают. + + - - +
diff --git a/reference/yaconf/setup.xml b/reference/yaconf/setup.xml index 45d2d10388..6f98e39830 100644 --- a/reference/yaconf/setup.xml +++ b/reference/yaconf/setup.xml @@ -1,5 +1,5 @@ - + &reftitle.setup; @@ -13,6 +13,10 @@
&reftitle.install; + + Модуль Yaconf устанавливают одним из трёх способов: через PECL, через PIE + или сборкой из исходного кода. + &pecl.moved; @@ -23,6 +27,42 @@ &pecl.windows.download.avail; + + Установка Yaconf через PECL + + + + + + Начиная с Yaconf 1.2.0 модуль устанавливают установщиком PHP-модулей + &link.pie;, для чего выполняют в командной строке следующее. + + + Установка Yaconf через PIE + + + + + + Исходный код размещается на + GitHub. Чтобы собрать + модуль из исходного кода, выполняют в командной строке следующее, заменив + пути на пути локальной установки PHP. + + + Сборка Yaconf из исходного кода + + + +
&reference.yaconf.ini; diff --git a/reference/yaconf/yaconf/debuginfo.xml b/reference/yaconf/yaconf/debuginfo.xml new file mode 100644 index 0000000000..b6b155295a --- /dev/null +++ b/reference/yaconf/yaconf/debuginfo.xml @@ -0,0 +1,142 @@ + + + + + + Yaconf::__debug_info + Показывает, как хранится значение конфигурации + + + + &reftitle.description; + + public static arraynullYaconf::__debug_info + stringname + + + Метод возвращает отладочные сведения о значении, которое сохранили под + названием name: адрес значения в памяти и признак + того, находится ли значение по-прежнему внутри уплотнённого блока + хранилища Yaconf. + + + + Метод существует исключительно для собственного набора тестов Yaconf, + который проверяет им, что модуль работает корректно. + Метод не применяют в производственном коде и не полагаются на формат + его вывода: массив, который метод возвращает, изменяется в любой момент. + + + + + + &reftitle.parameters; + + + name + + + Название конфигурации, которую требуется исследовать; применяют ту же + точечную нотацию, что и в методе Yaconf::get. + + + + + + + + &reftitle.returnvalues; + + Массив (array) из четырёх элементов, когда конфигурация + существует, иначе — &null;: + + + + + key — название, которое искали. + + + + + address — адрес сохранённого значения в памяти. + Значения хранятся как интернированные строки или неизменяемые массивы, + поэтому адрес остаётся постоянным, пока конфигурацию не перезагрузят. + + + + + val — само сохранённое значение. + + + + + changed — &false;, пока данные значения находятся + внутри уплотнённого блока хранилища, то есть операционной системе + не пришлось копировать страницу и копирование при записи ещё действует; + &true;, когда значение переразместили за пределами блока. + + + + + + + &reftitle.examples; + + Пример использования метода <methodname>Yaconf::__debug_info</methodname> + + + string(8) "app.name" + ["address"]=> + string(14) "0x7f8b1c0a3d20" + ["val"]=> + string(4) "shop" + ["changed"]=> + bool(false) +} +*/ + +var_dump(Yaconf::__debug_info("app.missing")); // NULL +?> +]]> + + + + + + &reftitle.seealso; + + + Yaconf::get + Yaconf::has + + + + + + + diff --git a/reference/yaconf/yaconf/get.xml b/reference/yaconf/yaconf/get.xml index 8b5a5b9e05..8c8ea9a1c2 100644 --- a/reference/yaconf/yaconf/get.xml +++ b/reference/yaconf/yaconf/get.xml @@ -1,10 +1,10 @@ - + Yaconf::get - Извлечь элемент + Получает значение конфигурации по названию @@ -12,11 +12,19 @@ public static mixedYaconf::get stringname - mixeddefault_valueNULL + mixeddefault&null; - - - + + Метод получает значение конфигурации, которое сохранили под названием + name. В названиях применяют точечную нотацию, чтобы + обходить вложенные ключи: "app" адресует весь разобранный + файл app.ini, "app.name" — ключ + внутри него, а начиная с Yaconf 1.2.0 + "users.database.master" — ключ в файле + database.ini, который положили в подкаталог + users/. Точечная нотация поддерживает до 64 уровней + вложенности. + @@ -25,17 +33,21 @@ name - - Ключ конфигурации, ключ может быть вида "filename.key" или "filename.sectionName,key". - + + Название конфигурации, которую требуется найти; вложенные ключи обходят + точечной нотацией, например "app.name", + "app.features.1" или, начиная с Yaconf 1.2.0, + "users.database.master" для файлов в подкаталогах. + - default_value + default - - Если ключа не существует, Yaconf::get вернёт значение этого параметра. - + + Значение, которое возвращают, когда название name + не нашли. Если параметр опустили, возвращается &null;. + @@ -43,53 +55,73 @@ &reftitle.returnvalues; - - Возвращает результат конфигурации (строка или массив), если ключ существует, - возвращает default_value, если его нет. - + + Сохранённое значение конфигурации — строку (string) или массив + (array), — когда название name + существует; иначе значение параметра default + или &null;, если значение по умолчанию не задали. + &reftitle.examples; - - Пример <function>INI</function> - + + Примеры ниже предполагают, что в каталоге, который задали директивой + yaconf.directory, лежат следующие два файла. + + - - &example.outputs.similar; - + + + + + Пример использования метода <methodname>Yaconf::get</methodname> + + ]]> - + + + &reftitle.seealso; + + + Yaconf::has + Yaconf::__debug_info + + + + + + Yaconf::has - Определить, существует ли элемент + Проверяет, существует ли значение конфигурации @@ -13,9 +13,13 @@ public static boolYaconf::has stringname - - - + + Метод определяет, существует ли значение конфигурации под названием + name, в котором применяют ту же точечную нотацию, + что и в методе Yaconf::get: например, + "app.name" или, начиная с Yaconf 1.2.0, + "users.database.master" для файлов в подкаталогах. + @@ -24,9 +28,11 @@ name - - - + + Название конфигурации, которую требуется найти; вложенные ключи обходят + точечной нотацией, например "app.name" + или "users.database.master". + @@ -34,13 +40,51 @@ &reftitle.returnvalues; - + + Функция возвращает &true;, если значение конфигурации под названием + name существует, иначе — &false;. + + - + + &reftitle.examples; + + Примеры ниже предполагают, что в каталоге, который задали директивой + yaconf.directory, лежит файл + app.ini с ключами name="shop" + и debug=0. + + + Пример использования метода <methodname>Yaconf::has</methodname> + + +]]> + + + + &reftitle.seealso; + + + Yaconf::get + Yaconf::__debug_info + + + +