PHP扩展的INI配置解析：在RINIT与MINIT阶段加载配置项的顺序与覆盖规则

好的，没问题。下面开始我的讲解。

PHP 扩展 INI 配置解析：RINIT 与 MINIT 阶段加载配置项的顺序与覆盖规则

大家好，今天我们来深入探讨 PHP 扩展中 INI 配置的加载和管理，重点关注 RINIT（Request Initialization）和 MINIT（Module Initialization）阶段配置项的加载顺序以及覆盖规则。理解这些机制对于编写健壮且可配置的 PHP 扩展至关重要。

INI 配置在 PHP 扩展中的作用

INI 文件是 PHP 中常用的配置存储方式。扩展可以使用 INI 文件来定义一些运行时参数，允许用户根据自己的需求调整扩展的行为。这些参数可以影响扩展的功能、性能、安全等方面。

PHP 扩展可以通过两种方式处理 INI 配置：

1. 直接读取 INI 文件： 扩展代码直接读取指定的 INI 文件并解析其中的配置项。这种方式比较灵活，但需要自行处理文件读取、解析和错误处理等逻辑。
2. 使用 PHP 提供的 INI API： PHP 提供了一组 API 函数，允许扩展注册自己的配置项，并自动从 php.ini 文件或 .user.ini 文件中加载配置。这种方式更加方便、规范，并且可以利用 PHP 的配置管理机制。

我们今天主要讨论第二种方式，即使用 PHP 提供的 INI API。

PHP 提供的 INI API

PHP 提供了一系列 API 函数用于注册和管理 INI 配置项，主要包括：

• REGISTER_INI_ENTRIES(): 用于注册一组 INI 配置项。通常在 MINIT 阶段调用。
• PHP_INI_ENTRY(): 用于定义单个 INI 配置项。
• zend_ini_string(), zend_ini_long(), zend_ini_double(), zend_ini_boolean(): 用于获取 INI 配置项的值。
• zend_alter_ini_entry(): 用于修改 INI 配置项的值。

MINIT 阶段：模块初始化

MINIT 阶段发生在 PHP 启动时，每个扩展只会被执行一次。这是注册 INI 配置项的最佳时机。

在 MINIT 阶段，我们使用 REGISTER_INI_ENTRIES() 宏来注册 INI 配置项。REGISTER_INI_ENTRIES() 宏接收一个结构体作为参数，该结构体包含了所有需要注册的 INI 配置项的定义。

下面是一个简单的例子：

#include "php.h"

// 定义 INI 配置项的结构体
PHP_INI_BEGIN()
    PHP_INI_ENTRY("my_extension.option1", "default_value", PHP_INI_ALL, NULL)
    PHP_INI_ENTRY("my_extension.option2", "123", PHP_INI_ALL, NULL)
    PHP_INI_ENTRY("my_extension.option3", "On", PHP_INI_ALL, NULL)
PHP_INI_END()

// 模块初始化函数
PHP_MINIT_FUNCTION(my_extension)
{
    // 注册 INI 配置项
    REGISTER_INI_ENTRIES();

    return SUCCESS;
}

zend_module_entry my_extension_module_entry = {
    STANDARD_MODULE_HEADER,
    "my_extension",
    NULL,
    PHP_MINIT(my_extension),
    NULL,
    NULL,
    NULL,
    NULL,
    PHP_MINFO(my_extension),
    PHP_VERSION,
    STANDARD_MODULE_PROPERTIES
};

#ifdef COMPILE_DL_MY_EXTENSION
ZEND_GET_MODULE(my_extension)
#endif

在这个例子中，我们定义了三个 INI 配置项：

• my_extension.option1: 字符串类型，默认值为 "default_value"。
• my_extension.option2: 整型类型，默认值为 "123"。
• my_extension.option3: 布尔类型，默认值为 "On"。

PHP_INI_ALL 表示该配置项可以在任何地方被修改，包括 php.ini 文件、.user.ini 文件和 ini_set() 函数。

在 MINIT 阶段，REGISTER_INI_ENTRIES() 会将这些配置项注册到 PHP 的配置系统中。如果用户在 php.ini 文件中设置了这些配置项的值，那么这些值将会覆盖默认值。

RINIT 阶段：请求初始化

RINIT 阶段发生在每个 HTTP 请求开始时。在这个阶段，我们可以根据 INI 配置项的值来执行一些初始化操作。

例如，我们可以根据 my_extension.option3 的值来决定是否启用某个功能：

#include "php.h"

// 模块请求初始化函数
PHP_RINIT_FUNCTION(my_extension)
{
    if (zend_ini_boolean("my_extension.option3", sizeof("my_extension.option3") - 1, 0)) {
        // 启用某个功能
        php_printf("Option3 is enabled!n");
    } else {
        // 禁用某个功能
        php_printf("Option3 is disabled!n");
    }

    return SUCCESS;
}

zend_module_entry my_extension_module_entry = {
    STANDARD_MODULE_HEADER,
    "my_extension",
    NULL,
    PHP_MINIT(my_extension),
    PHP_MSHUTDOWN(my_extension),
    PHP_RINIT(my_extension),
    PHP_RSHUTDOWN(my_extension),
    PHP_MINFO(my_extension),
    PHP_VERSION,
    STANDARD_MODULE_PROPERTIES
};

#ifdef COMPILE_DL_MY_EXTENSION
ZEND_GET_MODULE(my_extension)
#endif

在这个例子中，我们在 RINIT 阶段使用 zend_ini_boolean() 函数来获取 my_extension.option3 的值。如果值为真（例如 "On"、"1"、"true"），则启用某个功能；否则，禁用该功能。

INI 配置项的加载顺序与覆盖规则

了解 INI 配置项的加载顺序和覆盖规则对于理解 PHP 扩展的行为至关重要。

PHP 加载 INI 配置项的顺序如下：

1. 编译时默认值： 在 PHP_INI_ENTRY() 中定义的默认值。
2. php.ini 文件： PHP 主配置文件中的配置项。
3. .user.ini 文件： 目录级别的配置文件。
4. ini_set() 函数： 在 PHP 脚本中使用 ini_set() 函数设置的值。

后面的配置项会覆盖前面的配置项。例如，如果在 php.ini 文件中设置了 my_extension.option1 的值为 "new_value"，那么该值将会覆盖在 PHP_INI_ENTRY() 中定义的默认值 "default_value"。如果在 PHP 脚本中使用 ini_set('my_extension.option1', 'another_value')，那么 another_value 将会覆盖 php.ini 文件中设置的值 "new_value"。

作用域 (Scope) 对覆盖的影响

PHP_INI_ENTRY 的第四个参数定义了配置项的作用域，这会影响配置项的覆盖行为。主要的作用域类型包括：

• PHP_INI_USER: 可以通过 .user.ini 或 ini_set() 修改。
• PHP_INI_PERDIR: 只能通过 php.ini 或 .htaccess 修改。
• PHP_INI_SYSTEM: 只能通过 php.ini 修改。
• PHP_INI_ALL: 允许任何方式修改。

例如，如果将 my_extension.option1 的作用域设置为 PHP_INI_SYSTEM，那么即使在 .user.ini 文件或 PHP 脚本中使用 ini_set() 函数设置该配置项的值，也不会生效。

详细的覆盖规则表格

为了更清晰地说明 INI 配置项的加载顺序和覆盖规则，我们用表格来总结：

优先级	配置文件/函数	是否覆盖之前的配置	作用域限制	说明
1	编译时默认值	否	无	在 PHP_INI_ENTRY 中定义的默认值
2	php.ini	是	有	PHP 主配置文件中的配置项，受 PHP_INI_SYSTEM 和 PHP_INI_PERDIR 限制
3	.user.ini	是	有	目录级别的配置文件，受 PHP_INI_USER 和 PHP_INI_PERDIR 限制
4	ini_set()	是	有	在 PHP 脚本中使用 ini_set() 函数设置的值，受 PHP_INI_USER 限制

实际案例分析

假设我们有一个名为 "my_image_processor" 的 PHP 扩展，用于处理图像。该扩展有两个 INI 配置项：

• my_image_processor.max_width: 允许处理的最大图像宽度，默认值为 800。
• my_image_processor.jpeg_quality: JPEG 图像的压缩质量，默认值为 75。

我们希望用户可以根据自己的需求调整这些配置项的值。

#include "php.h"

// 定义 INI 配置项的结构体
PHP_INI_BEGIN()
    PHP_INI_ENTRY("my_image_processor.max_width", "800", PHP_INI_ALL, NULL)
    PHP_INI_ENTRY("my_image_processor.jpeg_quality", "75", PHP_INI_ALL, NULL)
PHP_INI_END()

// 模块初始化函数
PHP_MINIT_FUNCTION(my_image_processor)
{
    REGISTER_INI_ENTRIES();

    return SUCCESS;
}

// 请求初始化函数
PHP_RINIT_FUNCTION(my_image_processor)
{
    // 获取 max_width 的值
    long max_width = zend_ini_long("my_image_processor.max_width", sizeof("my_image_processor.max_width") - 1, 0);

    // 获取 jpeg_quality 的值
    long jpeg_quality = zend_ini_long("my_image_processor.jpeg_quality", sizeof("my_image_processor.jpeg_quality") - 1, 0);

    // 打印配置信息
    php_printf("Max width: %ldn", max_width);
    php_printf("JPEG quality: %ldn", jpeg_quality);

    return SUCCESS;
}

// 模块信息函数
PHP_MINFO_FUNCTION(my_image_processor)
{
    php_info_print_table_start();
    php_info_print_table_header(2, "my_image_processor support", "enabled");
    php_info_print_table_end();

    DISPLAY_INI_ENTRIES();
}

zend_module_entry my_image_processor_module_entry = {
    STANDARD_MODULE_HEADER,
    "my_image_processor",
    NULL,
    PHP_MINIT(my_image_processor),
    NULL,
    PHP_RINIT(my_image_processor),
    NULL,
    PHP_MINFO(my_image_processor),
    PHP_VERSION,
    STANDARD_MODULE_PROPERTIES
};

#ifdef COMPILE_DL_MY_IMAGE_PROCESSOR
ZEND_GET_MODULE(my_image_processor)
#endif

在这个例子中，我们在 MINIT 阶段注册了两个 INI 配置项，并在 RINIT 阶段获取了它们的值。我们还添加了一个 PHP_MINFO_FUNCTION 函数，用于在 phpinfo() 函数中显示配置信息。

现在，我们可以通过以下方式来修改这些配置项的值：

• php.ini 文件： 在 php.ini 文件中添加以下内容：

  [my_image_processor]
  my_image_processor.max_width = 1024
  my_image_processor.jpeg_quality = 90

• .user.ini 文件： 在网站根目录下创建一个 .user.ini 文件，并添加以下内容：

  my_image_processor.max_width = 640

• ini_set() 函数： 在 PHP 脚本中使用 ini_set() 函数：

  <?php
  ini_set('my_image_processor.jpeg_quality', 85);
  ?>

根据 INI 配置项的加载顺序和覆盖规则，最终的配置值将会是：

• my_image_processor.max_width: 640 (被 .user.ini 文件覆盖)
• my_image_processor.jpeg_quality: 85 (被 ini_set() 函数覆盖)

容易犯的错误和注意事项

• 忘记注册 INI 配置项： 如果没有在 MINIT 阶段使用 REGISTER_INI_ENTRIES() 宏注册 INI 配置项，那么即使在 php.ini 文件中设置了该配置项的值，也不会生效。
• 使用错误的作用域： 如果使用了错误的作用域，可能会导致配置项无法被修改。例如，如果将配置项的作用域设置为 PHP_INI_SYSTEM，那么即使在 .user.ini 文件或 PHP 脚本中使用 ini_set() 函数设置该配置项的值，也不会生效。
• 忘记检查 INI 配置项的值： 在 RINIT 阶段，一定要检查 INI 配置项的值，并根据这些值来执行相应的操作。
• 数据类型不匹配： 使用 zend_ini_string(), zend_ini_long(), zend_ini_double(), zend_ini_boolean() 获取 INI 配置项的值时，要确保数据类型匹配。否则可能会导致错误。
• 使用 sizeof 运算符的陷阱： 在使用 zend_ini_string() 等函数时，第二个参数是配置项名称的长度。很多人会使用 sizeof("my_extension.option1") 来获取长度，但这样得到的是字符串字面量的长度，包括结尾的空字符。正确的做法是 sizeof("my_extension.option1") - 1 或者使用 strlen("my_extension.option1")。

结论：配置机制影响扩展的行为

INI 配置是 PHP 扩展中重要的组成部分，它可以让用户根据自己的需求调整扩展的行为。理解 INI 配置项的加载顺序和覆盖规则对于编写健壮且可配置的 PHP 扩展至关重要。通过 REGISTER_INI_ENTRIES，PHP_INI_ENTRY等API定义INI配置，并根据其作用域和优先级，来灵活控制扩展的行为，同时要避免常见的错误，才能写出更好的扩展。