PHP 序列化对象时 __serialize 怎样控制兼容字段

要让 PHP 对象在字段改名、新增属性或内部重构后仍能读取旧数据，关键不是把所有属性原样交给 serialize()，而是把 __serialize() 返回的数组当成一份小型持久化协议：使用稳定键名，加入明确的 v 版本字段，只保存真正需要跨请求保留的数据；再由 __unserialize() 负责旧键映射、默认值和类型检查。

最稳妥的迁移策略可以概括成一句话：读旧写新。新版本只写当前格式，但在一个明确的兼容窗口内继续读取旧格式。这样，缓存、队列和数据库里的历史载荷不会因为一次类属性重构而突然失效。

官方文档：https://www.php.net/manual/en/language.oop5.magic.php#object.serialize

先确认故障来自持久化结构漂移

序列化兼容问题常被误判成“对象属性莫名其妙为空”。实际排查时，可以先看三个信号：

• 类中的私有属性已经改名，但缓存或数据库仍保存旧对象；
• 新增了有类型声明且没有默认值的属性，恢复后访问时提示未初始化；
• 旧载荷中没有新字段，代码却直接用数组下标读取，产生未定义键或类型错误。

PHP 官方定义的签名是 public function __serialize(): array 与 public function __unserialize(array $data): void。前者返回的元素不必一一对应对象属性，因此完全可以使用稳定的外部键名；后者拿到这个数组后，自行恢复当前类需要的属性。若同一个类还定义了 __sleep() 或 __wakeup()，新钩子优先。

把 __serialize 返回值当成稳定协议

下面的 ProfileSnapshot 在内存中有五个属性，但持久化载荷只暴露一组稳定字段。即使以后把 $displayName 改成别的内部名称，载荷中的 display_name 也可以保持不变。

 self::SCHEMA_VERSION,
            'user_id' => $this->userId,
            'display_name' => $this->displayName,
            'labels' => $this->labels,
            'locale' => $this->locale,
        ];
        // runtimeCache 是运行态数据，不应进入跨请求载荷
    }
}

这里的 v 不是 PHP 语言版本，而是应用自己维护的载荷版本。版本号只在读取规则发生变化时增加，不要每次发布都递增。runtimeCache、数据库连接、文件句柄、闭包以及可以重新计算的派生值通常都不应成为兼容字段。

在 __unserialize 中集中处理旧键

假设旧版本使用 uid、name，新版改成 user_id、display_name，并新增 labels 与 locale。兼容逻辑应集中在 __unserialize()，而不是散落在每个业务调用点。

 self::SCHEMA_VERSION,
            'user_id' => $this->userId,
            'display_name' => $this->displayName,
            'labels' => $this->labels,
            'locale' => $this->locale,
        ];
    }

    public function __unserialize(array $data): void
    {
        // 没有 v 的历史载荷按版本 1 处理
        $version = isset($data['v']) ? (int) $data['v'] : 1;
        if ($version  self::SCHEMA_VERSION) {
            throw new UnexpectedValueException('不支持的序列化版本');
        }

        // 版本 2 使用 user_id，版本 1 继续兼容 uid
        $userId = $data['user_id'] ?? $data['uid'] ?? null;
        if (!is_string($userId) || $userId === '') {
            throw new UnexpectedValueException('user_id 缺失或类型错误');
        }

        // display_name 缺失时读取旧 name，仍缺失则使用明确默认值
        $displayName = $data['display_name'] ?? $data['name'] ?? '未命名用户';
        if (!is_string($displayName)) {
            throw new UnexpectedValueException('display_name 类型错误');
        }

        $labels = $data['labels'] ?? [];
        if (!is_array($labels)) {
            throw new UnexpectedValueException('labels 必须是数组');
        }

        // 只保留字符串标签，避免把异常嵌套对象带入领域状态
        $this->labels = array_values(array_filter(
            $labels,
            static fn (mixed $label): bool => is_string($label)
        ));
        $this->userId = $userId;
        $this->displayName = $displayName;

        $locale = $data['locale'] ?? null;
        $this->locale = is_string($locale) ? $locale : null;

        // 运行态缓存始终重新初始化，不接受载荷中的同名值
        $this->runtimeCache = [];
    }
}

这里有两个重要判断。第一，未知的未来版本不能“尽量猜着读”，因为当前代码并不知道未来字段语义；明确抛出异常比生成半完整对象更安全。第二，新增可选字段可以用默认值补齐，但身份标识这类必填字段缺失时应立即拒绝。

用读旧写新的窗口完成迁移

兼容分支不应该永久增长。一次可控迁移通常分为三段：

1. 部署双读：__unserialize() 同时认识版本 1 和版本 2，__serialize() 只写版本 2。
2. 消化旧数据：等待缓存自然过期、队列消费完毕，或把数据库里的旧载荷批量读取后重新写入。
3. 移除旧分支：确认旧格式数量归零，并且回滚窗口已经关闭，再删除 uid、name 的兼容代码。

这种安排比“同时写两个版本”简单。写入端始终只有一个真相，读取端承担有限期兼容。若载荷会长期保存，应把旧版本样本作为回归夹具保存在测试目录，而不是依赖临时环境里碰巧还存在的数据。

反向检查类型、安全与继承边界

不要跳过类型检查

__unserialize() 是对象恢复边界。先检查数组中的标量类型和容器元素，再赋值给类型属性，可以把问题定位为“载荷不合法”，避免对象进入半初始化状态。对可选字段使用默认值，对必填字段抛出明确异常，两者不要混用。

不可信输入不要交给 unserialize

PHP 官方明确警告：即使设置了 allowed_classes，也不应把不可信用户输入传给 unserialize()。跨系统交换数据优先使用 JSON 等安全的标准格式；如果确实要读取外部存储的序列化字符串，应在应用边界验证完整性，并严格限制数据来源。__serialize() 解决的是格式控制，不是把不可信反序列化变安全。

继承时显式组合父类状态

子类需要父类状态时，可以把 parent::__serialize() 返回的数组放到单独键中，恢复时再交给 parent::__unserialize()。这样父类和子类各自维护自己的兼容版本，避免把所有键摊平成一个容易冲突的大数组。

 1, 'id' => $this->id];
    }

    public function __unserialize(array $data): void
    {
        // 父类独立验证自身必填字段
        if (!isset($data['id']) || !is_string($data['id'])) {
            throw new UnexpectedValueException('父类 id 无效');
        }
        $this->id = $data['id'];
    }
}

final class LabeledRecord extends BaseRecord
{
    private string $label;

    public function __serialize(): array
    {
        // 用 parent 键隔离父类协议，避免同名字段互相覆盖
        return ['v' => 1, 'parent' => parent::__serialize(), 'label' => $this->label];
    }

    public function __unserialize(array $data): void
    {
        // 先验证并恢复父类，再处理子类自己的状态
        if (!isset($data['parent']) || !is_array($data['parent'])) {
            throw new UnexpectedValueException('父类载荷缺失');
        }
        parent::__unserialize($data['parent']);
        $this->label = is_string($data['label'] ?? null) ? $data['label'] : '';
    }
}

发布前逐项核对兼容字段

常见问题

__serialize 返回的键必须和属性同名吗？

不必须。官方文档说明返回数组的元素可以对应属性，但这不是要求。为了兼容性，稳定业务键通常比私有属性名更合适。

同时保留 __sleep 和 __serialize 会调用哪个？

存在 __serialize() 时，序列化会优先使用它，__sleep() 被忽略；读取侧同理，__unserialize() 优先于 __wakeup()。

可以静默接受高于当前版本的载荷吗？

不建议。当前代码无法知道未来格式的必填条件和字段语义，静默接受容易生成错误对象。应明确拒绝，并通过升级消费者或回退生产者解决版本不匹配。

什么时候应该改用 JSON？

当数据要跨语言、跨服务、提供给不可信客户端，或需要长期稳定的公开交换格式时，JSON 通常更合适。PHP 原生序列化更适合受控的内部存储，并且仍要管理版本和完整性。

最终原则很简单：对象属性属于当前实现，序列化字段属于持久化协议。只要把这两个层次拆开，__serialize() 就不只是“挑几个属性保存”，而会成为可维护的兼容边界。