PHP WeakMap 为什么适合保存对象附加元数据

PHP WeakMap 适合保存对象附加元数据，核心原因是它以对象为键，却不会因为这个键而增加对象的引用计数。当业务代码不再持有该对象时，对象可以被回收，对应的 WeakMap 条目也会随之移除。追踪标签、校验结果、反射信息和派生缓存因此可以与对象同生共灭，而不是悄悄变成长期存活的全局数据。

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

先把小项目的边界定清楚

我第一次需要这种结构，是在请求处理链里给对象附加追踪标签。把 trace_id 直接塞进领域对象很省事，但对象会因此承担与业务无关的职责；用普通数组按 spl_object_id() 存储，又需要手动清理，还要处理标识复用和遗漏释放的问题。

这个小项目只做一件事：实现一个 MetadataRegistry，让任意对象关联一组临时数组数据。它不负责数据库持久化，不负责跨请求共享，也不保证对象消失后还能查询。这样的约束正好匹配 WeakMap 的生命周期语义。

实现一个最小 MetadataRegistry

WeakMap 从 PHP 8 开始可用，只接受对象作为键，并实现了 ArrayAccess、Countable 和可遍历能力。下面的注册表把底层容器封装起来，调用方不需要直接操作 WeakMap。

> */
    private WeakMap $items;

    public function __construct()
    {
        // 弱键不会单独延长目标对象的生命周期
        $this->items = new WeakMap();
    }

    public function put(object $target, array $metadata): void
    {
        // 以对象本身为键，避免手工维护对象 ID
        $this->items[$target] = $metadata;
    }

    public function get(object $target): array
    {
        // WeakMap 中不存在该对象时返回空元数据
        return isset($this->items[$target])
            ? $this->items[$target]
            : [];
    }

    public function count(): int
    {
        // count() 只统计当前仍然存活的映射
        return count($this->items);
    }
}

put() 的参数类型明确限制为对象，这正是 WeakMap 与普通关联数组的主要差别。get() 先用 isset() 判断，避免直接读取不存在的键。注册表只暴露业务需要的三个动作，也防止外部代码依赖具体容器实现。

把它接入请求对象

为了让示例保持小而完整，可以用一个不包含追踪字段的请求对象。元数据注册表在请求进入处理器后记录来源和解析结果，领域对象本身不需要为调试、缓存或框架扩展而增加属性。

put($request, [
    'trace_id' => 'trace-demo-001',
    'normalized' => true,
]);

$metadata = $registry->get($request);
echo $metadata['trace_id'];

这个结构最让我省心的地方，不是少写了一个清理函数，而是对象边界更清楚：ImportRequest 只描述导入请求，MetadataRegistry 只描述处理期间的附加信息。要替换追踪方案时，不必改动领域类。

对象释放后，映射为什么会自动减少

普通容器保存对象键时，容器自身通常会成为对象仍然存活的理由。WeakMap 不会让键增加引用计数；如果业务代码里没有其他引用，垃圾回收后，该对象及对应条目都会离开映射。这正是“附加元数据不能活得比对象更久”的实现基础。

put($request, ['parsed_rows' => 120]);

echo $registry->count(); // 当前对象仍有业务引用，数量为 1

// 删除业务侧最后一个对象变量，WeakMap 不会阻止对象回收
unset($request);
gc_collect_cycles();

echo $registry->count(); // 对应弱键条目已经移除，数量为 0

gc_collect_cycles() 在这里用于让演示更直观，不应该被当成每次写入 WeakMap 后都要调用的业务步骤。真正的设计目标是不要让元数据注册表成为对象的所有者。

WeakMap 和 SplObjectStorage 怎么选

如果容器的职责是“拥有这批对象”，选 SplObjectStorage 更自然；如果容器只是“对象存在时顺便记一点信息”，WeakMap 更贴合。两者表面上都能用对象做键，但生命周期契约完全不同。

验收时重点看四件事

• 键必须是对象：字符串、整数和数组不能直接作为 WeakMap 键。
• 数据必须是可丢弃的：对象释放后仍需查询的数据，应写入持久化存储或由明确所有者保存。
• 不要依赖稳定数量：WeakMap 的数量会随着外部对象引用变化，不适合作为业务库存或审计记录。
• 检查其他强引用：对象仍出现在服务容器、队列、闭包或其他集合中时，WeakMap 条目也会继续存在。

还有一个容易忽略的场景是枚举 case。枚举 case 是长期存在的单例对象，用它作为弱键通常不会获得“对象不用后自动消失”的收益。WeakMap 能否自动清理，最终取决于键对象在程序其他位置是否还有引用。

常见问题

WeakMap 能代替对象缓存吗？

它适合保存由某个对象派生、且不应超过该对象生命周期的缓存。需要按字符串键查询、跨请求复用或主动控制淘汰策略的缓存，应使用更合适的缓存组件。

元数据值可以是对象吗？

可以，WeakMap 的值类型是 mixed。不过仍要检查值与其他服务是否形成强引用关系，不能只看键是弱引用就假定整个对象图一定立即释放。

为什么 unset 后条目还在？

通常是程序中还有另一个变量、集合、闭包或服务持有同一个对象。PHP 的对象变量保存的是指向同一对象的标识副本，删除其中一个变量不代表所有引用都消失。

结论

WeakMap 最适合“对象还活着时才有意义”的附加数据。它让元数据与对象生命周期自然绑定，又不要求污染领域类或维护对象 ID。只要把持久数据、稳定集合和字符串键排除在外，WeakMap 会是 PHP 8 中实现派生缓存、追踪标签和框架级扩展信息的简洁工具。