Eloquent 模型的 disposable 属性易致内存泄漏，因 PHP GC 对循环引用不敏感，且无自动资源释放机制；须手动定义并调用 dispose() 方法显式清理，尤其在 CLI 或 Swoole 长连接中。
为什么 Eloquent 模型里的 disposable 属性会引发内存泄漏
PHP 的 GC 机制对循环引用不敏感，而 Eloquent 模型常通过 $casts、get*Attribute 或访问器间接持有资源对象（如 ResourceHandle、PDOStatement、自定义封装的 FileReader），若未显式释放，模型实例生命周期结束时这些对象仍驻留内存。尤其在 CLI 命令或长连接 Swoole 服务中，多次查询后内存持续上涨——这不是 Laravel Bug，是 PHP 对象生命周期与资源管理脱节的典型表现。
- 模型被
unset()或超出作用域后，只要存在未断开的引用（比如闭包里捕获了 $this，或静态缓存中保留了实例），资源不会自动__destruct() -
__destruct()不保证执行时机，也不能 throw 异常或 await 异步操作，不适合做关键清理 - Laravel 自身不提供模型级资源销毁钩子，
booted/creating等事件只在生命周期前端触发
手动调用 dispose() 是最可控的方式
不要依赖 PHP 自动回收，给需要处置的属性定义明确的清理方法，并在业务逻辑终点主动调用。这是目前唯一能稳定控制资源释放时机的做法。
- 在模型中添加
public function dispose(): void，内部逐个检查并调用属性的close()、destroy()或__invoke()（如果它是可调用对象） - 避免在
__destruct()中重复调用，防止双重释放导致警告（如 “Trying to close already closed resource”） - 若属性是第三方类且无
close()方法，用is_object($prop) && method_exists($prop, '__destruct')判断也不可靠，应改用接口约束（如实现Disposables\Disposable接口）
class Document extends Model
{
protected $disposableResource;
public function getPreview(): PreviewRenderer
{
return $this->disposableResource ??= new PreviewRenderer($this->path);
}
public function dispose(): void
{
if ($this->disposableResource instanceof Disposable) {
$this->disposableResource->dispose();
$this->disposableResource = null;
}
}
}
// 使用后立即释放
$doc = Document::find(123);
$preview = $doc->getPreview();
echo $preview->render();
$doc->dispose(); // ← 关键：不能省略
批量查询时如何避免漏掉 dispose()
用 Collection::each() 或 foreach 遍历模型列表时，很容易忘记逐个调用 dispose()，尤其嵌套在分页、map 或高阶函数中。
- 禁止在
map()回调里调用dispose()后返回null—— 这会破坏数据流，且后续代码可能因空值报错 - 推荐用
tap()+ 后置清理，或封装为withDisposal()辅助方法 - 在命令行任务中，可在
finally块统一处理，但要注意：集合中的模型可能已被修改或重新赋值，需确保引用的是原始实例
// ✅ 安全的批量清理
$docs = Document::where('status', 'active')->limit(100)->get();
try {
$docs->each(function ($doc) {
$preview = $doc->getPreview();
// ... 处理逻辑
generateThumbnail($preview);
});
} finally {
$docs->each->dispose(); // ← 显式遍历调用，不依赖 GC
}
用 __clone() 防止资源被意外共享
当模型被 clone（比如用于对比、快照或队列任务序列化前），默认会浅拷贝所有属性，包括已初始化的 disposable 对象。两个模型实例指向同一底层资源，先 dispose 的那个会让另一个失效。
立即学习“PHP免费学习笔记（深入）”；
- 重写
__clone()，对所有 disposable 属性设为null，强制下次访问时重建 - 不要在
__clone()里调用原对象的dispose()—— clone 不等于销毁原对象 - 如果资源创建开销大，可考虑加锁或缓存池，但绝大多数场景下“按需重建”更安全
public function __clone()
{
$this->disposableResource = null; // 下次 getPreview() 会新建
}
Laravel 没有内置的模型资源生命周期管理，dispose() 必须由你来决定何时调用、在哪调用、是否可重入。最容易被忽略的是：**CLI 命令里查完一批模型就直接 exit，根本没机会走任何析构逻辑——必须把 dispose() 当成和 save() 一样需要显式编码的关键步骤。** 
