4.7. 声明和使用 INI 设置

本章详细介绍了 PHP 如何通过配置进行操作,以及如何通过注册和使用 INI 设置将扩展插入 PHP 的主要配置步骤。

INI设置提醒

在继续之前,你必须记住 INI 设置和 PHP 配置在 PHP 中的工作方式。这里是步骤,再次提取它们作为对源代码的解释。PHP INI文件解析步骤发生在php_init_config(),与 INI 相关的一切主要发生在Zend/zend_ini.c

首先,PHP 尝试解析一个或几个 INI 文件。这些文件可能会声明某些设置,这些设置将来可能相关或可能不相关。在此早期阶段(INI 文件解析),PHP 对此类文件的期望一无所知。它只是解析内容,并将其保存以备后用。

然后,第二步,PHP启动其扩展,并调用其MINIT()。如果你需要记住有关 PHP 生命周期的信息,阅读专用章节MINIT()现在可以注册当前扩展 的 INI 设置。注册设置时,作为 INI 文件解析步骤的一部分,引擎会检查它是否之前解析了其定义。如果已解析其定义,则将 INI 设置注册到引擎中,并将获取从 INI 文件中解析的值。如果在已解析的 INI 文件中没有定义,那么它将使用扩展设计器提供给 API 的默认值进行注册。

注意

该设置将获得的默认值是从 INI 文件解析中探查到的。如果未找到,则默认值为扩展开发人员提供的默认值,而不是其他方式。

我们在此讨论的默认值称为“主值”。你可以从phpinfo()输出中调用它,对吗?

php_extensions_ini.png

主值不能更改。如果在请求期间,用户希望使用ini_set()来更改配置,并且如果允许的话,则更改后的值为“本地值”,即当前请求的当前值。引擎将在请求结束时自动将本地值恢复为主值,从而将其重置并忽略请求有效的更改。

ini_get()读取当前请求绑定的本地值,而get_cfg_var()无论发生什么都会读取主值。

注意

如果你理解正确的话,get_cfg_var()对于任何不属于 INI 文件解析的值,即使该值存在且由扩展声明,该值也将返回false。反之亦然:如果要求提供扩展没有声明的设置,则ini_get将返回false,即使这样的设置是INI文件解析的一部分(例如php.ini)。

细说 INI 设置

进入引擎,INI 设置由zend_ini_entry结构表示:

  1. struct _zend_ini_entry {
  2. zend_string *name;
  3. int (*on_modify)(zend_ini_entry *entry, zend_string *new_value, void *mh_arg1, void *mh_arg2, void *mh_arg3,
  4. int stage);
  5. void *mh_arg1;
  6. void *mh_arg2;
  7. void *mh_arg3;
  8. zend_string *value;
  9. zend_string *orig_value;
  10. void (*displayer)(zend_ini_entry *ini_entry, int type);
  11. int modifiable;
  12. int orig_modifiable;
  13. int modified;
  14. int module_number;
  15. };

在这样的结构中没有什么真正厉害的。

  • 设置的namevalue 是最常用的字段。但是请注意,该值为字符串(如 zend_string *),没别的了。
  • 然后,就像我们在上面的简介章节中详细介绍的那样,我们找到与设置值的修改相关的orig_valueorig_modifiedmodifiableModifyed字段。该设置必须将其原始值(作为“主值”)保留在内存中。
  • modifiable 告诉设置实际上是否可修改,以及必须从 ZEND_INI_USERZEND_INI_PERDIRZEND_INI_SYSTEMZEND_INI_ALL中选出一些值,那些可能一起被标记,详情在PHP手册中
  • modified 只要在请求期间修改了设置,那么它就会设置为1,以便引擎在请求关闭时知道必须将 INI 设置值恢复为其主值才能处理下一个请求。
  • on_modify() 是每次修改当前设置的值时都会调用的处理程序,例如调用ini_set()(但不仅如此)。我们稍后将重点放在on_modify()上,但可以将其视为验证函数(例如,如果期望该设置代表整数,则可以针对整数验证要提供的值)。它还用作更新全局值的内存桥,我们稍后也会再讲。
  • diplayer()不太有用,通常你不会传递什么东西。displayer()是关于如何显示你的设置。例如,你可能还记得 PHP 倾向于对 true / yes / on / 1等布尔值显示 On。那就是displayer()的工作:将当前值转换为“显示”值。

你还需要处理这种结构zend_ini_entry_def

  1. typedef struct _zend_ini_entry_def {
  2. const char *name;
  3. ZEND_INI_MH((*on_modify));
  4. void *mh_arg1;
  5. void *mh_arg2;
  6. void *mh_arg3;
  7. const char *value;
  8. void (*displayer)(zend_ini_entry *ini_entry, int type);
  9. int modifiable;
  10. uint name_length;
  11. uint value_length;
  12. } zend_ini_entry_def;

zend_ini_entry非常相似,程序员(你)必须在引擎上注册 INI 设置时使用zend_ini_entry_def。引擎读取zend_ini_entry_def,并根据你提供的定义模型在内部创建一个zend_ini_entry供自己使用。简单。

注册和使用 INI

注册

INI 设置通过请求保持不变。它们可能会在请求期间运行时更改其值,但在请求关闭时会恢复为原始值。因此,在扩展的MINIT()钩子中,全部注册一次 INI 设置即可。

你需要做的是声明一个zend_ini_entry_def向量,这将为你提供专用的宏。然后,将向量注册到引擎,并完成声明。让我们看一下我们在上一章中有关随机数选择和猜测的示例,现在仅显示相关部分:

  1. PHP_INI_BEGIN()
  2. PHP_INI_ENTRY("pib.rnd_max", "100", PHP_INI_ALL, NULL)
  3. PHP_INI_END()
  4. PHP_MINIT_FUNCTION(pib)
  5. {
  6. REGISTER_INI_ENTRIES();
  7. return SUCCESS;
  8. }
  9. PHP_MINFO_FUNCTION(pib)
  10. {
  11. DISPLAY_INI_ENTRIES();
  12. }
  13. PHP_MSHUTDOWN_FUNCTION(pib)
  14. {
  15. UNREGISTER_INI_ENTRIES();
  16. return SUCCESS;
  17. }

那是最简单的 INI 声明,我们不会按原样保留它,但是步骤很简单:你可以使用PHP_INI_BEGINPHP_INI_END宏声明一个zend_ini_entry_def[]向量。在中间,你可以再次使用此处的宏添加单个zend_ini_entry_def条目。我们使用了最简单的一个:PHP_INI_BEGIN(),仅包含四个参数:要注册的条目的名称,如果它不是 INI 文件扫描的一部分,则给出其默认值(有关详细信息,请参见上一章),修改级别,PHP_INI_ALL表示“随处”。我们还没有使用验证器,故传递了 NULL。

MINIT挂钩中,我们使用REGISTER_INI_ENTRIES宏完成其描述工作,而在模块关闭时使用其对应的UNREGISTER_INI_ENTRIES释放分配的资源。

现在,新的 “pib.rnd_max” INI 设置被声明为 PHP_INI_ALL,这意味着用户可以使用ini_set()修改其值(并使用ini_get()读回它)。

我们并没有忘记使用DISPLAY_INI_ENTRIES()将这些 INI 设置显示为扩展信息的一部分。在MINFO()钩子的声明中忘记这一点将导致我们的 INI 设置在信息页面(phpinfo())中对用户隐藏。如果你需要,查看扩展信息章节

用法

作为扩展开发人员,我们现在可能需要自己读取 INI 设置值。在扩展中执行此操作的最简单方法是使用宏,该宏将在保留了所有 INI 设置的主数组中查找值,找到该值,然后将其返回您想要的类型。根据要返回的C类型,我们提供了几个宏。

INI_INT(val)INI_FLT(val)INI_STR(val)INI_BOOL(val) 这四个宏都将在INI设置数组中查找提供的值,并将其(如果找到)返回并强制转换为你要求的类型。

注意

请记住,在zend_ini_entry中,该值为zend_string类型。在我们的示例中,我们注册了一个类型为“long”的 INI 设置,即我们的pib.rnd_max,其默认值为100。但是那个值被作为zend_string注册到 INI 设置数组中,因此每次我们想读回它的值时都需要将其强制转换为'long'。 INI_INT()做这样的工作。

例:

  1. php_printf("The value is : %lu", INI_INT("pib.rnd_max"));

注意

如果找不到该值,则按照要求 long 返回0。在相同的情况下将返回0.0,但会进行浮点转换等。

如果用户将修改设置,并且我们希望显示“主”原始值(在我们的示例中为100),那么我们将使用INI_ORIG_INT()代替INI_INT()。当然,其他类型也存在这样的宏。

验证器和全局内存桥

到目前为止,注册和读取 INI 设置值并不困难。但是,我们在以上几行中使用它们的方式并非最佳。

使用“高级” INI 设置 API 可以同时解决两个问题:

  • 每次我们想读取值时,都需要对 INI 主设置表进行查找,以及强制转换为正确的类型(通常)。 这些操作花费一些CPU周期。
  • 我们没有提供任何验证器,因此用户可以更改我们的设置并将任何想要添加的值作为值。

解决方案是使用on_modify()验证器和内存桥来更新全局变量。

通过使用高级 INI 设置管理 API,我们可以告诉引擎正常注册我们的设置,但我们也可以指示它在每次更改 INI 设置值时更新整体值。因此,每当我们想读取值时,只需要读取我们的全局值即可。在我们需要经常读取 INI 设置值的情况下,这将提高性能,因为不再需要哈希表查找和强制转换操作。

注意

你需要对使用全局变量感到舒适才能继续阅读本章。全局空间管理在这章中

要声明到全局的内存桥,我们需要创建一个全局请求,并更改声明 INI 设置的方式。 像这样:

  1. ZEND_BEGIN_MODULE_GLOBALS(pib)
  2. zend_ulong max_rnd;
  3. ZEND_END_MODULE_GLOBALS(pib)
  4. ZEND_DECLARE_MODULE_GLOBALS(pib)
  5. PHP_INI_BEGIN()
  6. STD_PHP_INI_ENTRY("pib.rnd_max", "100", PHP_INI_ALL, OnUpdateLongGEZero, max_rnd, zend_pib_globals, pib_globals)
  7. PHP_INI_END()
  8. PHP_MINIT_FUNCTION(pib)
  9. {
  10. REGISTER_INI_ENTRIES();
  11. return SUCCESS;
  12. }

我们声明一个名为max_rnd的全局变量,类型为zend_ulong。然后,我们这次使用STD_PHP_INI_ENTRY()注册我们的'pib.rnd_max' INI 值。这使我们可以将更多参数传递给宏。 前四个已知,我们将在本章前面详细介绍。

最后四个参数代表全局桥。我们告诉它要更新由符号pib_globals表示的zend_pib_globals

构中的max_rnd。如果不了解,阅读全局管理章节。 快速提醒一下,ZEND_BEGIN_MODULE_GLOBALS()声明了Zend_pib_globals结构,而ZEND_DECLARE_MODULE_GLOBALS()则声明了这种类型的pib_globals符号。

注意

在内部, 偏移量将用于将我们的zend_pib_globals结构里的max_rnd成员的字节片计算,以便只要更改 'pub.rand_max' 就能更新该部分内存。

这里使用的on_modify()验证器,,onUpdateLongGEZero()是 PHP 中存在的默认验证器,用于对大于或等于零的 long 值进行验证。需要验证器来更新全局变量,验证器已完成了这样的工作。

现在,要读取我们的 INI 设置值,我们只需要读取我们的max_rnd全局值:

  1. php_printf("The value is : %lu", PIB_G(max_rnd));

我们完成了。

让我们现在来看验证器(on_modify())。 验证器有两个目标:

  • 验证传递的值
  • 如果验证成功,则更新全局变量

每当设置或修改(写入)INI设置时,都将调用验证程序。

警告

如果你要使用 INI 设置值更新全局变量,则需要一个验证器。这样的机制不是引擎神奇地执行的,而是必须明确地在验证器中完成。

让我们来看看onUpdateLongGEZero()源代码:

  1. #define ZEND_INI_MH(name) int name(zend_ini_entry *entry, zend_string *new_value,
  2. void *mh_arg1, void *mh_arg2, void *mh_arg3, int stage)
  3. ZEND_API ZEND_INI_MH(OnUpdateLongGEZero)
  4. {
  5. zend_long *p, tmp;
  6. #ifndef ZTS
  7. char *base = (char *) mh_arg2;
  8. #else
  9. char *base;
  10. base = (char *) ts_resource(*((int *) mh_arg2));
  11. #endif
  12. tmp = zend_atol(ZSTR_VAL(new_value), (int)ZSTR_LEN(new_value));
  13. if (tmp < 0) {
  14. return FAILURE;
  15. }
  16. p = (zend_long *) (base+(size_t) mh_arg1);
  17. *p = tmp;
  18. return SUCCESS;
  19. }

如你所见,没有什么复杂的。你的验证器将获得new_value,并且必须对其进行验证。记住new_value zend_string * 类型。onUpdateLongGEZero()将值作为 long 并检查其是否为正整数。如果一切顺利的话,必须从验证器那里返回SUCCESS,否则就必须返回FAILURE

然后是更新全局的部分。mh_arg变量用于将任何类型的信息携带到验证器中。

Note

'mh'代表修改处理程序。验证程序回调也称为修改处理程序回调

mh_arg2是指向表示全局结构内存开始的内存区域的指针,在本例中为pib_globals分配内存的开始。请注意,当我们谈论请求全局变量存储器时,无论是否使用ZTS模式,后者的访问方式都不同。有关ZTS的更多信息可以在这里找到.

mh_arg1传递了全局成员的计算偏移量(对我们来说是max_rnd),并且您必须自己对内存进行切片才能获得指向它的指针。这就是为什么我们将mh_arg2存储为通用char *指针并强制将mh_arg1强制转换为size_t的原因。

然后,您只需通过写入指针来使用已验证的值更新内容。mh_arg3实际上未使用。

PHP的默认验证器为OnUpdateLongGEZero()OnUpdateLong()OnUpdateBool()OnUpdateReal()OnUpdateString( )OnUpdateStringUnempty()。它们的名称是自描述的,它们的源代码也是(您可以阅读)。

基于这样的模型,我们可以开发自己的验证器,以验证0到1000之间的正整数,例如:

  1. ZEND_INI_MH(onUpdateMaxRnd)
  2. {
  3. zend_long tmp;
  4. zend_long *p;
  5. #ifndef ZTS
  6. char *base = (char *) mh_arg2;
  7. #else
  8. char *base;
  9. base = (char *) ts_resource(*((int *) mh_arg2));
  10. #endif
  11. p = (zend_long *) (base+(size_t) mh_arg1);
  12. tmp = zend_atol(ZSTR_VAL(new_value), (int)ZSTR_LEN(new_value));
  13. if (tmp < 0 || tmp > 1000) {
  14. return FAILURE;
  15. }
  16. *p = tmp;
  17. return SUCCESS;
  18. }
  19. PHP_INI_BEGIN()
  20. STD_PHP_INI_ENTRY("pib.rnd_max", "100", PHP_INI_ALL, onUpdateMaxRnd, max_rnd, zend_pib_globals, pib_globals)
  21. PHP_INI_END()

Note

一旦确认范围,就可以安全地从 long 写入 unsigned long

现在,如果用户想要修改设置并传递一个不验证的错误值,则ini_set()只会将false返回到用户区,并且不会修改该值:

  1. ini_set('pib.rnd_max', 2048); /* returns false as 2048 is > 1000 */

在相反的情况下,ini_set()返回旧值并修改当前值。新提供的值变为

当前的“本地”值,而默认的先前值保留为“主值”。phpinfo()ini_get_all()详细说明这些值。例:

  1. ini_set('pib.rnd_max', 500);
  2. var_dump(ini_get_all('pib'));
  3. /*
  4. array(1) {
  5. ["pib.rnd_max"]=>
  6. array(3) {
  7. ["global_value"]=>
  8. string(3) "100"
  9. ["local_value"]=>
  10. string(3) "500"
  11. ["access"]=>
  12. int(7)
  13. }
  14. */

建议您在更改值时将调用验证程序回调,该值会更改多次。例如,对于我们的小示例,我们设计的验证器被称为3次:

-在REGISTER_INI_ENTRY()中的一次中,在MINIT()中的一次中。我们在此处将默认值设置为我们的设置,因此这是使用我们的验证器完成的。请记住,默认值可能来自INI文件解析。

-每个ini_set()用户域调用一次。

-一旦进入RSHUTDOWN(),如果引擎在当前请求期间更改了本地值,则尝试将本地值恢复为其主值。 Userlandini_restore()执行相同的工作。

还请记住,ini_set()将检查值访问器。如果我们设计了PHP_INI_SYSTEM设置,则用户将无法使用ini_set()对其进行修改,因为ini_set()使用的是 PHP_INI_USER`作为访问者。然后,在这种情况下,将检测到不匹配,并且引擎不会调用验证器。

如果您需要在运行时将INI设置值更改为扩展名,则内部调用为zend_alter_ini_entry(),这就是userlandini_set()所使用的。

使用显示器

关于INI设置,您需要了解的最后一件事是displayer()回调。它在实践中较少使用,它在用户区要求打印&#39;&#39;您的INI设置值时触发,即通过使用</code>phpinfo()<code>或</code>php--ri

如果不提供显示器,则将使用默认显示器。看见:

  1. > php -dextension=pib.so -dpib.rnd_max=120 --ri pib
  2. Directive => Local Value => Master Value
  3. pib.rnd_max => 120 => 120

默认显示器采用INI设置值(提醒一下,该类型为zend_string **),并简单地显示它。如果未找到任何值或该值为空字符串,则显示字符串“ no value”。

要进行这样的过程,我们必须声明一个将被调用的displayer()回调。让我们尝试将我们的'pib.rnd_max'值表示为百分比条,并带有'#'*。'字符。只是一个例子:

  1. #define ZEND_INI_DISP(name) void name(zend_ini_entry *ini_entry, int type)
  2. ZEND_INI_DISP(MaxRnd)
  3. {
  4. char disp[100] = {0};
  5. zend_ulong tmp = 0;
  6. if (type == ZEND_INI_DISPLAY_ORIG && ini_entry->modified && ini_entry->orig_value) {
  7. tmp = ZEND_STRTOUL(ZSTR_VAL(ini_entry->orig_value), NULL, 10);
  8. } else if (ini_entry->value) {
  9. tmp = ZEND_STRTOUL(ZSTR_VAL(ini_entry->value), NULL, 10);
  10. }
  11. tmp /= 10;
  12. memset(disp, '#', tmp);
  13. memset(disp + tmp, '.', 100 - tmp);
  14. php_write(disp, 100);
  15. }
  16. PHP_INI_BEGIN()
  17. STD_PHP_INI_ENTRY_EX("pib.rnd_max", "100", PHP_INI_ALL, onUpdateMaxRnd, max_rnd, zend_pib_globals,
  18. pib_globals, MaxRnd)
  19. PHP_INI_END()

这次我们使用_EX()宏对应部分来声明我们的INI设置。此宏接受显示器功能作为最后一个参数。然后使用STD_PHP_INI_ENTRY_EX()

然后使用ZEND_INI_DISP()声明我们的显示功能。它接收附加的INI设置作为参数,PHP希望您显示该值:ZEND_INI_DISPLAY_ORIG表示主值,ZEND_INI_DISPLAY_ACTIVE表示当前请求绑定的本地值。

然后,我们使用该值进行计算,并将其表示为“#”和“。”字符,如下所示:

  1. ini_set('pib.rnd_max', 500);
  2. phpinfo(INFO_MODULES);

如果使用以下命令调用它:

  1. > php -dextension=pib.so /tmp/file.php

然后显示:

  1. pib
  2. Directive => Local Value => Master Value
  3. pib.rnd_max => ##################################################..................................................
  4. => ##########..........................................................................................

如果我们用以下命令调用它:

  1. > php -dextension=pib.so -dpib.rnd_max=10 /tmp/file.php

然后显示:

  1. pib
  2. Directive => Local Value => Master Value
  3. pib.rnd_max => ##################################################..................................................
  4. => ....................................................................................................

于PHP将同时显示我们的本地值和主值,因此我们的显示器回调在这里将被调用两次。本地值有效地表示了“ 500”的值,而主值显示了默认的硬编码值“ 100”(如果我们不进行更改),并且如果我们使用php->中的-d进行了更改, cli,它得到了有效的利用。

如果要使用PHP中现有的显示器之一,则可以使用zend_ini_boolean_displayer_cb()zend_ini_color_displayer_cb()display_link_numbers()