PHP 8.5迁移时处理魔术序列化弃用

把项目从 PHP 8.4 升到 PHP 8.5 后，如果日志里出现与 __sleep() 或 __wakeup() 有关的弃用提示，不需要把序列化功能整体删掉。正确的迁移方向是：新代码用 __serialize() 和 __unserialize() 明确描述对象载荷；只有在还要读取旧格式时，才保留 Serializable 的兼容入口。

官方地址：https://www.php.net/releases/8_5_0.php

PHP 8.5 把 __sleep() 和 __wakeup() 标记为软弃用，它们暂时仍能工作，但新旧代码都应该逐步转向新的魔术方法。下面用一个会写入会话或缓存的对象说明迁移方式。

PHP 8.5 到底弃用了什么

这里有两个容易混淆的概念。第一，__sleep() 与 __wakeup() 是对象序列化生命周期中的旧魔术方法；第二，Serializable 是更早时期提供的接口。PHP 8.5 针对的是前一组魔术方法的软弃用，不能简单理解成“所有序列化对象都不能用了”。

现代写法把“要写入哪些数据”和“如何恢复对象状态”分别放进两个返回值明确的方法：

• __serialize(): array 返回键值数组，作为对象的可存储表示。
• __unserialize(array $data): void 接收这个数组，并恢复对象需要的属性。

迁移时最重要的判断不是“看到弃用就改成任意方法”，而是先确认这个类有没有历史载荷需要读取。如果只有当前版本自己写、自己读，通常直接迁移新魔术方法即可；如果缓存、会话或队列里可能留着旧数据，就需要保留一层兼容转换。

先盘点类里的序列化入口

不要先改方法名，再去猜数据是否兼容。可以先在代码库中按三组关键词盘点：

# 先找出旧魔术方法、接口实现和序列化调用点
rg -n "__sleep|__wakeup|__serialize|__unserialize|implements[[:space:]]+Serializable|serialize\(|unserialize\(" src tests

# 再把会跨请求保存的载荷来源单独列出来
rg -n "session|cache|queue|payload|serialize|unserialize" src tests

盘点结果建议分成三类：

尤其要找出载荷的保存周期。只在同一次请求内调用 serialize() 的对象，兼容压力通常较小；写进长期缓存、数据库或队列的对象，则必须考虑旧版本已经产生的字符串。

把旧魔术方法迁移到显式载荷

下面的示例把用户标识和功能开关作为载荷，连接、文件句柄等运行时资源不进入序列化结果。新方法返回一个稳定的关联数组，恢复时使用默认值应对新增字段。

userId = $userId;
        $this->flags = $flags;
    }

    public function __serialize(): array
    {
        // 只保存可重建对象状态的数据，不把连接等运行时资源写入载荷。
        return [
            'user_id' => $this->userId,
            'flags' => $this->flags,
        ];
    }

    public function __unserialize(array $data): void
    {
        // 对新字段给默认值，避免旧载荷缺少字段时直接访问数组键。
        $this->userId = (string) ($data['user_id'] ?? '');
        $this->flags = is_array($data['flags'] ?? null)
            ? $data['flags']
            : [];
    }
}

$session = new UserSession('u-1001', ['dark_mode' => true]);
$payload = serialize($session); // 序列化时会调用 __serialize()。
$restored = unserialize($payload, [
    'allowed_classes' => [UserSession::class], // 只允许恢复目标类。
]);

这里不是把 __sleep() 的返回值原样改名。新方法的契约本来就是返回键值数组，因此可以顺手把载荷字段改成稳定的外部名称，并在 __unserialize() 中集中处理缺失字段、类型和默认值。

__serialize() 与 __unserialize() 存在时，serialize() 会优先使用新方法；旧的 __sleep() 不再是迁移后的主入口。新旧方法不要各写一份容易漂移的字段清单。

需要兼容旧载荷时怎么保留接口

如果历史数据来自 PHP 7.3 或更早版本，或者某个外部组件仍写出 Serializable 格式，不能只保留新方法后就假定所有旧字符串都能按同一格式读取。官方手册说明：较新的载荷会进入 __unserialize()，更早的接口格式仍可能进入 Serializable::unserialize()。

这时可以让接口方法只负责“格式转换”，最终仍调用同一个 __unserialize()：

 $this->userId,
            'flags' => $this->flags,
        ];
    }

    public function __unserialize(array $data): void
    {
        // 所有格式最终都汇入这一处，避免恢复规则分叉。
        $this->userId = (string) ($data['user_id'] ?? '');
        $this->flags = is_array($data['flags'] ?? null)
            ? $data['flags']
            : [];
    }

    public function serialize(): ?string
    {
        // 兼容仍要求 Serializable 的调用方，但新写入使用同一份数据。
        return serialize($this->__serialize());
    }

    public function unserialize(string $data): void
    {
        // 旧接口载荷只允许还原数组，避免把未知对象带入恢复过程。
        $decoded = unserialize($data, ['allowed_classes' => false]);
        if (!is_array($decoded)) {
            throw new UnexpectedValueException('旧序列化载荷不是数组');
        }
        $this->__unserialize($decoded);
    }
}

这段兼容代码的重点是“统一恢复逻辑”，而不是永久保留旧接口。等历史载荷都完成迁移、外部调用方也不再依赖接口后，可以再评估是否删除 Serializable。如果类只是内部短生命周期对象，没有旧格式读取责任，就不必为了形式上的兼容增加接口。

反序列化安全和回归检查

迁移弃用方法时不要忽略反序列化本身的风险。PHP 手册明确提醒，不要把不可信用户输入直接传给 unserialize()；allowed_classes 可以限制可恢复的类，但不能把不可信输入变成安全输入。外部数据优先使用 JSON 等面向数据的格式，确实要读取内部历史载荷时，应先限制来源和允许的类。

上线前至少做下面几项检查：

1. 新实例经过 serialize() 与 unserialize() 后，关键业务属性保持一致。
2. 准备一份旧版本产生的载荷，确认兼容入口能把它转换到同一对象状态。
3. 给新字段缺失、类型不符和空数组分别准备输入，确认默认值和异常策略符合业务要求。
4. 确认调用点没有把请求参数、Cookie 或任意外部文本直接交给 unserialize()。
5. 在 PHP 8.5 的日志环境中检查旧魔术方法是否仍被调用，并将迁移后的弃用提示纳入发布观察。

 [UserSession::class],
    ]);

    if (!$value instanceof UserSession) {
        // 类型不符合时立即失败，不把半恢复对象交给后续业务。
        throw new UnexpectedValueException('会话载荷类型不正确');
    }

    return $value;
}

迁移结论

PHP 8.5 的处理顺序可以压缩成一句话：新写入使用 __serialize()，新读取使用 __unserialize()；只有确实存在旧 Serializable 载荷时，才保留接口方法并把它们转换到同一恢复逻辑。这样既能消除旧魔术方法的迁移压力，也不会因为一次升级丢掉仍在缓存或队列中的历史数据。

相关问题

PHP 8.5 是不是不能再使用 serialize()

不是。软弃用针对的是 __sleep() 和 __wakeup() 这组旧魔术方法；serialize() 仍可使用，只是对象应优先提供新魔术方法。

只把 __sleep() 改名为 __serialize() 可以吗

不建议直接改名。两者返回值契约不同，迁移时应明确返回键值数组，并为恢复过程定义缺失字段和类型处理。

实现了 Serializable 还需要 __serialize()

如果需要兼容较早的接口载荷或消除旧提示，可以同时实现新魔术方法和接口方法；如果没有历史格式责任，则可以按项目调用方逐步移除接口。