RUEN
Пакет · jwt

Справочник API

Полный справочник по каждому публичному классу и методу Flytachi JWT. Все классы находятся в пространстве имён Flytachi\Jwt.

JWT

Фасад для кодирования и декодирования. Два статических метода, без состояния.

JWT::encode()

php
JWT::encode(JwtPayload $payload, PrivateKey $privateKey): string

Строит заголовок из ключа, подписывает header.payload и возвращает компактную строку header.payload.signature.

Параметр Тип Описание
$payload JwtPayload claims (утверждения) для кодирования.
$privateKey PrivateKey Ключевой материал + алгоритм (+ опциональный kid).

Возвращает string — закодированный JWT. Выбрасывает JWTException, если алгоритм неподдерживаемый, тип ключа не соответствует алгоритму или подпись не удалась.

JWT::decode()

php
JWT::decode(string $token, array $publicKeys, int $leeway = 0): JwtPayload

Разбивает токен, выбирает ключ для проверки, проверяет подпись и валидирует временные claims.

Параметр Тип По умолчанию Описание
$token string — Компактная строка JWT.
$publicKeys array<string, PublicKey> — Карта [kid => PublicKey]. Для HS* используется первый элемент, а kid игнорируется.
$leeway int 0 Секунды допуска на рассинхронизацию часов, применяемые к exp/nbf/iat.

Возвращает JwtPayload — проверенные claims. Выбрасывает JWTException при неверном числе сегментов, неподдерживаемом/несоответствующем алгоритме, отсутствующем или неизвестном kid, ошибке подписи или проваленной проверке временного claim. Любая не-JWTException ошибка, выброшенная внутри, оборачивается в JWTException.

Выбор ключа различается по семейству

Для токенов HS* decode() использует reset($publicKeys) — первый ключ — и игнорирует kid. Для RS*/ES* требуется kid в заголовке, и он ищется в карте. См. Проверка с помощью JWKS.

JWK

Парсер, преобразующий JSON Web Keys в объекты PublicKey. Только статические методы.

JWK::parseKeySet()

php
JWK::parseKeySet(array $jwksData): array

Разбирает полный документ JWKS в карту [kid => PublicKey].

Параметр Тип Описание
$jwksData array Декодированный массив JWKS — должен содержать массив keys.

Возвращает array<string, PublicKey>. Записи без kid или те, что не удалось разобрать, молча пропускаются. Выбрасывает InvalidArgumentException только если отсутствует массив keys верхнего уровня.

JWK::parseKey()

php
JWK::parseKey(array $jwkData): PublicKey

Преобразует один объект JWK в PublicKey.

kty Обязательные поля Примечания
RSA n, e Модуль и экспонента (base64url).
EC crv, x, y Кривая P-256, P-384 или P-521.
oct k Значение симметричного ключа (base64url) для HS*.

Каждый JWK также должен включать alg. Выбрасывает InvalidArgumentException при отсутствующем kty/alg/обязательном поле или неподдерживаемом kty/кривой, и RuntimeException, если OpenSSL не может построить ключ.

JwtPayload

Объект-значение, содержащий claims токена.

php
new JwtPayload(array $claims)
Метод Сигнатура Описание
getClaim() getClaim(string $name, mixed $default = null): mixed Возвращает claim или $default, если он отсутствует.
toArray() toArray(): array Возвращает все claims в виде ассоциативного массива.

JwtHeader

Объект-значение для заголовка токена. Строится за вас методом encode() из PrivateKey; редко создаётся напрямую.

php
new JwtHeader(string $algorithm, ?string $keyId = null, array $extra = [])
Свойство Тип Описание
$algorithm string Выводится как alg.
$type string Выводится как typ; по умолчанию 'JWT'.
$keyId ?string Выводится как kid, когда не null.
$extra array Дополнительные поля заголовка, объединяемые с выводом.

toArray() возвращает заголовок как ['alg' => …, 'typ' => 'JWT', 'kid' => …] плюс любые $extra.

PrivateKey

Ключ для подписи. Передаётся в encode().

php
new PrivateKey(
  OpenSSLAsymmetricKey|string $keyMaterial,
  string  $algorithm,
  ?string $keyId = null
)
Параметр Тип Описание
$keyMaterial OpenSSLAsymmetricKey | string Секретная строка для HS*; объект приватного ключа OpenSSL для RS*/ES*.
$algorithm string например, HS256, RS256, ES256.
$keyId ?string kid, записываемый в заголовок — обязателен для асимметричных токенов.

Геттеры: getAlgorithm(): string, getKeyMaterial(): OpenSSLAsymmetricKey|string, getKeyId(): ?string.

PublicKey

Ключ для проверки. Передаётся в decode() (в карте $publicKeys).

php
new PublicKey(
  OpenSSLAsymmetricKey|string $keyMaterial,
  string $algorithm = 'HS256'
)
Параметр Тип По умолчанию Описание
$keyMaterial OpenSSLAsymmetricKey | string — Секретная строка для HS*; объект публичного ключа OpenSSL для RS*/ES*.
$algorithm string 'HS256' Должен соответствовать alg токена, иначе decode() выбрасывает исключение.

Геттеры: getAlgorithm(): string, getKeyMaterial(): OpenSSLAsymmetricKey|string.

JWTException

Наследует \DomainException. Единственный тип исключения, выбрасываемый JWT::encode() и JWT::decode() — один catch (JWTException $e) покрывает любую ошибку токена. (Парсер JWK вместо этого выбрасывает стандартные InvalidArgumentException/RuntimeException.)

Связанное