Zend API：深入 PHP 内核（十八）支持初始化文件（php.ini）

PHP4 重写了对初始化文件的支持。现在你可以直接在代码中指定一些初始化选项，然后在运行时读取和改变这些选项值，甚至还可以在选项值改变时接到相关通知。

如果想要为你的模块创建一个 .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 个参数：配置项名称、初始值、改变这些值所需的权限以及在值改变时用于接收通知的函数句柄。配置项名称和初始值必须是一个字符串，即使它们是一个整数。

更改这些值所需的权限可以划分为三种：PHP_INI_SYSTEM 只允许在 php.ini 中改变这些值；PHP_INI_USER 允许用户在运行时通过像 .htaccess 这样的附加文件来重写其值；而 PHP_INI_ALL 则允许随意更改。其实还有第四种权限：PHP_INI_PERDIR，不过我们还暂时不能确定它有什么影响。（本段关于这几种权限的说明与手册中《附录G php.ini 配置选项》一节的描述略有出入。根据译者自己查到的资料，相比之下还是《附录G php.ini 配置选项》更为准确些。译注）

第四个参数是初始值被改变时接收通知的函数句柄。一旦某个初始值被改变，那么相应的函数就会被调用。这个函数我们可以用宏 PHP_INI_MH 来定义：

PHP_INI_MH(OnChangeSecond);             // handler for ini-entry "second_ini_entry"

// specify ini-entries here
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（携带三个附加参数）等宏来加以指定。

关于值改变的通知函数应该被用来本地缓存一些初始花选项以便可以更快地对其访问或被用来从事一个值发生改变时所要求完成的任务。比如要是一个模块对一个主机常量进行了连接，而这时有人改变了主机名，那么就需要自动地关闭原来的连接，并尝试进行新的连接。

可以使用“表3.17 PHP 中用以访问初始化配置项的宏”来访问初始化配置项：

表3.17 PHP 中用以访问初始化配置项的宏


宏	说明
INI_INT(name)	将配置项 name 的当前值以长整数返回。
INI_FLT(name)	将配置项 name 的当前值以双精度浮点数返回。
INI_STR(name)	将配置项 name 的当前值以字符串返回。注意：这个字符串不是复制过的字符串，而是直接指向了内部数据。如果你需要进行进一步的访问的话，那就需要再进行复制一下。
INI_BOOL(name)	将配置项 name 的当前值以布尔值返回。(返回值被定义为 zend_bool,也就是说是一个 unsigned char)。
INI_ORIG_INT(name)	将配置项 name 的初始值以长整型数返回。
INI_ORIG_FLT(name)	将配置项 name 的初始值以双精度浮点数返回。
INI_ORIG_STR(name)	将配置项 name 的初始值以字符串返回。注意：这个字符串不是复制过的字符串，而是直接指向了内部数据。如果你需要进行进一步的访问的话，那就需要再进行复制一下。
INI_ORIG_BOOL(name)	将配置项 name 的初始值以布尔值返回。(返回值被定义为 zend_bool,也就是说是一个 unsigned char)。

最后，你还得把整个初始化配置项引入 PHP。这项工作可以在模块的起始/结束函数中使用宏 REGISTER_INI_ENTRIES() 和 UNREGISTER_INI_ENTRIES() 来搞定。

 ZEND_MINIT_FUNCTION(mymodule)
{
    REGISTER_INI_ENTRIES();
}

ZEND_MSHUTDOWN_FUNCTION(mymodule)
{
    UNREGISTER_INI_ENTRIES();
}

抚琴居