Firebase PHP JWT

https://github.com/googleapis/php-jwt
Admin
A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519 with...
Tokens:42,665
Snippets:254
Trust Score:9.7
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install paragonie/sodium_compat (optional)

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Optionally install the paragonie/sodium_compat package if your PHP environment does not have libsodium installed.

```bash
composer require paragonie/sodium_compat
```

--------------------------------

### Install firebase/php-jwt via Composer

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Use Composer to install the PHP-JWT library. This is the primary installation command.

```bash
composer require firebase/php-jwt
```

--------------------------------

### CachedKeySet::offsetGet() usage example

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/cachedkeyset.md

Example usage of offsetGet() to retrieve a key by its kid. On cache miss, the JWKS is refreshed from the configured URI.

```php
$key = $keySet['kid1']; // refreshes JWKS from the URI on cache miss
```

--------------------------------

### Run PHPUnit tests

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Commands to install dependencies and run the test suite using PHPUnit. The output shows a successful run with 5 tests and 5 assertions.

```bash
$ composer update
$ vendor/bin/phpunit -c phpunit.xml.dist
PHPUnit 3.7.10 by Sebastian Bergmann.
.....
Time: 0 seconds, Memory: 2.50Mb
OK (5 tests, 5 assertions)
```

--------------------------------

### Key::getAlgorithm

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

Instance method to get the key's algorithm.

```APIDOC
## Key::getAlgorithm

### Description
Returns the algorithm associated with this key.

### Method
Instance method

### Signature
`Key::getAlgorithm(): string`

### Return Value
- **string** - The algorithm.

### Example
```php
$alg = $key->getAlgorithm();
```
```

--------------------------------

### JWT::constantTimeEquals() usage example

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwt.md

Example showing how to use constantTimeEquals to verify an HMAC. The method returns true when the two strings are equal, allowing authenticated actions.

```php
if (JWT::constantTimeEquals($expectedHmac, $providedHmac)) {
    // authenticated
}
```

--------------------------------

### Key::getKeyMaterial

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

Instance method to get the key material.

```APIDOC
## Key::getKeyMaterial

### Description
Returns the key material.

### Method
Instance method

### Signature
`Key::getKeyMaterial(): string`

### Return Value
- **string** - The key material.

### Example
```php
$material = $key->getKeyMaterial();
```
```

--------------------------------

### Parse RSA and oct JWKs with JWK::parseKey()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwk.md

Examples of parsing an RSA JWK and an oct symmetric JWK. The oct JWK uses the default algorithm 'HS256'.

```php
use Firebase\JWT\JWK;

// RSA JWK: { "kty": "RSA", "n": "...", "e": "AQAB", "alg": "RS256" }
$key = JWK::parseKey($rsaJwk);

// oct symmetric JWK (alg taken from $defaultAlg)
$key = JWK::parseKey(['kty' => 'oct', 'k' => 'base64url-secret'], 'HS256');
```

--------------------------------

### Install phpseclib for PS256 support

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

PS256 (RSASSA-PSS) is not supported by PHP's OpenSSL extension by default. Install the phpseclib library version ^3.0 as a soft dependency to enable PS256 support.

```bash
composer install phpseclib/phpseclib:^3.0
```

--------------------------------

### ExpiredException

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/exceptions.md

Documentation for the ExpiredException class, including its methods and usage example.

```APIDOC
## ExpiredException

### Description
Exception thrown by `JWT::decode()` when a token has expired. It extends `\UnexpectedValueException` and implements `JWTExceptionWithPayloadInterface`, providing access to the expired payload and the timestamp used for the expiry check.

### Methods

#### setPayload(object $payload): void
- **Parameters**: `$payload` (object) - The expired payload.
- **Returns**: `void`

#### getPayload(): object
- **Returns**: `object` - The expired payload (including `exp`).

#### setTimestamp(int $timestamp): void
- **Parameters**: `$timestamp` (int) - The reference timestamp used in the expiry check.
- **Returns**: `void`

#### getTimestamp(): ?int
- **Returns**: `?int` - The reference timestamp used in the expiry check, or `null` if not set.

### Usage Example
```php
use Firebase\JWT\JWT;
use Firebase\JWT\ExpiredException;
use \DateTime as DT;

try {
    JWT::decode($jwt, $key);
} catch (ExpiredException $e) {
    $expiredAt = $e->getPayload()->exp;
    $checkedAt  = $e->getTimestamp();
    // trigger a re-auth flow
}
```
```

--------------------------------

### Encode and decode JWT with PS256 algorithm

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Demonstrates encoding and decoding a JWT using the PS256 algorithm. Requires phpseclib/phpseclib to be installed. The private and public keys are placeholders.

```php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$privateRsKey = '-----BEGIN RSA PRIVATE KEY----- ...';
$publicKey = '-----BEGIN PUBLIC KEY----- ...';

$payload = [
    'iss' => 'example.org',
    'aud' => 'example.com',
    'iat' => 1356999524,
    'nbf' => 1357000000
];

/**
* PS256 support requires phpseclib/phpseclib
*/
$jwt = JWT::encode($payload, $privateRsKey, 'PS256', 'keyid');
echo "Encode:\n" . print_r($jwt, true) . "\n";

$decoded = JWT::decode($jwt, new Key($publicKey, 'PS256'));
echo "Decode:\n" . print_r((array) $decoded, true) . "\n";
```

--------------------------------

### GET $jwksUri (CachedKeySet)

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/endpoints.md

Performs an outbound GET request to fetch a remote JWKS document. Triggered lazily on cache miss for a key ID, subject to rate limiting.

```APIDOC
## GET $jwksUri

### Description
Performs an outbound GET request to fetch a remote JWKS document. Triggered lazily by the first `offsetGet()` / `offsetExists()` when the requested `kid` is not found in cache and the rate limit has not been exceeded.

### Method
GET

### Endpoint
`$jwksUri` (constructor parameter, any HTTP(S) URI)

### Parameters
#### Path Parameters
- **$jwksUri** (string) - Required - The URI of the JWKS document to fetch.

#### Query Parameters
None

#### Request Body
None

### Request Example
No request body.

### Response
#### Success Response (200)
- **keys** (array) - Required - Array of JWK objects; must be non-empty.
- **keys[].kid** (string) - Optional - Key ID; when absent the array index is used.
- **keys[].alg** (string) - Optional - Algorithm; when absent, the constructor `$defaultAlg` is used.
- **keys[].kty** (string) - Required for a key to be usable - One of `RSA`, `EC`, `OKP`, `oct`.
- **keys[].n**, **keys[].e** (string, base64url) - Required for RSA - RSA modulus / exponent.
- **keys[].crv**, **keys[].x**, **keys[].y** (string, base64url) - Required for EC - Curve (`P-256`, `secp256k1`, `P-384`), coordinates.
- **keys[].x**, **keys[].crv** (`Ed25519`) (string, base64url) - Required for OKP - Ed25519 public key.
- **keys[].k** (string, base64url) - Required for oct - Symmetric key bytes.

#### Response Example
```json
{
  "keys": [
    { "kid": "key-id-1", "kty": "RSA", "n": "<base64url>", "e": "<base64url>", "alg": "RS256" },
    { "kid": "key-id-2", "kty": "EC", "crv": "P-256", "x": "<base64url>", "y": "<base64url>" },
    { "kid": "key-id-3", "kty": "oct", "k": "<base64url>" }
  ]
}
```

### Status Codes
| Status | Handling |
|--------|----------|
| 200 | Body parsed and merged into the in-memory key set; cached under the derived cache key with `$expiresAfter` TTL when set. |
| any other | `UnexpectedValueException` thrown with message `'HTTP Error: <status> <reason> for URI "<jwksUri>"'` and the HTTP status as the exception code. |

### Notes
- No headers are added by the library; the request is created via `RequestFactoryInterface::createRequest('GET', $jwksUri)` and sent as-is.
- No authentication is attached; authenticate at the transport level if the endpoint requires it.
- Rate limiting: When `$rateLimit = true`, at most `maxCallsPerMinute` (10) fetches per minute per cache-pool; enforced via the `'jwksratelimit' + uri` cache key.
- Parsed key errors per member propagate from `JWK::parseKey()`; keys with known-but-unsupported curves are skipped silently.

### Resulting behavior on `kid` lookup
- Cache hit → key set used directly, no request.
- Cache miss, request succeeds, `kid` present → key parsed and returned; key set saved to cache.
- Cache miss, request succeeds, `kid` absent → lookup returns `false` (`offsetExists`) / throws `OutOfBoundsException('Key ID not found')` (`offsetGet`), and the fetched key set is cached for future `kid`s.
- Rate limit exceeded → lookups fail as "not found" without a network request.
```

--------------------------------

### Catch exceptions from JWK::parseKeySet()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwk.md

Example of error handling when calling parseKeySet(). Catches InvalidArgumentException for empty key sets, UnexpectedValueException for malformed sets or unsupported algorithms, and DomainException for OpenSSL failures.

```php
use Firebase\JWT\JWK;

try {
    $keys = JWK::parseKeySet($jwks, 'RS256');
} catch (InvalidArgumentException $e) {
    // JWK Set contained no keys
} catch (UnexpectedValueException $e) {
    // Malformed set: missing "keys" member, or no supported algorithms
} catch (DomainException $e) {
    // OpenSSL could not build the public key
}
```

--------------------------------

### Create CachedKeySet and decode JWT

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/cachedkeyset.md

Instantiate CachedKeySet with a JWKS URI and PSR-18/17/6 implementations, then pass it directly to JWT::decode() as the keyOrKeyArray. The example uses Guzzle for HTTP and Phpfastcache for caching. With rateLimit enabled, at most 10 JWKS fetches per minute are allowed; exceeding the limit makes keys appear not found without a network call.

```php
use Firebase\JWT\CachedKeySet;
use Firebase\JWT\JWT;

$keySet = new CachedKeySet(
    'https://www.gstatic.com/iap/verify/public_key-jwk',
    new GuzzleHttp\Client(),                    // PSR-18
    new GuzzleHttp\Psr7\HttpFactory(),          // PSR-17
    Phpfastcache\CacheManager::getInstance('files'), // PSR-6
    null, // expiresAfter: null = no expiry
    true, // rateLimit: max 10 fetches/minute
    'RS256' // defaultAlg for keys without alg
);

$decoded = JWT::decode($jwt, $keySet); // $keySet is used directly as keyOrKeyArray
```

--------------------------------

### BeforeValidException::getPayload

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

Instance method to get the payload from the exception.

```APIDOC
## BeforeValidException::getPayload

### Description
Returns the payload associated with the exception.

### Method
Instance method

### Signature
`BeforeValidException::getPayload(): object`

### Return Value
- **object** - The payload object.

### Example
```php
$payload = $e->getPayload();
```
```

--------------------------------

### Decode JWT using JWK::parseKeySet()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwk.md

Example of decoding a JWT using a JWK Set fetched from a URI. The JWK Set is parsed with a default algorithm 'RS256' and passed to JWT::decode().

```php
use Firebase\JWT\JWK;
use Firebase\JWT\JWT;

// e.g. the JSON response of https://www.gstatic.com/iap/verify/public_key-jwk
$jwks = json_decode(file_get_contents($jwksUri), true);

$decoded = JWT::decode($jwt, JWK::parseKeySet($jwks, 'RS256'));
```

--------------------------------

### JWT::sign() RS256 example

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwt.md

Signs the string 'header.payload' with an RSA private key in PEM format using RS256. Returns the raw binary signature.

```php
$sig = JWT::sign('header.payload', $privateKeyPem, 'RS256');
```

--------------------------------

### Encode and decode JWTs with multiple keys (RS256 and EdDSA)

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Shows how to encode the same payload with two different keys and algorithms (RS256 and EdDSA), each identified by a key ID ('kid1', 'kid2'), then decode both tokens using an array of Key objects. The keys are placeholders from a previous example.

```php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

// Example RSA keys from previous example
// $privateRsKey = '...';
// $publicRsKey = '...';

// Example EdDSA keys from previous example
// $privateEcKey = '...';
// $publicEcKey = '...';

$payload = [
    'iss' => 'example.org',
    'aud' => 'example.com',
    'iat' => 1356999524,
    'nbf' => 1357000000
];

$jwt1 = JWT::encode($payload, $privateRsKey, 'RS256', 'kid1');
$jwt2 = JWT::encode($payload, $privateEcKey, 'EdDSA', 'kid2');
echo "Encode 1:\n" . print_r($jwt1, true) . "\n";
echo "Encode 2:\n" . print_r($jwt2, true) . "\n";

$keys = [
    'kid1' => new Key($publicRsKey, 'RS256'),
    'kid2' => new Key($publicEcKey, 'EdDSA'),
];

$decoded1 = JWT::decode($jwt1, $keys);
$decoded2 = JWT::decode($jwt2, $keys);

echo "Decode 1:\n" . print_r((array) $decoded1, true) . "\n";
echo "Decode 2:\n" . print_r((array) $decoded2, true) . "\n";
```

--------------------------------

### Encode and decode JWT with RS256 using OpenSSL keys

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Demonstrates encoding a JWT with a private key using RS256 and decoding it with the corresponding public key. The decoded result is an object, not an associative array; cast it to an array if needed. The example includes full RSA private and public keys.

```php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$privateKey = <<<EOD
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAuzWHNM5f+amCjQztc5QTfJfzCC5J4nuW+L/aOxZ4f8J3Frew
M2c/dufrnmedsApb0By7WhaHlcqCh/ScAPyJhzkPYLae7bTVro3hok0zDITR8F6S
JGL42JAEUk+ILkPI+DONM0+3vzk6Kvfe548tu4czCuqU8BGVOlnp6IqBHhAswNMM
78pos/2z0CjPM4tbeXqSTTbNkXRboxjU29vSopcT51koWOgiTf3C7nJUoMWZHZI5
HqnIhPAG9yv8HAgNk6CMk2CadVHDo4IxjxTzTTqo1SCSH2pooJl9O8at6kkRYsrZ
WwsKlOFE2LUce7ObnXsYihStBUDoeBQlGG/BwQIDAQABAoIBAFtGaOqNKGwggn9k
6yzr6GhZ6Wt2rh1Xpq8XUz514UBhPxD7dFRLpbzCrLVpzY80LbmVGJ9+1pJozyWc
VKeCeUdNwbqkr240Oe7GTFmGjDoxU+5/HX/SJYPpC8JZ9oqgEA87iz+WQX9hVoP2
oF6EB4ckDvXmk8FMwVZW2l2/kd5mrEVbDaXKxhvUDf52iVD+sGIlTif7mBgR99/b
c3qiCnxCMmfYUnT2eh7Vv2LhCR/G9S6C3R4lA71rEyiU3KgsGfg0d82/XWXbegJW
h3QbWNtQLxTuIvLq5aAryV3PfaHlPgdgK0ft6ocU2de2FagFka3nfVEyC7IUsNTK
bq6nhAECgYEA7d/0DPOIaItl/8BWKyCuAHMss47j0wlGbBSHdJIiS55akMvnAG0M
39y22Qqfzh1at9kBFeYeFIIU82ZLF3xOcE3z6pJZ4Dyvx4BYdXH77odo9uVK9s1l
3T3BlMcqd1hvZLMS7dviyH79jZo4CXSHiKzc7pQ2YfK5eKxKqONeXuECgYEAyXlG
vonaus/YTb1IBei9HwaccnQ/1HRn6MvfDjb7JJDIBhNClGPt6xRlzBbSZ73c2QEC
6Fu9h36K/HZ2qcLd2bXiNyhIV7b6tVKk+0Psoj0dL9EbhsD1OsmE1nTPyAc9XZbb
OPYxy+dpBCUA8/1U9+uiFoCa7mIbWcSQ+39gHuECgYAz82pQfct30aH4JiBrkNqP
nJfRq05UY70uk5k1u0ikLTRoVS/hJu/d4E1Kv4hBMqYCavFSwAwnvHUo51lVCr/y
xQOVYlsgnwBg2MX4+GjmIkqpSVCC8D7j/73MaWb746OIYZervQ8dbKahi2HbpsiG
8AHcVSA/agxZr38qvWV54QKBgCD5TlDE8x18AuTGQ9FjxAAd7uD0kbXNz2vUYg9L
hFL5tyL3aAAtUrUUw4xhd9IuysRhW/53dU+FsG2dXdJu6CxHjlyEpUJl2iZu/j15
YnMzGWHIEX8+eWRDsw/+Ujtko/B7TinGcWPz3cYl4EAOiCeDUyXnqnO1btCEUU44
DJ1BAoGBAJuPD27ErTSVtId90+M4zFPNibFP50KprVdc8CR37BE7r8vuGgNYXmnI
RLnGP9p3pVgFCktORuYS2J/6t84I3+A17nEoB4xvhTLeAinAW/uTQOUmNicOP4Ek
2MsLL2kHgL8bLTmvXV4FX+PXphrDKg1XxzOYn0otuoqdAQrkK4og
-----END RSA PRIVATE KEY-----
EOD;

$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuzWHNM5f+amCjQztc5QT
fJfzCC5J4nuW+L/aOxZ4f8J3FrewM2c/dufrnmedsApb0By7WhaHlcqCh/ScAPyJ
hzkPYLae7bTVro3hok0zDITR8F6SJGL42JAEUk+ILkPI+DONM0+3vzk6Kvfe548t
u4czCuqU8BGVOlnp6IqBHhAswNMM78pos/2z0CjPM4tbeXqSTTbNkXRboxjU29vS
opcT51koWOgiTf3C7nJUoMWZHZI5HqnIhPAG9yv8HAgNk6CMk2CadVHDo4IxjxTz
TTqo1SCSH2pooJl9O8at6kkRYsrZWwsKlOFE2LUce7ObnXsYihStBUDoeBQlGG/B
wQIDAQAB
-----END PUBLIC KEY-----
EOD;

$payload = [
    'iss' => 'example.org',
    'aud' => 'example.com',
    'iat' => 1356999524,
    'nbf' => 1357000000
];

$jwt = JWT::encode($payload, $privateKey, 'RS256');
echo "Encode:\n" . print_r($jwt, true) . "\n";

$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));

/*
 NOTE: This will now be an object instead of an associative array. To get
 an associative array, you will need to cast it as such:
*/

$decoded_array = (array) $decoded;
echo "Decode:\n" . print_r($decoded_array, true) . "\n";
```

--------------------------------

### Simplify exception handling with UnexpectedValueException

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Since all exceptions in the Firebase\JWT namespace extend UnexpectedValueException, this simplified catch block catches LogicException for environmental setup or malformed JWT Keys, and UnexpectedValueException for JWT signature and claims errors.

```php
use Firebase\JWT\JWT;
use UnexpectedValueException;
try {
    $decoded = JWT::decode($jwt, $keys);
} catch (LogicException $e) {
    // errors having to do with environmental setup or malformed JWT Keys
} catch (UnexpectedValueException $e) {
    // errors having to do with JWT signature and claims
}
```

--------------------------------

### Encode and decode JWT headers manually

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Shows how to encode custom headers into a JWT and decode them without verification. WARNING: Decoding headers without verifying the JWT is not recommended and is vulnerable to attacks, as header values could be tampered with. The example uses json_decode and base64_decode on the header part.

```php
use Firebase\JWT\JWT;

$key = 'example_key_of_sufficient_length';
$payload = [
    'iss' => 'example.org',
    'aud' => 'example.com',
    'iat' => 1356999524,
    'nbf' => 1357000000
];

$headers = [
    'x-forwarded-for' => 'www.google.com'
];

// Encode headers in the JWT string
$jwt = JWT::encode($payload, $key, 'HS256', null, $headers);

// Decode headers from the JWT string WITHOUT validation
// **IMPORTANT**: This operation is vulnerable to attacks, as the JWT has not yet been verified.
// These headers could be any value sent by an attacker.
list($headersB64, $payloadB64, $sig) = explode('.', $jwt);
$decoded = json_decode(base64_decode($headersB64), true);

print_r($decoded);
```

--------------------------------

### Key::__construct()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Creates a new Key instance with the given key material and algorithm. Validates the key material type and non-empty values.

```APIDOC
## Key::__construct()

### Description
Creates a new Key instance bundling key material with the algorithm it is valid for. Throws TypeError or InvalidArgumentException on invalid input.

### Method
Constructor

### Signature
```php
public function __construct(
    #[\SensitiveParameter] private $keyMaterial,
    private string $algorithm
)
```

### Parameters
- **$keyMaterial** (string | OpenSSLAsymmetricKey | OpenSSLCertificate) - Required - The key material: a PEM/DER string, or an OpenSSL key handle. For HS* algorithms a plain secret string. For EdDSA a base64-encoded key string.
- **$algorithm** (string) - Required - One of the supported algorithm names: 'ES384', 'ES256', 'ES256K', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'PS256', 'EdDSA'.

### Throws
- **TypeError** - If key material is not a string, OpenSSLCertificate, or OpenSSLAsymmetricKey. Message: 'Key material must be a string, OpenSSLCertificate, or OpenSSLAsymmetricKey'.
- **InvalidArgumentException** - If key material is empty. Message: 'Key material must not be empty'.
- **InvalidArgumentException** - If algorithm is empty. Message: 'Algorithm must not be empty'.

### Example
```php
use Firebase\JWT\Key;

$key = new Key('example_key_of_sufficient_length', 'HS256');

// With an OpenSSL private key handle (e.g. passphrase-protected PEM)
$privateKey = openssl_pkey_get_private(
    file_get_contents('/path/to/key-with-passphrase.pem'),
    $passphrase
);
$keyMaterial = openssl_pkey_get_details($privateKey)['key'];
$publicKey = new Key($keyMaterial, 'RS256');
```
```

--------------------------------

### Instantiate CachedKeySet with constructor options

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/configuration.md

Constructs a CachedKeySet with a JWKS URI, PSR-18 HTTP client, PSR-17 request factory, PSR-6 cache pool, a 1-hour cache TTL, rate limiting enabled, and a default algorithm of RS256. The rate limit caps fetches at 10 per minute.

```php
new CachedKeySet(
    'https://issuer.example/.well-known/jwks.json',
    $httpClient,          // PSR-18
    $httpFactory,         // PSR-17
    $cachePool,           // PSR-6
    3600,                 // expiresAfter: cache JWKS for 1h
    true,                 // rateLimit: max 10 fetches/minute
    'RS256'               // defaultAlg
);
```

--------------------------------

### Create Key instances for HS256 and RS256

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Create a Key instance with a plain secret for HS256, and with an OpenSSL private key handle for RS256. The private key handle is obtained from a passphrase-protected PEM file, then the key material is extracted via openssl_pkey_get_details().

```php
use Firebase\JWT\Key;

$key = new Key('example_key_of_sufficient_length', 'HS256');

// With an OpenSSL private key handle (e.g. passphrase-protected PEM)
$privateKey = openssl_pkey_get_private(
    file_get_contents('/path/to/key-with-passphrase.pem'),
    $passphrase
);
$keyMaterial = openssl_pkey_get_details($privateKey)['key'];
$publicKey = new Key($keyMaterial, 'RS256');
```

--------------------------------

### ExpiredException::getTimestamp

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

Instance method to get the timestamp from the exception.

```APIDOC
## ExpiredException::getTimestamp

### Description
Returns the timestamp associated with the exception.

### Method
Instance method

### Signature
`ExpiredException::getTimestamp(): int`

### Return Value
- **int** - The timestamp.

### Example
```php
$timestamp = $e->getTimestamp();
```
```

--------------------------------

### Key::getKeyMaterial()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Returns the raw key material stored at construction time. Passed to internal verify()/sign() routines.

```APIDOC
## Key::getKeyMaterial()

### Description
Returns the raw key material stored at construction time. Passed to the internal verify() / sign() routines (e.g. to openssl_pkey_get_public() / openssl_pkey_get_private()).

### Method
Getter

### Signature
```php
public function getKeyMaterial()
```

### Return Value
- **string | OpenSSLAsymmetricKey | OpenSSLCertificate** - The raw key material.

### Example
```php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

// Multiple keys keyed by kid — the value type is always Key
$keys = [
    'kid1' => new Key($publicRsKey, 'RS256'),
    'kid2' => new Key($publicEdKey, 'EdDSA'),
];

$decoded = JWT::decode($jwt, $keys);
```
```

--------------------------------

### ExpiredException::getPayload

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

Instance method to get the payload from the exception.

```APIDOC
## ExpiredException::getPayload

### Description
Returns the payload associated with the exception.

### Method
Instance method

### Signature
`ExpiredException::getPayload(): object`

### Return Value
- **object** - The payload object.

### Example
```php
$payload = $e->getPayload();
```
```

--------------------------------

### Key::__construct

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

Constructor for the Key class.

```APIDOC
## Key::__construct

### Description
Creates a new Key object with the given key material and algorithm.

### Method
Constructor

### Signature
`Key::__construct(string $keyMaterial, string $algorithm)`

### Parameters
- **$keyMaterial** (string) - Required - The key material (e.g., secret or public key).
- **$algorithm** (string) - Required - The algorithm associated with this key.

### Example
```php
$key = new Key($secret, 'HS256');
```
```

--------------------------------

### Key::getAlgorithm()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Returns the algorithm this key was constructed with. Used by JWT::decode() to compare against the token header's alg.

```APIDOC
## Key::getAlgorithm()

### Description
Returns the algorithm this key was constructed with (e.g. 'HS256'). JWT::decode() compares this against the token header's alg with constantTimeEquals() and throws UnexpectedValueException('Incorrect key for this algorithm') on mismatch.

### Method
Getter

### Signature
```php
public function getAlgorithm(): string
```

### Return Value
- **string** - The algorithm name (e.g. 'HS256').
```

--------------------------------

### JWK::parseKeySet()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/errors.md

Documentation for the `JWK::parseKeySet()` method, including its exceptions and conditions.

```APIDOC
## `JWK::parseKeySet()` — `src/JWK.php:64`

### Description
Parses a JWK Set (JSON Web Key Set) into an array of public keys. Throws exceptions for invalid or empty key sets.

### Method
`parseKeySet`

### Parameters
- `$jwks` (array) - Required - The JWK Set array.
- `$defaultAlg` (string|null) - Optional - Default algorithm to use if `alg` is missing.

### Exceptions
| Error | Message | Condition |
|-------|---------|-----------|
| `UnexpectedValueException` | `'"keys" member must exist in the JWK Set'` | `$jwks['keys']` unset. |
| `InvalidArgumentException` | `'JWK Set did not contain any keys'` | `$jwks['keys']` empty. |
| `UnexpectedValueException` | `'No supported algorithms found in JWK Set'` | Zero keys parsed (all skipped/`null`). |
| `DomainException` | see `parseKey()` | Delegated from `parseKey()` for a member key. |
```

--------------------------------

### Key constructor signature

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Constructor signature for the Key class. Requires key material (string, OpenSSLAsymmetricKey, or OpenSSLCertificate) and an algorithm name. Throws TypeError for invalid key material type, InvalidArgumentException for empty key material or empty algorithm.

```php
public function __construct(
    #[\SensitiveParameter] private $keyMaterial,
    private string $algorithm
)
```

--------------------------------

### CachedKeySet::offsetGet

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/index.md

ArrayAccess method to get a Key by key ID.

```APIDOC
## CachedKeySet::offsetGet

### Description
Retrieves a Key by key ID from the cached key set.

### Method
Instance method (ArrayAccess)

### Signature
`CachedKeySet::offsetGet(mixed $keyId): Key`

### Parameters
- **$keyId** (mixed) - Required - The key ID.

### Return Value
- **Key** - The Key object.

### Example
```php
$key = $keySet['kid'];
```
```

--------------------------------

### JWK::parseKey()

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/errors.md

Documentation for the `JWK::parseKey()` method, including its exceptions and conditions.

```APIDOC
## `JWK::parseKey()` — `src/JWK.php:105`

### Description
Parses a single JWK into a public key. Throws exceptions for invalid or unsupported keys.

### Method
`parseKey`

### Parameters
- `$jwk` (array) - Required - The JWK array.
- `$defaultAlg` (string|null) - Optional - Default algorithm to use if `alg` is missing.

### Exceptions
| Error | Message | Condition |
|-------|---------|-----------|
| `InvalidArgumentException` | `'JWK must not be empty'` | `$jwk` empty. |
| `UnexpectedValueException` | `'JWK must contain a "kty" parameter'` | `kty` unset. |
| `UnexpectedValueException` | `'JWK must contain an "alg" parameter'` | `alg` unset and `$defaultAlg` null (RFC 7517 §4.4). |
| `UnexpectedValueException` | `'RSA private keys are not supported'` | RSA JWK has `d`. |
| `UnexpectedValueException` | `'RSA keys must contain values for both "n" and "e"'` | RSA JWK missing `n` or `e`. |
| `DomainException` | `'OpenSSL error: <openssl_error_string()>'` | `openssl_pkey_get_public($pem)` returns `false`. |
| `UnexpectedValueException` | `'Key data must be for a public key'` | EC or OKP JWK has `d`. |
| `UnexpectedValueException` | `'crv not set'` | EC/OKP JWK missing `crv`. |
| `DomainException` | `'Unrecognised EC curve'` | EC `crv` not in `EC_CURVES` and not in `KNOWN_UNSUPPORTED_EC_CURVES`. |
| `UnexpectedValueException` | `'x and y not set'` | EC JWK missing `x` or `y`. |
| `DomainException` | `'Unrecognised or unsupported OKP key subtype'` | OKP `crv` not `Ed25519`. |
| `UnexpectedValueException` | `'x not set'` | OKP JWK missing `x`. |
| `UnexpectedValueException` | `'k not set'` | `oct` JWK missing `k`. |

### Notes
Known unsupported curves (`P-521`, `Ed25519`, `Ed448`, `X25519`, `X448`) return `null` instead of throwing; unknown `kty` returns `null`.
```

--------------------------------

### Key::getAlgorithm() signature

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Method signature for getAlgorithm(). Returns the algorithm string (e.g. 'HS256'). JWT::decode() compares this against the token header's alg with constantTimeEquals() and throws UnexpectedValueException('Incorrect key for this algorithm') on mismatch.

```php
public function getAlgorithm(): string
```

--------------------------------

### JWT::encode() HS256 example

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwt.md

Encodes a JWT with HS256 using a raw string key of sufficient length. The payload includes iss, sub, and exp claims. Returns the signed JWT string.

```php
use Firebase\JWT\JWT;

$jwt = JWT::encode(
    ['iss' => 'example.org', 'sub' => 'user-1', 'exp' => time() + 3600],
    'example_key_of_sufficient_length',
    'HS256'
);
```

--------------------------------

### `JWT::$supported_algs` map

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/types.md

Closed set of supported algorithms and their backend implementation.

```APIDOC
## `JWT::$supported_algs` map

### Description
Closed set of supported algorithms and their backend implementation.

### Supported Algorithms

| Algorithm | Backend function | Algorithm parameter | Notes |
|-----------|------------------|---------------------|-------|
| `ES384` | `openssl` | `SHA384` | ECDSA P-384; DER↔raw signature conversion |
| `ES256` | `openssl` | `SHA256` | ECDSA P-256 |
| `ES256K` | `openssl` | `SHA256` | ECDSA secp256k1 |
| `HS256` | `hash_hmac` | `SHA256` | key ≥ 256 bits enforced |
| `HS384` | `hash_hmac` | `SHA384` | key ≥ 384 bits enforced |
| `HS512` | `hash_hmac` | `SHA512` | key ≥ 512 bits enforced |
| `RS256` | `openssl` | `SHA256` | RSA key ≥ 2048 bits enforced |
| `RS384` | `openssl` | `SHA384` | RSA key ≥ 2048 bits enforced |
| `RS512` | `openssl` | `SHA512` | RSA key ≥ 2048 bits enforced |
| `PS256` | `openssl` | `SHA256` | RSASSA-PSS; requires `phpseclib/phpseclib` |
| `EdDSA` | `sodium_crypto` | `EdDSA` | Ed25519; requires `ext-sodium` or `paragonie/sodium_compat` |

```

--------------------------------

### Decode JWT using JWK::parseKeySet

Source: https://github.com/googleapis/php-jwt/blob/main/README.md

Parses a JWKS array into an associative array of kid to Firebase\JWT\Key objects, which is passed as the second parameter to JWT::decode. The JWKS must have a 'keys' key, as in the response from the example endpoint.

```php
use Firebase\JWT\JWK;
use Firebase\JWT\JWT;

// Set of keys. The "keys" key is required. For example, the JSON response to
// this endpoint: https://www.gstatic.com/iap/verify/public_key-jwk
$jwks = ['keys' => []];

// JWK::parseKeySet($jwks) returns an associative array of **kid** to Firebase\JWT\Key
// objects. Pass this as the second parameter to JWT::decode.
$decoded = JWT::decode($jwt, JWK::parseKeySet($jwks));
print_r($decoded);
```

--------------------------------

### Import Firebase\JWT\JWK

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwk.md

Import the JWK class for use in PHP code.

```php
use Firebase\JWT\JWK;
```

--------------------------------

### JWT::encode() EdDSA example with kid and custom headers

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwt.md

Encodes a JWT with EdDSA using a base64-encoded secret key, a key ID, and a custom header. The key is derived from a sodium key pair. Returns the signed JWT string.

```php
use Firebase\JWT\JWT;

// With kid and custom headers; EdDSA key is base64-encoded secret key
$jwt = JWT::encode(
    ['iss' => 'example.org'],
    base64_encode(sodium_crypto_sign_secretkey($keyPair)),
    'EdDSA',
    'kid2',
    ['x-forwarded-for' => 'www.google.com'] // custom head
);
```

--------------------------------

### Key::getKeyMaterial() signature

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Method signature for getKeyMaterial(). Returns the raw key material (string, OpenSSLAsymmetricKey, or OpenSSLCertificate) stored at construction time. Passed to internal verify()/sign() routines.

```php
public function getKeyMaterial()
```

--------------------------------

### Class Firebase\JWT\Key

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/types.md

Documentation for the Firebase\JWT\Key class, including its constructor, methods, and usage contexts.

```APIDOC
## Class `Firebase\JWT\Key`

### Description
Represents a key used for JWT signing or verification, holding the key material and the algorithm it is valid for.

### Constructor
`__construct($keyMaterial, string $algorithm)`

#### Parameters
- **$keyMaterial** (`string` | `OpenSSLAsymmetricKey` | `OpenSSLCertificate`) - Required - Key material; must be non-empty and one of the listed types.
- **$algorithm** (`string`) - Required - Algorithm the key is valid for; must be non-empty.

### Methods

#### `getAlgorithm(): string`
Returns the algorithm associated with the key.

#### `getKeyMaterial()`
Returns the key material.

### Accepted By
- `JWT::decode()` (direct or as array/`ArrayAccess` value)
- `JWT::getKey()` (private)

### Returned By
- `JWK::parseKey()`
- `JWK::parseKeySet()` (values)
- `CachedKeySet::offsetGet()`
```

--------------------------------

### Import Firebase\JWT\Key

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/key.md

Import the Key class from the Firebase JWT library.

```php
use Firebase\JWT\Key;
```

--------------------------------

### JWKS response body schema

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/endpoints.md

Expected JSON response body for a successful GET request to the JWKS URI. The keys array must exist and be non-empty; otherwise exceptions are thrown. Each key object can include kid, alg, kty, and type-specific fields like n/e for RSA, crv/x/y for EC, x/crv for OKP, and k for oct.

```json
{
  "keys": [
    { "kid": "key-id-1", "kty": "RSA", "n": "<base64url>", "e": "<base64url>", "alg": "RS256" },
    { "kid": "key-id-2", "kty": "EC", "crv": "P-256", "x": "<base64url>", "y": "<base64url>" },
    { "kid": "key-id-3", "kty": "oct", "k": "<base64url>" }
  ]
}
```

--------------------------------

### Import Firebase\JWT\CachedKeySet

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/cachedkeyset.md

Import the CachedKeySet class before using it.

```php
use Firebase\JWT\CachedKeySet;
```

--------------------------------

### JWT::$supported_algs property

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/jwt.md

Maps algorithm names to backend function and algorithm parameter. Includes HS, RS, ES, PS, and EdDSA algorithms.

```php
public static $supported_algs = [
    'ES384' => ['openssl', 'SHA384'],
    'ES256' => ['openssl', 'SHA256'],
    'ES256K' => ['openssl', 'SHA256'],
    'HS256' => ['hash_hmac', 'SHA256'],
    'HS384' => ['hash_hmac', 'SHA384'],
    'HS512' => ['hash_hmac', 'SHA512'],
    'RS256' => ['openssl', 'SHA256'],
    'RS384' => ['openssl', 'SHA384'],
    'RS512' => ['openssl', 'SHA512'],
    'PS256' => ['openssl', 'SHA256'],
    'EdDSA' => ['sodium_crypto', 'EdDSA']
];
```

--------------------------------

### Catch BeforeValidException and recover payload

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/exceptions.md

Shows how to catch BeforeValidException and recover the token payload via getPayload(). This exception is thrown when the nbf or iat claim is in the future, indicating the token is not yet valid.

```php
use Firebase\JWT\JWT;
use Firebase\JWT\BeforeValidException;

try {
    JWT::decode($jwt, $key);
} catch (BeforeValidException $e) {
    $payload = $e->getPayload();   // recover the claims anyway
    $nbf = $payload->nbf;          // the not-before time
    // Client clock is ahead of the issuer, or the token is genuinely not yet valid
}

```

--------------------------------

### BeforeValidException class definition with payload methods

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/exceptions.md

Defines the BeforeValidException class, which extends \UnexpectedValueException and implements JWTExceptionWithPayloadInterface. It stores the token payload that triggered the exception and provides setPayload() and getPayload() methods.

```php
class BeforeValidException extends \UnexpectedValueException implements JWTExceptionWithPayloadInterface
{
    private object $payload;

    public function setPayload(object $payload): void
    {
        $this->payload = $payload;
    }

    public function getPayload(): object
    {
        return $this->payload;
    }
}

```

--------------------------------

### CachedKeySet::offsetSet() signature

Source: https://github.com/googleapis/php-jwt/blob/main/_autodocs/api-reference/cachedkeyset.md

Part of the read-only collection interface. Always throws LogicException('Method not implemented').

```php
public function offsetSet($offset, $value): void
```
Tokens:
Raw