Глава 40. Поддержка файлов инициализации

В PHP 4 имеется переработанная поддержка файлов инициализации. Теперь можно специфицировать вхождения инициализации по умолчанию непосредственно в вашем коде, читать и изменять эти значения на этапе прогона/runtime и создавать обработчики сообщений для изменения уведомления.

При создании раздела .ini в вашем собственном модуле используйте макрос PHP_INI_BEGIN() для маркировки начала такого раздела и макрос PHP_INI_END() - для маркировки его конца. Между ними вы можете использовать PHP_INI_ENTRY() для создания вхождений.

PHP_INI_BEGIN()
    PHP_INI_ENTRY("first_ini_entry",  "has_string_value", PHP_INI_ALL, NULL)
    PHP_INI_ENTRY("second_ini_entry", "2",                PHP_INI_SYSTEM, OnChangeSecond)
    PHP_INI_ENTRY("third_ini_entry",  "xyz",              PHP_INI_USER, NULL)
PHP_INI_END()

Макрос PHP_INI_ENTRY() принимает 4 параметра: имя вхождения/entry name, значение вхождения/entry value, изменение прав доступа и указатель на обработчик изменения уведомления. Имя и значение вхождения обязаны быть специфицированы как строки, независимо от того, являются они в действительности строками или целыми числами.

Права доступа сгруппированы в три раздела: PHP_INI_SYSTEM позволяет вносить изменения только непосредственно в файле php3.ini; PHP_INI_USER позволяет пользователю переопределять изменения на этапе прогона с использованием дополнительных файлов конфигурации, таких как .htaccess;
а PHP_INI_ALL позволяет делать изменения без ограничений.
Имеется также четвёртый уровень, PHP_INI_PERDIR, поведение которого ещё не проверено.

Четвёртый параметр состоит из указателя на обработчик change-notification/изменения уведомления. При изменении любого из этих вхождений вызывается этот обработчик. Такой обработчик может быть объявлен с использованием макроса PHP_INI_MH:

PHP_INI_MH(OnChangeSecond);             // обработчик для ini-entry "second_ini_entry"

// специфицируйте здесь ini-entries

PHP_INI_MH(OnChangeSecond)
{

    zend_printf("Message caught, our ini entry has been changed to %s<br>", new_value);

    return(SUCCESS);

}

Новое значение даётся обработчику изменения как строка в переменной new_value. Если посмотреть на определение PHP_INI_MH, вы увидите, что должны использовать небольшое количество параметров:

#define PHP_INI_MH(name) int name(php_ini_entry *entry, char *new_value,
                                  uint new_value_length, void *mh_arg1,
                                  void *mh_arg2, void *mh_arg3)

Все эти определения можно найти в php_ini.h. Ваш обработчик сообщений будет иметь доступ к структуре, которая содержит полное вхождение, новое значение, его длину и три необязательных аргумента. Эти необязательные аргументы можно специфицировать дополнительным макросом PHP_INI_ENTRY1 (допускающим один дополнительный аргумент), PHP_INI_ENTRY2 (допускающим два дополнительных аргумента) и PHP_INI_ENTRY3 (допускающим три дополнительных аргумента).

Обработчики change-notification должны использоваться при кэширования вхождений инициализации для быстрого доступа или для выполнения определённых задач, которые необходимы при изменении значения. Например, если модулю необходимо постоянное соединение с определённым хостом и кто-то изменяет hostname, автоматически разрывается старое соединение и делается попытка установить новое.

Доступ к вхождениям инициализации может также обрабатываться макросами из Таблицы 9.17.

Наконец, вы должны ввести ваши вхождения инициализации в PHP. Это можно сделать в startup и shutdown-функциях модуля, используя макросы REGISTER_INI_ENTRIES() и UNREGISTER_INI_ENTRIES():

ZEND_MINIT_FUNCTION(mymodule)
{

    REGISTER_INI_ENTRIES();

}

ZEND_MSHUTDOWN_FUNCTION(mymodule)
{

    UNREGISTER_INI_ENTRIES();

}