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

保存config.m4。

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

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

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

   zend_module_entrygreeting_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实现。

   staticconstzend_function_entrygreeting_functions[]={PHP_FE(confirm_greeting_compiled,NULL)//初始示例函数，可删除或替换PHP_FE(greet,arginfo_greet)//添加我们自己的函数greetPHP_FE_END//结束标记};
   • PHP_FE宏定义了一个函数：第一个参数是PHP函数名（也是对应的C函数名前缀），第二个参数是参数信息结构体指针（arginfo_）。
   • 删除或替换掉confirm_greeting_compiled这个示例函数，添加我们自己的函数，如greet。

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

   PHP_FUNCTION(greet){charname=NULL;size_tname_len;zend_stringgreeting;//解析参数：期望一个字符串参数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!WelcometotheworldofPHPextensions!",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字符串(charname)及其长度(size_tname_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中添加：

   #ifndefPHP_GREETING_H#definePHP_GREETING_Hexternzend_module_entrygreeting_module_entry;#definephpext_greeting_ptr&greeting_module_entry#definePHP_GREETING_VERSION"0.1.0"//定义扩展版本#ifdefZTS#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,"greetingsupport","enabled");php_info_print_table_row(2,"version",PHP_GREETING_VERSION);php_info_print_table_row(2,"author","YourName<[email protected]>");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. 安装(可选)：

   sudomakeinstall#需要管理员权限

   这会将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-mgrepgreeting

   应该输出greeting，运行：

   php-r'echogreet("Developer");'

   应该输出：Hello,Developer!WelcometotheworldofPHPextensions!。

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

1. 使用zend_stringAPI：PHP7+引入了zend_string作为内部字符串表示，优先使用zend_stringAPI(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,HashTableAPI)和对象(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–ZendThreadSafety)：如果你的PHP运行在多线程环境（如ApacheMPMworker/event,IIS），扩展必须编译为线程安全版本（使用phpize时会自动检测），在访问全局变量时，必须使用线程本地存储(TSRM)宏（如TSRMLS_FETCH(),TSRMG）来访问线程隔离的全局数据，仔细阅读ZendAPI文档中关于线程安全的部分。

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（ForeignFunctionInterface）这样的技术是否能在某些场景下替代C扩展？FFI的优势和局限性在哪里？你更倾向于在什么情况下使用FFI，什么情况下坚持使用C扩展？

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