PHP WeakMap 怎样关联对象元数据而不阻止回收

长生命周期的 PHP worker 经常需要给对象挂一份派生信息，例如请求对象对应的日志标签、解析结果或一次计算的缓存。问题在于，普通数组不能直接用对象做键，而 SplObjectStorage 会持有对象本身，辅助数据可能因此把业务对象留得比预期更久。WeakMap 的关键语义是：它接受对象作为键，但键不会增加对象的引用计数；当对象只剩 WeakMap 这一条引用时，对象被回收，条目也会被移除。

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

影响面：辅助缓存让对象迟迟不回收

一次常见故障是：请求处理已经结束，业务代码也没有继续使用对象，但 worker 的内存曲线仍缓慢上升。排查后发现，代码用对象标识保存元数据，并把对象继续放进一个长期存活的容器。容器只是为了“方便下次查”，却无意中变成了对象的拥有者。

修复的判断标准不是“能不能查到这份元数据”，而是“元数据是否应该决定对象还能活多久”。如果答案是否定的，WeakMap 才是合适的关系：对象是生命周期锚点，缓存只是附属信息。

触发条件：强引用容器和弱键容器的结果不同

可以先用下面的表格判断容器语义。数组通常需要把对象转换为标识，转换后的键与对象生命周期没有自动关系；SplObjectStorage 适合“容器需要管理这些对象”的场景；WeakMap 则适合对象已经由别处管理，当前结构只做伴随数据。

下面的示例把请求对象和日志元数据绑定起来。代码中的 count() 只用来观察条目数量；它不是把对象转成永久索引的替代品。

 '/reports', 'sampled' => true];

if ($metadata->offsetExists($request)) {
    // 读取时仍使用同一个对象引用，而不是重新拼接对象 ID。
    $route = $metadata[$request]['route'];
}

// 业务代码不再需要请求对象后，解除外部引用。
unset($request);
// 这里的数量用于观察：对象被回收后，WeakMap 条目会随之消失。
echo $metadata->count();
?>

根因边界：WeakMap 只弱化键，不弱化值

WeakMap 的“弱”不能理解成整张表都不会保留引用。它针对的是对象键：键不会因为进入 WeakMap 就增加引用计数。值仍按普通 PHP 值保存，因此值里如果放入另一个大型对象、闭包或回指关系，仍要按强引用来评估。

另一个容易误判的点是遍历。WeakMap 实现了 Traversable、Countable 和 ArrayAccess，但遍历时看到的条目只代表那些对象此刻还活着；它不等于业务系统中的“有效记录”。如果对象还被其他服务持有，条目可能继续存在；如果对象已经没有外部引用，条目则会在回收时消失。

修复与防复发：把生命周期判断写进代码评审清单

落地时可以按四项检查：第一，键是否确实是对象，而不是为了使用 WeakMap 临时包装的标量；第二，元数据是否在对象结束后就没有价值；第三，值是否意外保存了会延长其他资源生命周期的对象或闭包；第四，当前场景是否其实要求容器拥有对象，如果要求拥有，就不要用 WeakMap 掩盖强引用需求。

当需要手动删除单个关联时，可以使用 unset($metadata[$object])；当需要判断关联是否存在时，用 offsetExists($object)，不要用对象 ID 去猜。调试时记录条目数量和对象创建/销毁路径，能比单看 worker 总内存更快定位“缓存变成所有者”的问题。

常见问题

WeakMap 可以用字符串作为键吗？

不可以。它的键语义是对象；字符串、整数等标量不属于这个用途，应回到普通数组或其他明确的索引结构。

对象还有其他引用时，WeakMap 会立即删除条目吗？

不会。只要对象仍被业务变量、容器或其他服务引用，它就还活着，WeakMap 条目也可以继续访问。

什么时候应该选择 SplObjectStorage？

当容器需要管理对象集合、遍历集合并让对象跟随容器存活时，强引用语义才是目标；不要为了追求“自动清理”把这种拥有关系误换成 WeakMap。