PHP扩展开发关键在于精准调用Zend引擎五大核心API：模块/请求初始化与关闭、ZVAL变量操作、函数注册、内存管理及参数解析，缺一不可。
PHP扩展开发不是写几个C函数就能跑起来的事，关键在能准确调用 Zend 引擎暴露的那几组核心 API——它们控制着内存、变量、函数注册和生命周期。没摸清这些，zend_module_entry 写得再工整也会在 php -m 里看不到你的扩展。
zend_module_entry 和生命周期钩子必须配对使用
这是模块注册的“身份证”，但光有它不够。每个字段都对应真实运行阶段，漏掉或错配会导致段错误或函数不加载：
-
functions字段必须指向有效的zend_function_entry数组，且末尾必须是PHP_FE_END（不是NULL） -
module_startup_func（即PHP_MINIT）是唯一能安全注册函数/类/常量的地方；在这里调用zend_register_function会崩溃 -
request_startup_func（PHP_RINIT）适合分配 per-request 资源，比如初始化一个zend_object实例，但不能注册全局函数 - 如果扩展需要清理全局资源，
PHP_MSHUTDOWN必须显式释放，否则valgrind会报内存泄漏
操作 PHP 变量必须走 Zend 的 ZVAL API
直接声明 zval myvar 或 memcpy 赋值是危险的。PHP 8.6 对引用计数和类型校验更严格，错误操作会导致 zend_error(E_WARNING, "Trying to access array offset on value of type null") 这类难以定位的错误：
- 创建字符串：用
ZVAL_STRING(&retval, "hello")，而不是strcpy手动填充 - 返回数组：先
array_init(&retval)，再用add_assoc_string等宏添加元素，避免手动管理ht指针 - 检查参数：用
ZEND_PARSE_PARAMETERS_START(1, 2)宏，它自动处理类型转换、引用传递和默认值，比手写Z_TYPE_P判断更可靠 - 注意
ZVAL_COPY和ZVAL_DEREF的区别：前者复制值，后者解引用（如从&$x得到$x的实际值）
内存分配必须用 Zend 提供的堆管理器
扩展里用 malloc 或 new 分配内存，PHP 关机时不会帮你回收，MSHUTDOWN 阶段也难追踪。Zend 提供了两套语义明确的分配器：
立即学习“PHP免费学习笔记（深入）”；
- 请求级内存（自动释放）：
emalloc/efree—— 在RINIT分配、RSHUTDOWN自动清理，适合缓存、临时结构体 - 模块级内存（需手动释放）：
malloc+PHP_MSHUTDOWN中free，或更安全地用zend_alloc系列（如zend_string_init返回的zend_string*必须用zend_string_release释放） - 切忌混用：用
emalloc分配的内存传给free会 crash；zend_string不能用efree
PHP 8.6 的类型系统约束直接影响 API 选择
PHP 8.6 强化了联合类型和 readonly 属性支持，扩展层也要响应变化。老代码里常见的 convert_to_long 在 strict 模式下可能触发 TypeError：
- 接收参数时，
ZEND_PARSE_PARAMETERS_START宏已支持zend_parse_parameters的新语法，例如Z_PARAM_STR_OR_NULL(str)显式接受 string|null - 返回值类型声明必须匹配：若 PHP 函数声明为
function foo(): int，C 层必须确保RETURN_LONG，不能用RETURN_BOOL后靠隐式转换 - 对象操作优先用
zend_object_handlers接口，而不是直接读写zend_object成员；PHP 8.6 中get_properties回调签名已变更
最难调试的往往不是编译失败，而是扩展加载后函数存在却返回 NULL、或只在 CLI 下工作而在 FPM 下 segfault——这类问题几乎都卡在 ZVAL 生命周期或内存归属上。动手前先确认你用的 php-config 输出路径和当前运行的 PHP 版本完全一致，否则 php.h 头文件版本错位，连 zval 结构体大小都会对不上。
