PHP 8.5 unserialize 相关魔术方法怎样迁移

PHP 8.5 的变化不是让 unserialize() 失效，而是把旧的 __sleep()、__wakeup() 对象序列化机制标记为软弃用。迁移的核心，是让对象明确返回一份可持久化的数组，再在恢复时把这份数组转换回对象状态。

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

如果项目仍要读取历史数据，可以先保留兼容入口，再把新写入统一切到 __serialize() 和 __unserialize()。这一步与安全边界要分开处理：无论使用哪种魔术方法，都不要把不可信字符串直接交给 unserialize()。

先区分软弃用、兼容和安全风险

PHP 8.5 的迁移信号来自 __sleep() 和 __wakeup()，不是来自函数名 unserialize()。新机制从 PHP 7.4 已经可用，签名分别是 public function __serialize(): array 和 public function __unserialize(array $data): void。如果两个机制同时存在，序列化优先使用新钩子；恢复对象时，__unserialize() 也优先于 __wakeup()。

Serializable 还可能出现在老项目中。它的旧载荷通常以接口格式保存，而新钩子使用普通对象序列化格式。迁移时不要把“改了方法名”误当成“历史数据已经转换”，要先盘点存量载荷的来源、格式和读写双方的 PHP 版本。

用 __serialize() 明确写入哪些状态

迁移时不要把 __sleep() 返回的属性名机械改成数组。新方法应返回一个稳定的数据契约：保存业务上需要跨请求恢复的字段，排除数据库连接、文件句柄、临时缓存等运行时资源。

 $this->userId,
            'scopes' => array_values($this->scopes),
            'expires_at' => $this->expiresAt?->format(DateTimeInterface::ATOM),
        ];
    }

    public function __unserialize(array $data): void
    {
        // 先读取并约束字段，再恢复对象；缺少关键字段就拒绝载荷。
        if (!isset($data['user_id']) || !is_string($data['user_id'])) {
            throw new UnexpectedValueException('user_id 缺失或类型错误');
        }
        if (!isset($data['scopes']) || !is_array($data['scopes'])) {
            throw new UnexpectedValueException('scopes 缺失或类型错误');
        }

        $this->userId = $data['user_id'];
        $this->scopes = array_values(array_filter(
            $data['scopes'],
            static fn (mixed $scope): bool => is_string($scope),
        ));
        $this->expiresAt = isset($data['expires_at'])
            ? new DateTimeImmutable((string) $data['expires_at'])
            : null;
    }
}

$payload = serialize(new UserSession('u-42', ['read'], null));
$session = unserialize($payload, ['allowed_classes' => [UserSession::class]]);
?>

这里的重点不是数组字段名本身，而是“写入格式由类负责定义”。__serialize() 返回的数组会由 PHP 负责编码；__unserialize() 接收恢复后的数组，并可以在此处做字段存在性、类型和取值范围处理。

让恢复过程兼容旧载荷

如果数据库、Session 或队列中仍有旧数据，先区分两类兼容：PHP 7.4 及以上版本能够识别新钩子；更早版本会忽略它们，因此跨版本部署时需要明确最低版本。另一方面，旧的 Serializable 载荷可能仍要由同一个类读取。

 $this->key, 'value' => $this->value];
    }

    public function __unserialize(array $data): void
    {
        // 对新格式做最小恢复；复杂值仍应由业务层进一步校验。
        $this->key = is_string($data['key'] ?? null) ? $data['key'] : '';
        $this->value = $data['value'] ?? null;
    }

    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);
    }
}
?>

这个兼容层只适合有明确历史数据边界的类。新代码不应为了“看起来兼容”而继续产生旧格式；可以先让读路径兼容，再在写路径切换完成后安排历史数据重编码或自然过期。

把 unserialize() 放进威胁模型

PHP 官方明确警告：不要把不可信用户输入传给 unserialize()。即使设置了 allowed_classes，对象实例化和自动加载仍可能扩大攻击面。外部接口、Cookie、导入文件和可被用户修改的缓存都不应默认视为可信来源。

如果必须读取外部保存的 PHP 序列化数据，至少同时做三件事：一是限制允许的类，二是用 hash_hmac() 等方式验证数据未被篡改，三是让 __unserialize() 对字段做类型和业务范围检查。新系统若能控制格式，优先使用 JSON 等更适合边界交换的格式。

 [CacheEntry::class],
        'max_depth' => 64,
    ]);
    if (!$value instanceof CacheEntry) {
        throw new UnexpectedValueException('缓存对象类型不符合预期');
    }
    return $value;
}
?>

allowed_classes 不是“安全开关”，而是缩小对象恢复范围的控制项；签名验证也不能替代字段校验。迁移完成后，应在日志中记录旧格式读取次数、非法类名、签名失败和字段恢复异常，等旧格式读数归零再删除兼容方法。

迁移清单与常见问题

• 先查类中是否存在 __sleep()、__wakeup() 或 Serializable，再确认历史载荷来源。
• 新写入使用 __serialize()，恢复使用 __unserialize()，方法签名保持公开且准确。
• 不要序列化连接、句柄和临时状态；恢复后按需重新创建运行时资源。
• 外部载荷先验签，再限制允许类，最后做类型和业务字段检查。
• 在兼容期记录旧载荷命中率，确认数据迁移完成后再移除旧接口。

PHP 8.5 是删除 __sleep() 和 __wakeup() 吗？

不是。当前变化是软弃用，目标是推动新代码改用 __serialize() 和 __unserialize()；项目仍应把弃用提示当作迁移信号处理。

__serialize() 能不能直接返回对象属性？

可以返回数组，但不建议把所有属性无差别暴露进去。应只返回可持久化、可校验、能在目标版本恢复的业务状态。

设置 allowed_classes=false 就能安全 unserialize() 吗？

不能把它当作绝对安全保证。它能限制对象类恢复，但输入解析、资源消耗、自动加载策略和业务数据完整性仍要单独控制；不可信输入最好改用 JSON。