PHP FFI 调用 C 函数前必须确认扩展已加载、C 头文件可读、目标函数符号在运行时真实存在；类型声明须严格匹配，动态库需正确导出符号且 ABI 兼容；避免循环中重复加载或创建对象。
PHP FFI 调用 C 函数前必须确认的三件事
PHP 8.0+ 自带 FFI 扩展，但默认不启用，且调用 C 函数不是“写个 FFI::cdef() 就能跑”。你得先确认：扩展已加载、C 头文件可读、目标函数符号在运行时真实存在。漏掉任一环，FFI::load() 或 FFI::cdef() 都会静默失败或抛出 FFI\Exception，而不是告诉你缺了啥。
- 检查扩展：运行
php -m | grep ffi，无输出说明没启用，需在php.ini中取消;extension=ffi的注释并重启 PHP - 头文件路径必须是绝对路径或相对于当前脚本的可访问路径；相对路径在 CLI 和 Web SAPI 下行为可能不一致
- Linux/macOS 上用
nm -D /path/to/lib.so | grep your_func确认符号存在；Windows 上用dumpbin /exports your.dll；C++ 函数要加extern "C"否则符号名被 mangling
用 FFI::cdef() 声明函数时参数类型不能凭感觉写
C 类型和 PHP 类型没有自动映射关系，FFI::cdef() 里写的每个类型都直接影响内存布局和调用结果。比如把 int* 写成 int，或把 char* 当作 string 直接传，轻则返回乱码，重则段错误。
-
int对应 PHP 的整数，但int*必须用FFI::new('int')创建指针，再传$ptr->getAddress() -
char*在 C 里常表示字符串或字节数组；若用于输入，用FFI::new('char[128]')并手动strcpy；若用于输出，需确保 C 函数已分配内存或使用固定缓冲区 - 结构体必须完整声明字段顺序和类型，字段对齐（
__attribute__((packed))）会影响大小，PHP 侧sizeof($struct)必须等于 C 侧sizeof(struct foo) - 回调函数要用
FFI::callback()包装，且签名必须与 C 函数指针类型严格一致，包括const修饰符
动态库加载失败常见于符号可见性与 ABI 不匹配
即使 FFI::load('libfoo.so') 看似成功，实际调用时仍可能报 undefined symbol: xxx —— 这通常不是路径错，而是符号未导出或 ABI 不兼容。
- Linux 下编译 C 库时加
-fPIC -shared，并确保函数非static；用gcc -shared -o libfoo.so foo.c最简验证 - macOS 需加
-undefined dynamic_lookup，否则符号默认不导出；M1/M2 芯片注意编译为arm64架构，避免 x86_64 二进制混用 - Windows 上 DLL 导出函数需显式用
__declspec(dllexport)，或通过 .def 文件定义导出列表；PHP 进程位数（x64 vs x86）必须与 DLL 一致 - 如果 C 函数依赖其他库（如
libm.so），FFI 不会自动链接，需在FFI::load()前用dl() + dlopen(RTLD_GLOBAL)（不推荐），或改用FFI::cdef()+FFI::load()组合并确保系统 LD_LIBRARY_PATH 包含依赖路径
性能敏感场景下别在循环里反复调用 FFI::load() 或 FFI::new()
每次 FFI::load() 都会解析符号表并建立绑定，FFI::new() 每次都分配新内存。高频调用 C 函数时，这些开销会迅速放大。
立即学习“PHP免费学习笔记（深入）”；
- 把
FFI::load()提到脚本顶层或单例中，复用同一个FFI实例 - 需要重复使用的结构体或数组，用
FFI::new()创建一次，后续通过$obj->field = ...修改字段，而非重建 - 批量处理数据时，优先让 C 函数接收数组指针 + 长度（如
void process(int* data, size_t n)），比 PHP 层循环调用单个元素快一个数量级 - 注意内存所有权：C 分配的内存（如
malloc返回）不能直接由 PHP GC 回收，必须提供对应的free函数并在 PHP 侧显式调用
C 函数调用本身不难，难的是类型对齐、符号可见性、内存生命周期这三处细节——它们不出错时一切正常，一出错就很难定位到根源。尤其是 Windows 下 DLL 导出和 macOS 的符号导出规则，和 Linux 差异明显，别假设一份构建脚本能跨平台跑通。
