lcobucci/jwt 版本升级指南：从 v3.x 到 v5.x 的迁移策略

lcobucci/jwt 版本升级指南：从 v3.x 到 v5.x 的迁移策略

jwt A simple library to work with JSON Web Token and JSON Web Signature 项目地址: https://gitcode.com/gh_mirrors/jw/jwt

前言

lcobucci/jwt 是一个广受欢迎的 PHP JWT 实现库，随着版本的迭代，库的功能和 API 都发生了显著变化。本文将详细介绍从 v3.x 到 v5.x 的升级路径，帮助开发者顺利完成迁移。

升级路线规划

建议采用分阶段升级策略：

1. 先升级到 v3.4.x 版本
2. 修复所有废弃警告
3. 再升级到 v4.x 版本
4. 最后升级到 v5.x 版本

这种渐进式升级能最大限度地减少对现有代码的影响。

从 v3.x 升级到 v4.x

1. 准备工作

首先升级到最新的 3.4.x 版本：

composer require lcobucci/jwt ^3.4

2. 关键变更点

2.1 配置对象引入

v4.x 引入了 Configuration 对象来集中管理 JWT 相关依赖：

// 旧方式
$builder = new Builder();
$signer = new Sha256();
$key = new Key('secret');

// 新方式
$config = Configuration::forSymmetricSigner(
    new Sha256(),
    InMemory::plainText('secret')
);
$builder = $config->builder();

2.2 Key 对象重构

Signer\Key 变成了接口，使用 InMemory 实现类：

// 旧方式
$key = new Key('secret');

// 新方式
$key = InMemory::plainText('secret');

2.3 Builder API 变更

Builder API 有四项主要变化：

1. 方法名变更
2. 签名方式变化
3. 使用 DateTimeImmutable 替代时间戳
4. 需要手动复制头部信息

// 旧方式
$token = (new Builder())
    ->setIssuer('example.com')
    ->setExpiration(time() + 3600)
    ->sign(new Sha256(), 'secret')
    ->getToken();

// 新方式
$now = new DateTimeImmutable();
$token = $config->builder()
    ->issuedBy('example.com')
    ->expiresAt($now->modify('+1 hour'))
    ->getToken($config->signer(), $config->signingKey());

2.4 验证 API 重构

废弃了 Token#verify() 和 Token#validate()，引入新的验证组件：

// 旧方式
$token->validate(new ValidationData());
$token->verify($signer, $key);

// 新方式
$validator = $config->validator();
if (!$validator->validate($token, ...$config->validationConstraints())) {
    throw new InvalidTokenException();
}

2.5 Token API 变更

Token API 变得更加类型安全：

// 旧方式
$headers = $token->getHeaders();
$issuer = $token->getClaim('iss');

// 新方式
$headers = $token->headers()->all();
$issuer = $token->claims()->get('iss');

从 v4.x 升级到 v5.x

1. 准备工作

首先升级到最新的 4.3.x 版本：

composer require lcobucci/jwt ^4.3

2. 关键变更点

2.1 ECDSA 创建方式变更

// 旧方式
$signer = Ecdsa\Sha256::create();

// 新方式
$signer = new Ecdsa\Sha256();

2.2 移除 none 算法

出于安全考虑，移除了不安全的 none 算法：

// 替代方案
$config = Configuration::forSymmetricSigner(
    new Blake2b(),
    InMemory::base64Encoded('secure-key-here')
);

2.3 Builder 变为不可变对象

// 旧方式
$builder->issuedBy('example.com');

// 新方式
$builder = $builder->issuedBy('example.com');

2.4 时钟组件变为可选

lcobucci/clock 不再默认安装，需要显式引入：

composer require lcobucci/clock

升级建议

1. 逐步升级：按照 v3.x → v4.x → v5.x 的顺序进行
2. 全面测试：每次升级后运行完整的测试套件
3. 静态分析：使用 PHPStan 等工具检测废弃用法
4. 关注性能：新版 API 设计更注重性能和类型安全
5. 文档参考：仔细阅读每个版本的更新日志

总结

lcobucci/jwt 从 v3.x 到 v5.x 的升级过程中，主要变化集中在：

1. 配置管理更加集中化
2. API 设计更加类型安全和不可变
3. 验证流程更加灵活
4. 移除了不安全的功能
5. 提高了对现代 PHP 特性的支持

通过遵循本文的升级指南，开发者可以平稳过渡到最新版本，同时获得更好的性能、安全性和开发体验。

jwt A simple library to work with JSON Web Token and JSON Web Signature 项目地址: https://gitcode.com/gh_mirrors/jw/jwt