RUEN
Package · jwt

API Reference

Complete reference for every public class and method in Flytachi JWT. All classes live under the Flytachi\Jwt namespace.

JWT

The façade for encoding and decoding. Two static methods, no state.

JWT::encode()

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

Builds the header from the key, signs header.payload, and returns the compact header.payload.signature string.

Parameter Type Description
$payload JwtPayload The claims to encode.
$privateKey PrivateKey Key material + algorithm (+ optional kid).

Returns string — the encoded JWT. Throws JWTException if the algorithm is unsupported, the key type doesn’t match the algorithm, or signing fails.

JWT::decode()

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

Splits the token, selects the verifying key, checks the signature, and validates the time claims.

Parameter Type Default Description
$token string — The compact JWT string.
$publicKeys array<string, PublicKey> — Map of [kid => PublicKey]. For HS* the first entry is used and kid is ignored.
$leeway int 0 Seconds of clock-skew tolerance applied to exp/nbf/iat.

Returns JwtPayload — the verified claims. Throws JWTException on wrong segment count, unsupported/mismatched algorithm, missing or unknown kid, signature failure, or a failed time claim. Any non-JWTException error thrown internally is wrapped in a JWTException.

Key selection differs by family

For HS* tokens decode() uses reset($publicKeys) — the first key — and ignores kid. For RS*/ES* it requires a kid in the header and looks it up in the map. See Verifying with JWKS.

JWK

Parser that converts JSON Web Keys into PublicKey objects. Static methods only.

JWK::parseKeySet()

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

Parses a full JWKS document into a [kid => PublicKey] map.

Parameter Type Description
$jwksData array The decoded JWKS array — must contain a keys array.

Returns array<string, PublicKey>. Entries without a kid, or that fail to parse, are silently skipped. Throws InvalidArgumentException only if the top-level keys array is missing.

JWK::parseKey()

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

Converts a single JWK object into a PublicKey.

kty Required fields Notes
RSA n, e Modulus and exponent (base64url).
EC crv, x, y Curve P-256, P-384, or P-521.
oct k Symmetric key value (base64url) for HS*.

Every JWK must also include alg. Throws InvalidArgumentException for a missing kty/alg/required field or an unsupported kty/curve, and RuntimeException if OpenSSL can’t build the key.

JwtPayload

Value object holding a token’s claims.

php
new JwtPayload(array $claims)
Method Signature Description
getClaim() getClaim(string $name, mixed $default = null): mixed Returns a claim, or $default if absent.
toArray() toArray(): array Returns all claims as an associative array.

JwtHeader

Value object for the token header. Built for you by encode() from the PrivateKey; rarely constructed directly.

php
new JwtHeader(string $algorithm, ?string $keyId = null, array $extra = [])
Property Type Description
$algorithm string Emitted as alg.
$type string Emitted as typ; defaults to 'JWT'.
$keyId ?string Emitted as kid when not null.
$extra array Extra header fields, merged into the output.

toArray() returns the header as ['alg' => …, 'typ' => 'JWT', 'kid' => …] plus any $extra.

PrivateKey

The signing key. Passed to encode().

php
new PrivateKey(
  OpenSSLAsymmetricKey|string $keyMaterial,
  string  $algorithm,
  ?string $keyId = null
)
Parameter Type Description
$keyMaterial OpenSSLAsymmetricKey | string A secret string for HS*; an OpenSSL private key object for RS*/ES*.
$algorithm string e.g. HS256, RS256, ES256.
$keyId ?string The kid written into the header — required for asymmetric tokens.

Getters: getAlgorithm(): string, getKeyMaterial(): OpenSSLAsymmetricKey|string, getKeyId(): ?string.

PublicKey

The verifying key. Passed to decode() (in the $publicKeys map).

php
new PublicKey(
  OpenSSLAsymmetricKey|string $keyMaterial,
  string $algorithm = 'HS256'
)
Parameter Type Default Description
$keyMaterial OpenSSLAsymmetricKey | string — A secret string for HS*; an OpenSSL public key object for RS*/ES*.
$algorithm string 'HS256' Must match the token’s alg or decode() throws.

Getters: getAlgorithm(): string, getKeyMaterial(): OpenSSLAsymmetricKey|string.

JWTException

Extends \DomainException. The single exception type thrown by JWT::encode() and JWT::decode() — one catch (JWTException $e) covers every token failure. (The JWK parser throws standard InvalidArgumentException/RuntimeException instead.)