核心内容摘要
老狼信息网贰佰金属网加工：精湛工艺，铸就卓越品质
前置准备
安装库使用 Composer 安装 firebase/php-jwt 是使用该库的前提。
composer require firebase/php-jwt
核心类与方法核心类Firebase\JWT\JWT所有操作围绕此类展开核心静态方法JWT::encode()生成 JWT 令牌JWT::decode()验证并解析 JWT 令牌异常类如 Firebase\JWT\ExpiredException、Firebase\JWT\SignatureInvalidException用于捕获验证过程中的异常
核心参数说明
JWT::encode()方法生成 JWT方法签名public static function encode( array $payload, string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $key, string $alg HS256, string $keyId null, array $head null ): string参数详解参数名类型必选说明$payload数组是JWT 的载荷存储业务数据如用户ID、过期时间建议包含注册声明$key字符串/加密资源等是加密密钥
对称加密HS256自定义字符串密钥
非对称加密RS256使用私钥.pem文件内容$alg字符串否加密算法默认HS256。
常用- 对称HS
HS
HS512- 非对称RS
RS
RS512$keyId字符串否密钥 ID多密钥场景下标识当前密钥写入 JWT 头部kid字段$head数组否自定义 JWT 头部信息合并默认头部含alg,typ常用注册声明推荐在$payload使用ississuer签发者如网站域名audaudience接收者如 API 域名subsubject主题如用户唯一标识expexpiration time过期时间Unix 时间戳必填nbfnot before生效时间Unix 时间戳iatissued at签发时间Unix 时间戳jtiJWT ID令牌唯一标识防重放
JWT::decode()方法验证并解析 JWT方法签名public static function decode( string $jwt, string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate|JWKSet $key, array $allowedAlgs [HS256] ): stdClass参数详解参数名类型必选说明$jwt字符串是待验证的 JWT 令牌三段式字符串用.分隔$key字符串/加密资源等是验证密钥
对称加密与生成时相同的字符串密钥
非对称加密公钥.pem文件内容$allowedAlgs数组否允许的加密算法列表默认[HS256]需与生成时一致防止算法伪造攻击返回值验证通过返回 stdClass 对象包含 $payload 所有数据可通过 - 访问属性。
实际使用示例示例 1对称加密HS256简单常用适合单体应用、前后端分离密钥仅服务端保管场景。
主要流程生成 JWT → 验证 JWT → 捕获异常?php //
引入 Composer 自动加载 require_once __DIR__ . /vendor/autoload.php; //
导入核心类和异常类 use Firebase\JWT\JWT; use Firebase\JWT\ExpiredException; use Firebase\JWT\SignatureInvalidException; use UnexpectedValueException; //
配置参数 const SECRET_KEY your-very-strong-secret-key-321-keep-it-safe; const ALGORITHM HS256; // 生成 JWT 令牌 function generateJwtToken(int $userId): string { $payload [ iss https://example.com, aud https://api.example.com, sub (string)$userId, iat time(), exp time() 3600, jti uniqid(jwt_, true), username test_user, role admin ]; return JWT::encode($payload, SECRET_KEY, ALGORITHM); } // 验证并解析 JWT 令牌 function verifyJwtToken(string $jwt): ?stdClass { try { $decoded JWT::decode($jwt, SECRET_KEY, [ALGORITHM]); return $decoded; } catch (ExpiredException $e) { echo 错误JWT 令牌已过期 - . $e-getMessage() . PHP_EOL; } catch (SignatureInvalidException $e) { echo 错误JWT 签名无效 - . $e-getMessage() . PHP_EOL; } catch (UnexpectedValueException $e) { echo 错误JWT 格式无效 - . $e-getMessage() . PHP_EOL; } catch (Exception $e) { echo 错误JWT 验证失败 - . $e-getMessage() . PHP_EOL; } return null; } // 测试 $jwtToken generateJwtToken(
; echo 生成的 JWT 令牌 . PHP_EOL . $jwtToken . PHP_EOL . PHP_EOL; $decodedData verifyJwtToken($jwtToken); if ($decodedData) { echo JWT 验证通过解析的数据 . PHP_EOL; echo 用户ID . $decodedData-sub . PHP_EOL; echo 用户名 . $decodedData-username . PHP_EOL; echo 过期时间 . date(Y-m-d H:i:s, $decodedData-exp) . PHP_EOL; }示例 2非对称加密RS256适合分布式系统适合多服务协作如微服务私钥签发公钥验签安全性更高。
步骤 1生成 RSA 密钥对终端命令# 生成私钥2048 位无密码 openssl genrsa -out private.pem 2048 # 从私钥生成公钥 openssl rsa -in private.pem -pubout -out public.pem步骤 2PHP 代码实现?php require_once __DIR__ . /vendor/autoload.php; use Firebase\JWT\JWT; use Firebase\JWT\ExpiredException; use Firebase\JWT\SignatureInvalidException; use UnexpectedValueException; const PRIVATE_KEY_PATH __DIR__ . /private.pem; const PUBLIC_KEY_PATH __DIR__ . /public.pem; const ALGORITHM RS256; $privateKey file_get_contents(PRIVATE_KEY_PATH); $publicKey file_get_contents(PUBLIC_KEY_PATH); // 私钥生成 JWT function generateRsaJwtToken(int $userId, string $privateKey): string { $payload [ iss https://example.com, sub (string)$userId, iat time(), exp time() 3600, username test_user_rsa ]; return JWT::encode($payload, $privateKey, ALGORITHM); } // 公钥验证 JWT function verifyRsaJwtToken(string $jwt, string $publicKey): ?stdClass { try { $decoded JWT::decode($jwt, $publicKey, [ALGORITHM]); return $decoded; } catch (ExpiredException $e) { echo 错误JWT 令牌已过期 - . $e-getMessage() . PHP_EOL; } catch (SignatureInvalidException $e) { echo 错误JWT 签名无效 - . $e-getMessage() . PHP_EOL; } catch (UnexpectedValueException $e) { echo 错误JWT 格式无效 - . $e-getMessage() . PHP_EOL; } catch (Exception $e) { echo 错误JWT 验证失败 - . $e-getMessage() . PHP_EOL; } return null; } // 测试 $jwtToken generateRsaJwtToken(10087, $privateKey); echo 生成的 RSA JWT 令牌 . PHP_EOL . $jwtToken . PHP_EOL . PHP_EOL; $decodedData verifyRsaJwtToken($jwtToken, $publicKey); if ($decodedData) { echo RSA JWT 验证通过解析的数据 . PHP_EOL; echo 用户ID . $decodedData-sub . PHP_EOL; echo 用户名 . $decodedData-username . PHP_EOL; }
四、
总结汇总核心要点回顾核心操作JWT::encode() 生成令牌JWT::decode() 验证解析令牌依赖密钥及算法。
参数核心生成$payload 必须含 exp$key 按算法类型选择对称字符串非对称私钥验证$key 与生成匹配对称相同字符串非对称公钥$allowedAlgs 包含生成算法安全性注意不在 $payload 存储敏感信息JWT 可被解码严格保管对称密钥/私钥公钥可公开捕获验证异常区分异常类型做针对性处理常用场景对称加密HS256单体应用、前后端分离身份认证非对称加密RS256微服务、跨系统协作
常见问题提醒ExpiredException检查 exp 是否为 Unix 时间戳且大于当前时间注意服务器时区SignatureInvalidException检查密钥匹配、算法一致、令牌未被篡改令牌过长$payload 仅存必要业务标识
总结firebase/php-jwt 以 JWT::encode()生成和 JWT::decode()验证为核心安全性依赖密钥和算法。
对称加密HS256简单高效适合单服务非对称加密RS256安全性高适合分布式系统。
生成 JWT 必须设置 exp 过期时间验证时需捕获各类异常且避免载荷存储敏感信息。