PHP WeakReference 与 WeakMap 怎样选择

在 PHP 里遇到“想记住一个对象，但又不希望这份记录把对象一直留住”的需求时，WeakReference 和 WeakMap 很容易被混在一起。我的判断标准很简单：只需要稍后试探一个对象，用 WeakReference；需要按对象保存临时元数据或缓存，用 WeakMap。

两者都不会像普通变量那样增加目标对象的强引用，但数据形状不同。WeakReference 只有“这个对象现在还活着吗”这一层关系；WeakMap 则是“这个对象对应哪份临时数据”。

先看关联关系再选类：单个可失效句柄选 WeakReference，对象到附加数据的弱映射选 WeakMap。若数据必须持久保存、必须跨请求恢复，二者都不是存储方案。

官方文档：https://www.php.net/manual/en/class.weakreference.php

WeakMap 文档：https://www.php.net/manual/en/class.weakmap.php

先把“记住对象”和“给对象挂数据”分开

假设一个请求里有一个解析器对象。某个调度器想在稍后尝试调用它，但调度器不应该因为自己的记录让解析器继续存活，这就是单对象句柄问题。WeakReference 保存的是一个可以失效的观察入口，调用 get() 时才知道对象是否仍可用。

另一种情况是：每个实体对象都需要一份请求内的解析结果、调试标签或临时状态，而这些附加数据不应成为实体的正式属性。这是对象到数据的映射问题。WeakMap 用对象作为键，键不会因为出现在映射中而额外增加对象引用计数。

只想试探一个对象时用 WeakReference

WeakReference 不能直接通过构造函数实例化，通常用 WeakReference::create() 创建。之后通过 get() 读取对象；如果目标对象已经没有其他强引用，get() 会返回 null。这个返回值不是异常，而是弱引用本来就应该暴露的生命周期结果。

get();
if ($current !== null) {
    echo $current->name, PHP_EOL;
}

unset($session);

// 原对象没有其他强引用后，弱引用只剩下“不可用”的结果。
var_dump($handle->get() === null); // bool(true)
?>

这个模式适合观察一个可选依赖、给调试器保留对象入口，或者保存“下次有机会再使用”的对象句柄。读取后如果把返回对象放进全局数组、静态属性或长期队列，新的强引用仍会延长对象生命周期；WeakReference 不会替你阻止这种事情。

需要按对象保存临时数据时用 WeakMap

WeakMap 的键必须是对象，值可以是任意类型。它实现了数组式访问、Countable 和可遍历接口，所以适合维护“对象对应的临时结果”。当对象不再被外部代码引用时，对应条目也可以从 WeakMap 中消失。

 true,
    'source' => 'request',
];

if (isset($metadata[$entity])) {
    echo $metadata[$entity]['source'], PHP_EOL;
}

echo count($metadata), PHP_EOL; // 1
unset($entity);

// 最后一个外部对象引用释放后，弱键对应的条目不再参与映射。
echo count($metadata), PHP_EOL; // 0
?>

WeakMap 的价值不是“让缓存永远自动清理”，而是把清理条件绑定到对象生命周期。它特别适合对象派生的解析缓存、请求内注释、临时计算结果和不值得写进领域对象的辅助状态。

四个维度决定该选哪一个

如果你的代码需要列出所有仍然存活的对象及其数据，WeakMap 具有更直接的遍历能力；如果只需要“拿到这个对象，拿不到就跳过”，WeakReference 更轻。若业务要求对象一定要注册、一定要被找到，反而应该使用明确的强引用容器，再设计主动删除策略。

几个容易误判的生命周期边界

看到 null 不代表 WeakReference 出错

WeakReference::get() 返回 null 的语义就是目标对象已经不可用。调用方应把它当成分支条件：能取到就继续，取不到就重新创建、跳过或返回降级结果。不要把 get() 的结果无条件塞进长期属性，否则等于把弱观察重新变成强持有。

WeakMap 里还有条目，不代表对象无法回收

只要业务代码、闭包、静态变量、队列或调试数据仍保留对象的强引用，WeakMap 的键就仍然有效。排查时应先寻找所有强引用来源，而不是反复调用 unset()。同样，WeakMap 的值如果保存了会把对象图重新连回来的对象，也需要按实际引用关系检查，不能把“弱键”理解成整张图都会自动断开。

弱引用不是跨请求缓存

PHP-FPM、CLI 命令或队列进程的生命周期各不相同，WeakReference 和 WeakMap 都只描述当前进程中的对象关系。要跨请求共享数据，应使用明确的缓存、数据库或消息系统，并用可序列化的标识关联对象，而不是尝试序列化弱引用。

我的选型清单

1. 问题是“这个对象还活着吗”，且只关心一个对象：选 WeakReference。
2. 问题是“这个对象对应哪份临时数据”，且数据不应延长对象寿命：选 WeakMap。
3. 问题是“所有对象必须被注册并可明确找回”：使用强引用容器，并补上删除或过期策略。
4. 问题是“数据要跨请求或重启恢复”：使用持久化存储，弱引用类不承担这个职责。
5. 问题是“对象怎么还没回收”：从强引用、闭包、静态属性、容器值和进程生命周期逐项排查。

一句话收束：WeakReference 是对对象生命周期的低承诺观察，WeakMap 是不拥有对象的对象数据表。先确认你需要的是“一个可失效的对象入口”，还是“按对象组织的临时数据”，选型就不会被两个类名带偏。

相关问题

• WeakReference 可以序列化吗？不应把它当作可序列化句柄；需要保存时改存业务标识。
• WeakMap 的键可以是字符串吗？不可以，WeakMap 的键必须是对象。
• WeakMap 能替代所有缓存吗？不能，它只适合绑定对象生命周期的进程内临时数据。
• 什么时候应该用普通数组？当数据必须明确持有、遍历、序列化或跨生命周期保留时，普通数组更直白。