如何用C语言开发PHP扩展？|PHP扩展开发实战指南

PHP作为一门高效、灵活的脚本语言，广泛应用于Web开发领域，当面临极其复杂的计算密集型任务、需要底层系统调用、操作特定硬件或追求极致性能时，原生PHP代码可能显得力不从心，使用C语言开发PHP扩展（Extension）成为连接高性能底层能力与灵活PHP应用层的关键桥梁，它允许你将核心逻辑用C实现，编译为共享库（.so文件），无缝集成到PHP运行时环境中，供PHP脚本直接调用，从而突破性能瓶颈，实现PHP自身难以完成的功能。

环境准备与工具链

在开始编码之前,确保你的开发环境已就绪：

1. PHP开发环境：

   • PHP源代码： 这是必须的，从 https://www.php.net/downloads 下载与你目标运行环境PHP版本匹配的源代码包（php-8.x.x.tar.gz），解压到本地目录（如 ~/php-src）。
   • PHP运行时： 安装与你下载的源代码版本一致的PHP命令行解释器 (php) 和开发包（如 php-dev 或 php-devel），以便使用 phpize 和 php-config 工具。
   • 构建工具： 确保 make, autoconf, automake, libtool 等基础构建工具已安装。
   • C编译器： gcc 或 clang。

2. 关键工具：

   • phpize: 位于PHP安装目录的 bin 子目录下（或系统PATH中），它用于准备扩展的构建环境，生成 configure 脚本，执行 phpize 后会创建必要的构建文件。
   • php-config: 同样位于PHP的 bin 目录，它提供当前PHP安装的配置信息（如包含文件路径、库路径、扩展目录等），在编译和链接时至关重要，可以通过 php-config --help 查看其功能。

第一步：创建扩展骨架

PHP源代码包提供了一个强大的脚本 ext_skel (位于源码包的 ext 目录下)，它能快速生成扩展的基本框架。

1. 进入PHP源代码的 ext 目录：

   cd ~/php-src/ext

2. 使用 ext_skel 创建扩展骨架，假设我们要创建一个名为 greeting 的扩展：

   ./ext_skel --extname=greeting

   这将创建一个名为 greeting 的新目录，里面包含了扩展的初始文件。

3. 进入新创建的扩展目录：

   cd greeting

第二步：探索骨架结构与核心文件

生成的骨架目录包含关键文件：

• config.m4: 这是扩展的构建配置脚本，它告诉 phpize 和 configure 如何检测依赖、设置编译选项以及最终如何编译扩展，你需要编辑此文件来启用扩展、检查依赖库（如果需要）等。
• php_greeting.h: 扩展的头文件，主要包含函数声明、类定义（如果扩展提供类）、常量定义等。
• greeting.c: 扩展的主源文件，包含模块入口定义、函数实现、INI设置处理、资源管理等核心代码，这是我们主要编写功能的地方。
• tests/: 存放扩展测试用例的目录（初始可能为空或包含示例）。
• CREDITS, EXPERIMENTAL, .gitignore 等： 辅助文件。

第三步：配置构建系统 (config.m4)

编辑 config.m4 文件，初始内容包含很多注释掉的示例，我们需要做的最基本修改是启用扩展：

找到类似下面的行（通常在文件末尾附近）：

dnl PHP_NEW_EXTENSION(greeting, greeting.c, $ext_shared)

去掉行首的 dnl (它代表注释) 并确保 $ext_shared 存在（表示构建为共享库）：

PHP_NEW_EXTENSION(greeting, greeting.c, $ext_shared)

如果你的扩展需要链接外部库（如 libm 数学库），需要在 PHP_NEW_EXTENSION 行之前添加检测和链接指令：

dnl 检查并链接数学库 (-lm)
PHP_ADD_LIBRARY(m, 1, GREETING_SHARED_LIBADD)

保存 config.m4。

第四步：实现核心功能 (greeting.c & php_greeting.h)

现在进入最核心的部分：用C语言编写扩展的功能。

1. 定义模块入口 (zend_module_entry):
   在 greeting.c 中找到 zend_module_entry 结构体，这是扩展的“身份证”，PHP内核通过它识别和加载你的扩展。

   zend_module_entry greeting_module_entry = {
       STANDARD_MODULE_HEADER,
       "greeting",                  // 扩展名称，与 extname 一致
       greeting_functions,          // 指向函数入口数组
       PHP_MINIT(greeting),         // 模块初始化函数 (MINIT)
       PHP_MSHUTDOWN(greeting),     // 模块关闭函数 (MSHUTDOWN)
       PHP_RINIT(greeting),         // 请求初始化函数 (RINIT) - 可选
       PHP_RSHUTDOWN(greeting),     // 请求关闭函数 (RSHUTDOWN) - 可选
       PHP_MINFO(greeting),         // 模块信息函数 (phpinfo() 输出)
       PHP_GREETING_VERSION,        // 扩展版本
       STANDARD_MODULE_PROPERTIES
   };

   确保 "greeting" 与你的扩展名一致。greeting_functions 是下面要定义的函数数组。

2. 定义PHP函数 (zend_function_entry):
   在 greeting.c 中找到或创建 zend_function_entry 数组，它列出了你的扩展提供给PHP脚本的所有函数及其对应的C实现。

   static const zend_function_entry greeting_functions[] = {
       PHP_FE(confirm_greeting_compiled, NULL) // 初始示例函数，可删除或替换
       PHP_FE(greet, arginfo_greet)             // 添加我们自己的函数 greet
       PHP_FE_END // 结束标记
   };

   • PHP_FE 宏定义了一个函数：第一个参数是PHP函数名（也是对应的C函数名前缀），第二个参数是参数信息结构体指针（arginfo_）。
   • 删除或替换掉 confirm_greeting_compiled 这个示例函数，添加我们自己的函数，如 greet。

3. 编写C函数实现：
   在 greeting.c 中实现 PHP_FUNCTION(greet)，这个宏会展开为 void zif_greet(zend_execute_data execute_data, zval return_value)，我们通常使用 PHP_FUNCTION 宏来定义。

   PHP_FUNCTION(greet)
   {
       char name = NULL;
       size_t name_len;
       zend_string greeting;
       // 解析参数：期望一个字符串参数
       ZEND_PARSE_PARAMETERS_START(1, 1)
           Z_PARAM_STRING(name, name_len)
       ZEND_PARSE_PARAMETERS_END();
       // 构造问候语字符串，注意：使用安全的字符串操作（如 `spprintf` 或 `zend_string` API）
       greeting = strpprintf(0, "Hello, %s! Welcome to the world of PHP extensions!", name);
       // 将 zend_string 赋值给返回值 (return_value)
       RETURN_STR(greeting);
   }

   • ZEND_PARSE_PARAMETERS_START / ZEND_PARSE_PARAMETERS_END: 用于安全地解析PHP脚本传递过来的参数。(1, 1) 表示期望最少1个，最多1个参数。
   • Z_PARAM_STRING(name, name_len): 将第一个参数解析为C字符串 (char name) 及其长度 (size_t name_len)，内存管理由Zend引擎负责（临时变量）。
   • strpprintf: 安全的格式化字符串函数（类似 sprintf），返回 zend_string。
   • RETURN_STR(greeting): 将 zend_string 类型的 greeting 设置为函数的返回值，并增加其引用计数（或转移所有权），这是正确返回字符串给PHP的方式。

4. 定义参数信息 (arginfo):
   为了让PHP引擎（包括反射、参数类型提示等）了解函数的参数信息，需要在 php_greeting.h (或直接在 greeting.c 中) 定义 arginfo 结构。
   在 php_greeting.h 中添加：

   #ifndef PHP_GREETING_H
   #define PHP_GREETING_H
   extern zend_module_entry greeting_module_entry;
   #define phpext_greeting_ptr &greeting_module_entry
   #define PHP_GREETING_VERSION "0.1.0" // 定义扩展版本
   #ifdef ZTS
   #include "TSRM.h"
   #endif
   // 声明函数
   PHP_FUNCTION(greet);
   // 定义 greet 函数的参数信息
   ZEND_BEGIN_ARG_INFO(arginfo_greet, 0) // 0 表示不要求传递引用
       ZEND_ARG_INFO(0, name)          // 参数名：name, 0 表示按值传递
   ZEND_END_ARG_INFO();
   #endif / PHP_GREETING_H /

   确保 greeting.c 包含了 php_greeting.h (#include "php_greeting.h")。

5. 实现模块信息函数 (PHP_MINFO_FUNCTION):
   此函数在 phpinfo(); 被调用时输出扩展的信息，在 greeting.c 中找到并修改：

   PHP_MINFO_FUNCTION(greeting)
   {
       php_info_print_table_start();
       php_info_print_table_header(2, "greeting support", "enabled");
       php_info_print_table_row(2, "version", PHP_GREETING_VERSION);
       php_info_print_table_row(2, "author", "Your Name <your@email.com>");
       php_info_print_table_end();
   }

第五步：编译与安装扩展

1. 运行 phpize： 在扩展目录 (~/php-src/ext/greeting) 下执行：

   phpize

   这会生成 configure 脚本和其他构建文件。

2. 运行 configure：

   ./configure [--with-php-config=/path/to/php-config] # php-config 不在PATH中，需要指定路径

   php-config 在PATH里，直接运行 ./configure 即可。

3. 编译：

   make

   编译成功后,会在 modules/ 子目录下生成 greeting.so（或类似名称，如 greeting.dll 在Windows上）共享库文件。

4. 安装 (可选)：

   sudo make install # 需要管理员权限

   这会将 greeting.so 复制到PHP的扩展目录（如 /usr/lib/php/20210902/ 或 /path/to/php/extensions/），使用 php-config --extension-dir 查看目标目录，你也可以手动复制 .so 文件到该目录。

5. 启用扩展： 编辑PHP的配置文件 (php.ini)，添加一行：

   extension=greeting

   确保文件名正确（不包括路径，PHP会在 extension_dir 中查找）。

   

6. 验证安装：

   php -m | grep greeting

   应该输出 greeting，运行：

   php -r 'echo greet("Developer");'

   应该输出：Hello, Developer! Welcome to the world of PHP extensions!。

第六步：进阶主题与最佳实践

1. 使用 zend_string API： PHP 7+ 引入了 zend_string 作为内部字符串表示，优先使用 zend_string API (zend_string_init, zend_string_copy, zend_string_release, ZSTR_ 宏等) 代替传统的 char 和 estrdup/efree 进行字符串操作，更安全高效，且与Zend内存管理集成更好。

2. 引用计数与内存管理： Zend引擎使用引用计数管理 zval（PHP变量的内部表示）内存，深入理解 Z_REFCOUNT, Z_REFCOUNTED, Z_ADDREF, Z_DELREF, ZVAL_COPY_VALUE, ZVAL_COPY, ZVAL_DUP 等宏和概念至关重要，错误的内存管理是扩展崩溃的主要原因，遵循“谁分配，谁释放”和正确处理引用计数的原则，利用 valgrind 等工具检测内存泄漏。

3. 处理复杂数据结构： 学习操作数组 (zend_array, HashTable API) 和对象 (zend_object)，了解如何创建、遍历、修改PHP数组和对象。

4. 定义类和对象： 扩展可以定义自己的PHP类，这涉及创建 zend_class_entry，定义方法 (zend_function_entry)、属性、常量以及实现构造函数、析构函数等，需要理解对象句柄 (zend_object_handlers) 和对象存储。

5. INI 设置： 扩展可以定义自己的 php.ini 配置指令，使用 PHP_INI_BEGIN(), PHP_INI_ENTRY(), PHP_INI_END() 和相应的 PHP_INI_MH (OnUpdate) 处理函数。

6. 资源类型 (Resource): 当需要封装C语言指针（如文件句柄、数据库连接、自定义结构体）时，需要注册资源类型，使用 zend_register_list_destructors_ex 注册资源析构函数，并通过 zend_register_resource / zend_fetch_resource 管理资源。

7. 线程安全 (ZTS – Zend Thread Safety)： 如果你的PHP运行在多线程环境（如Apache MPM worker/event, IIS），扩展必须编译为线程安全版本（使用 phpize 时会自动检测），在访问全局变量时，必须使用线程本地存储 (TSRM) 宏（如 TSRMLS_FETCH(), TSRMG）来访问线程隔离的全局数据，仔细阅读Zend API文档中关于线程安全的部分。

8. 错误处理： 使用 php_error_docref 或 zend_throw_error 等函数抛出 PHP 可捕获的错误 (E_WARNING, E_ERROR, E_EXCEPTION)，避免直接输出到 stderr。

9. 测试： 为你的扩展编写 PHPT 测试用例（放在 tests/ 目录下）是保证质量和兼容性的关键，学习 PHPT 测试文件的语法。

为什么选择C扩展？核心价值与应用场景

• 极致性能： C代码编译后直接运行，避免了PHP解释器的开销，在处理大量数据、复杂算法、循环密集型任务时性能提升显著（可能数倍甚至百倍）。
• 系统级访问： 直接调用操作系统API（文件、网络、进程、信号）、访问特定硬件设备或使用专有的C/C++库（如图形处理、加密库、数据库客户端）。
• 封装遗留代码： 将已有的、稳定的C/C++库或功能集成到PHP应用中。
• 内存控制： 对内存分配和生命周期有更精细的控制（但也意味着更大的责任）。
• 突破语言限制： 实现PHP语法本身难以表达或效率极低的操作。

开启高性能PHP之门

掌握C语言开发PHP扩展是一项强大而专业的技能,它使你能够深入PHP核心，突破脚本语言的性能瓶颈，实现更底层、更高效的功能集成，虽然入门有一定门槛，涉及Zend引擎API、内存管理、线程安全等复杂概念，但带来的性能收益和功能扩展能力是巨大的，从简单的函数封装开始，逐步学习操作复杂数据结构、定义类、管理资源，并严格遵守内存管理和线程安全的最佳实践，你就能构建出稳定、高效、专业的PHP扩展，为你的应用注入强大的原生动力。

思考与实践：

1. 性能临界点： 你认为在什么情况下，PHP原生代码的性能瓶颈会真正成为问题，从而需要C扩展来解决？你能想到一个具体的业务场景吗？
2. 内存陷阱： 在C扩展中，如果不小心在某个请求结束后仍然持有对一个zval的引用而没有正确减少其引用计数，会导致什么后果？如何避免？
3. 现代替代方案： 除了传统的C扩展，像FFI（Foreign Function Interface）这样的技术是否能在某些场景下替代C扩展？FFI的优势和局限性在哪里？你更倾向于在什么情况下使用FFI，什么情况下坚持使用C扩展？

欢迎在评论区分享你的见解、开发经验或遇到的挑战！