PHP FFI::new 怎么管理 C 结构体内存：作用域释放、指针类型与生产禁用边界

给 PHP 接一段现成的 C 库时，真正容易出错的通常不是把结构体声明写出来，而是忘了这块内存到底由谁收尾。FFI::new() 返回的是 FFI\CData，默认创建托管数据；一旦把 owned 改成 false，释放责任就转到了调用方，继续把它当普通 PHP 对象使用会留下很难追的泄漏或悬空指针问题。

先用 owned=true 验证结构体和指针访问，再在确有跨请求或 C 库所有权要求时考虑 persistent 与 FFI::free()；生产环境还要先确认 ffi.enable 的安全策略。

先把 FFI::new 的三个参数分开

FFI::new($type, $owned = true, $persistent = false) 看起来只是一个工厂方法，实际同时决定了数据类型、所有权和分配位置。最稳妥的阅读顺序是先看返回的 FFI\CData，再看它是不是 owned，最后才讨论是否要放到 persistent 堆。

官方手册对 managed 和 unmanaged 的区分很明确：托管数据在最后一个 CData 引用被释放时回收；非托管数据则要求调用 FFI::free()。这两个概念不要和 PHP 变量是否还在作用域内混为一谈。

用一个 Message 结构体看懂 CData 的边界

假设 C 库接收一个固定长度的消息，结构体只有正文中会继续使用的两个字段：code 和 payload。下面的声明只展示内存模型，不把它包装成可以直接接收外部输入的 Web 接口。

new('Message');
$message->code = 200;
FFI::memset($message->payload, 0, 32);
echo $message->code;

这里的 $message 是一个 CData 引用。它不是普通数组，字段访问最终对应 C 结构体的内存布局；当变量和其他引用都消失后，默认的托管结构体才会被回收。若 C 库还保存了指向 payload 的指针，就必须让 $message 活得足够久，不能在调用返回后立刻释放。

owned=false 什么时候需要 FFI::free

非托管数据适合“内存由外部 C API 负责”的场景，但这也意味着 PHP 不再替你兜底。一个小型适配层至少要把创建、交给 C 库、释放这三处责任写在一起，避免未来维护者只看到一个裸指针。

$buffer = $ffi->new('char[32]', false);
try {
    FFI::memset($buffer, 0, 32);
    // 调用只接受这块缓冲区的 C 函数
} finally {
    FFI::free($buffer);
    $buffer = null;
}

finally 不是装饰：C 函数抛出异常、参数校验失败或中途返回时，都应该走同一个清理出口。释放后不要再读取 $buffer，也不要把它存进缓存、静态属性或异步回调。

persistent 不是“永远安全”的缓存

persistent=true 会把数据放到系统堆，适合和预加载或长生命周期绑定一起设计的场景。它并不会自动把 CData 变成跨请求安全的共享对象，也不会修复结构体字段类型写错、指针指向已释放内存等问题。

如果只是一次请求内完成编码、调用和读取，保留默认的 owned=true, persistent=false 更容易审查。只有当外部库明确要求稳定的系统堆地址，或预加载方案已经定义了统一的销毁责任，才值得把这两个参数写出来。

生产部署先看 ffi.enable

FFI 能加载共享库并访问 C 数据结构，权限能力远高于普通业务对象。PHP 官方文档也提醒它属于低层且危险的接口，可通过 ffi.enable 限制使用。Web 进程不应因为某个页面需要转换数据，就给所有请求开放任意 C 声明和共享库加载能力。

• 把 FFI 调用收进独立适配层，业务代码只接收经过校验的 PHP 值。
• 禁止把用户输入直接拼进 C 类型声明、库路径或函数名。
• 部署时分别核对 CLI、FPM 和预加载配置，不能只看本机 CLI 的结果。
• 升级 PHP 或共享库后，重新检查结构体对齐、指针宽度和释放责任。

常见问题

FFI::new 默认会自动释放吗？

默认 owned=true 时，托管数据随最后一个 CData 引用释放；这不适用于 owned=false 创建的非托管数据。

FFI::free 可以释放普通的 CData 吗？

它用于释放非托管数据结构。托管对象应交给 PHP 的引用计数和垃圾回收处理，不要把两套所有权混用。

persistent=true 能解决跨请求共享吗？

不能单独解决。它只改变分配位置，跨请求可见性、并发访问、初始化和销毁都需要独立的预加载设计。

线上 PHP-FPM 应该打开 FFI 吗？

通常不应面向普通请求开放。先按最小权限检查 ffi.enable，把确有必要的调用隔离到受控进程或专用服务。

把所有权写进适配层

FFI 的难点不在于记住一个方法签名，而在于让结构体、指针和释放动作形成一条可审查的边界。先从托管 CData 做最小验证；需要非托管内存时，把 FFI::free() 放进同一段 finally；只有有明确部署理由时才使用 persistent。这样即使底层 C 库发生异常，PHP 代码仍能回答“谁创建、谁使用、谁释放”。