JWT

https://github.com/lcobucci/jwt
Admin
A simple library to work with JSON Web Token and JSON Web Signature based on the RFC 7519.
Tokens:18,866
Snippets:129
Trust Score:9.3
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Implement Key interface

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Create a custom key object by implementing the Lcobucci\JWT\Signer\Key interface. The example shows the class declaration with a placeholder for the required methods.

```php
use Lcobucci\JWT\Signer\Key;

final class KeyWithSomeMagicalProperties implements Key
{
    // implement all methods
}
```

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

### Install lcobucci/jwt via Composer

Source: https://github.com/lcobucci/jwt/blob/6.0.x/README.md

Use this command to install the lcobucci/jwt package. It is available on Packagist and can be installed using Composer.

```shell
composer require lcobucci/jwt
```

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

### Implement Signer interface

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Create a custom signer by implementing the Lcobucci\JWT\Signer interface. The example shows the class declaration with a placeholder for the required methods.

```php
use Lcobucci\JWT\Signer;

final class SignerForAVeryCustomizedAlgorithm implements Signer
{
    // implement all methods
}
```

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

### Implement Parser interface

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Create a custom token parser by implementing the Lcobucci\JWT\Parser interface. The example shows the class declaration with a placeholder for the required methods.

```php
use Lcobucci\JWT\Parser;

final class MyCustomTokenParser implements Parser
{
    // implement all methods
}
```

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

### Use the new Token API for headers, claims, and string conversion

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows the new Token API for accessing headers and claims. Headers and claims are now DataSet objects, so use headers()->all(), headers()->has(), headers()->get(), and the corresponding claims() methods. No exception is thrown for missing headers/claims; the default argument is always used. Tokens must be explicitly cast to string via toString().

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

// we assume here that $token is a valid parsed/created token

-$token->getHeaders() 
+$token->headers()->all()
-$token->hasHeader('typ')
+$token->headers()->has('typ')
-$token->getHeader('typ')
+$token->headers()->get('typ')

-$token->getClaims() 
+$token->claims()->all()
-$token->hasClaim('iss')
+$token->claims()->has('iss')
-$token->getClaim('iss')
+$token->claims()->get('iss')

-echo (string) $token;
+echo $token->toString();
```

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

### Require lcobucci/clock explicitly

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Run this command to add lcobucci/clock as a production dependency, as it is no longer installed by default in v5.0.0.

```sh
composer require lcobucci/clock
```

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

### Retrieve token headers and claims with Lcobucci\JWT

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/issuing-tokens.md

Builds a minimal JWT and then retrieves its headers and claims using the token's headers() and claims() methods. Demonstrates accessing specific header and claim values and printing the token string. The comments show expected output for the get() calls.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Encoding\ChainedFormatter;
use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Token\Builder;

require 'vendor/autoload.php';

$tokenBuilder = Builder::new(new JoseEncoder(), ChainedFormatter::default());
$algorithm    = new Sha256();
$signingKey   = InMemory::plainText(random_bytes(32));

$token = $tokenBuilder
    ->issuedBy('http://example.com')
    ->withClaim('uid', 1)
    ->withHeader('foo', 'bar')
    ->getToken($algorithm, $signingKey);

$token->headers(); // Retrieves the token headers
$token->claims(); // Retrieves the token claims

echo $token->headers()->get('foo'), PHP_EOL; // will print "bar"
echo $token->claims()->get('iss'), PHP_EOL; // will print "http://example.com"
echo $token->claims()->get('uid'), PHP_EOL; // will print "1"

echo $token->toString(), PHP_EOL; // The string representation of the object is a JWT string
```

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

### Replace Ecdsa::create() with constructor

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows the diff for replacing the named constructor Ecdsa::create() with the constructor for ECDSA signers. The example uses Sha256 and shows the required changes.

```diff
<?php
declare(strict_types=1);

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$configuration = Configuration::forAsymmetricSigner(
-    Signer\Ecdsa\Sha256::create(),
+    new Signer\Ecdsa\Sha256(),
    InMemory::file(__DIR__ . '/my-private-key.pem'),
    InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
    // You may also override the JOSE encoder/decoder if needed
    // by providing extra arguments here
);
```

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

### Register custom Parser in Configuration

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Register an instance of the custom parser in the configuration object using the withParser method. The example assumes a container that provides the Configuration instance.

```php
use Lcobucci\JWT\Configuration;

$config = $container->get(Configuration::class);
assert($config instanceof Configuration);

$configuration = $configuration->withParser(new MyCustomTokenParser());
```

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

### Implement Validator interface

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Create a custom token validator by implementing the Lcobucci\JWT\Validator interface. The example shows the class declaration with a placeholder for the required methods.

```php
use Lcobucci\JWT\Validator;

final class MyCustomTokenValidator implements Validator
{
    // implement all methods
}
```

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

### Use arrow function with immutable Builder

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows the diff for using an arrow function with the immutable Builder API. This is an alternative to the previous example, using a concise arrow function that returns the chained builder.

```diff
$token = (new JwtFacade())->issue(
    new Sha256(),
    $key,
-    static function (
+    static fn (
        Builder $builder,
        DateTimeImmutable $now
-    ): Builder {
-        $builder->issuedBy('https://api.my-awesome-app.io');
-        $builder->permittedFor('https://client-app.io');
-        $builder->expiresAt($now->modify('+10 minutes'));
-
-         return $builder;
-     }
+    ): Builder => $builder->issuedBy('https://api.my-awesome-app.io')
+        ->permittedFor('https://client-app.io')
+        ->expiresAt($now->modify('+10 minutes'))
);
```

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

### Issue a JWT with a frozen clock for tests

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/quick-start.md

Uses the JwtFacade constructor's clock parameter to pass a FrozenClock, ensuring deterministic issued-at timestamps during tests. The example sets no custom claims and outputs the issued-at claim formatted as RFC3339.

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock; // If you prefer, other PSR-20 implementations may also be used
                                // (https://packagist.org/providers/psr/clock-implementation)
use Lcobucci\JWT\Builder;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Token\RegisteredClaims;

$clock = new FrozenClock(new DateTimeImmutable('2022-06-24 22:51:10'));
$key   = InMemory::base64Encoded(
    'hiG8DlOKvtih6AxlZn5XKImZ06yu8I3mkOzaJrEuW8yAv8Jnkw330uMt8AEqQ5LB'
);

$token = (new JwtFacade(null, $clock))->issue(
    new Sha256(),
    $key,
    static fn (
        Builder $builder,
        DateTimeImmutable $issuedAt
    ): Builder => $builder
);

echo $token->claims()->get(
    RegisteredClaims::ISSUED_AT
)->format(DateTimeImmutable::RFC3339); // 2022-06-24 22:51:10
```

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

### Register custom Validator in Configuration

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Register an instance of the custom validator in the configuration object using the withValidator method. The example assumes a container that provides the Configuration instance.

```php
use Lcobucci\JWT\Configuration;

$config = $container->get(Configuration::class);
assert($config instanceof Configuration);

$configuration = $configuration->withValidator(new MyCustomTokenValidator());
```

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

### Implement Lcobucci\JWT\Validation\Constraint interface

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Implements the Lcobucci\JWT\Validation\Constraint interface to create a custom validation constraint. The assert method must throw a ConstraintViolation when validation fails; this example checks that the token is an UnencryptedToken and that the 'sub' claim exists in a database.

```php
use Lcobucci\JWT\Token;
use Lcobucci\JWT\UnencryptedToken;
use Lcobucci\JWT\Validation\Constraint;
use Lcobucci\JWT\Validation\ConstraintViolation;

final class SubjectMustBeAValidUser implements Constraint
{
    public function assert(Token $token): void
    {
        if (! $token instanceof UnencryptedToken) {
            throw new ConstraintViolation('You should pass a plain token');
        }

        if (! $this->existsInDatabase($token->claims()->get('sub'))) {
            throw new ConstraintViolation('Token related to an unknown user');
        }
    }

    private function existsInDatabase(string $userId): bool
    {
        // ...
    }
}
```

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

### Parse and validate a JWT with JwtFacade#parse()

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/quick-start.md

Parses a JWT string using JwtFacade::parse() with signature and date validation constraints. Throws an exception if the token is invalid. The example uses a FrozenClock for deterministic validation; production code should use SystemClock.

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock; // If you prefer, other PSR-20 implementations may also be used
                                // (https://packagist.org/providers/psr/clock-implementation)
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Validation\Constraint;

use function var_dump;

$jwt = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTg2OTYwNTIsIm5iZiI6MT'
    . 'Y1ODY5NjA1MiwiZXhwIjoxNjU4Njk2NjUyLCJpc3MiOiJodHRwczovL2FwaS5teS1hd2Vzb'
    . '21lLWFwcC5pbyIsImF1ZCI6Imh0dHBzOi8vY2xpZW50LWFwcC5pbyJ9.yzxpjyq8lXqMgaN'
    . 'rMEOLUr7R0brvhwXx0gp56uWEIfc';

$key = InMemory::base64Encoded(
    'hiG8DlOKvtih6AxlZn5XKImZ06yu8I3mkOzaJrEuW8yAv8Jnkw330uMt8AEqQ5LB'
);

$token = (new JwtFacade())->parse(
    $jwt,
    new Constraint\SignedWith(new Sha256(), $key),
    new Constraint\StrictValidAt(
        new FrozenClock(new DateTimeImmutable('2022-07-24 20:55:10+00:00'))
    )
);

var_dump($token->claims()->all());
```

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

### Issue a JWT with JwtFacade#issue()

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/quick-start.md

Creates a signed JWT using the JwtFacade::issue() method. It uses the current time for date claims, with a default expiration of 5 minutes. The example sets custom claims (issuer, audience, expiration) and outputs the claims and token string.

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\JWT\Builder;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Signer\Key\InMemory;

use function var_dump;

$key = InMemory::base64Encoded(
    'hiG8DlOKvtih6AxlZn5XKImZ06yu8I3mkOzaJrEuW8yAv8Jnkw330uMt8AEqQ5LB'
);

$token = (new JwtFacade())->issue(
    new Sha256(),
    $key,
    static fn (
        Builder $builder,
        DateTimeImmutable $issuedAt
    ): Builder => $builder
        ->issuedBy('https://api.my-awesome-app.io')
        ->permittedFor('https://client-app.io')
        ->expiresAt($issuedAt->modify('+10 minutes'))
);

var_dump($token->claims()->all());
echo $token->toString();
```

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

### Validate token with Lcobucci\JWT\Validator::validate()

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/validating-tokens.md

Uses the Validator::validate() method to validate a token against constraints. It returns a boolean and stops at the first violation. The example shows two validations: the first fails and prints 'Invalid token (1)!', the second passes and does not print.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Token\Parser;
use Lcobucci\JWT\Validation\Constraint\RelatedTo;
use Lcobucci\JWT\Validation\Validator;

require 'vendor/autoload.php';

$parser = new Parser(new JoseEncoder());

$token = $parser->parse(
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
    . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
    . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
);

$validator = new Validator();

if (! $validator->validate($token, new RelatedTo('1234567891'))) {
    echo 'Invalid token (1)!', PHP_EOL; // will print this
}

if (! $validator->validate($token, new RelatedTo('1234567890'))) {
    echo 'Invalid token (2)!', PHP_EOL; // will not print this
}
```

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

### Validate token with Lcobucci\JWT\Validator::assert()

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/validating-tokens.md

Uses the Validator::assert() method to validate a token against constraints. It groups all violations and throws a RequiredConstraintsViolated exception if any constraint fails. The example shows two assertions: the first passes, the second fails, and the catch block dumps the violations.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Token\Parser;
use Lcobucci\JWT\Validation\Constraint\RelatedTo;
use Lcobucci\JWT\Validation\RequiredConstraintsViolated;
use Lcobucci\JWT\Validation\Validator;

require 'vendor/autoload.php';

$parser = new Parser(new JoseEncoder());

$token = $parser->parse(
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
    . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
    . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
);

$validator = new Validator();

try {
    $validator->assert($token, new RelatedTo('1234567891')); // doesn't throw an exception
    $validator->assert($token, new RelatedTo('1234567890'));
} catch (RequiredConstraintsViolated $e) {
    // list of constraints violation exceptions:
    var_dump($e->violations());
}
```

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

### Replace Token#verify() and Token#validate() with Validation API

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows how to replace the old Token#verify() and Token#validate() calls with the new Validation API. The diff updates the constructor to accept a Configuration object and uses the configuration's parser and validator with validation constraints. Requires constraints to be configured as described in the configuration documentation.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

use InvalidArgumentException;
+use Lcobucci\JWT\Configuration;
-use Lcobucci\JWT\Signer;
-use Lcobucci\JWT\Signer\Key;
-use Lcobucci\JWT\Parser;
-use Lcobucci\JWT\ValidationData;

final class AuthenticateJwt
{
-    private Parser $parser;
-    private Signer $signer;
-    private Key $key;
+    private Configuration $config;
    
-    public function __construct(Parser $parser, Signer $signer, Key $key)
+    public function __construct(Configuration $config)
    {
-        $this->parser = $parser;
-        $this->signer = $signer;
-        $this->key    = $key;
+        $this->config = $config;
    }
    
    public function authenticate(string $jwt): void
    {
-        $token = $this->parser->parse($jwt);
+        $token = $this->config->parser()->parse($jwt);
        
-        if (! $token->validate(new ValidationData()) || $token->verify($this->signer, $this->key)) {
+        if (! $this->config->validator()->validate($token, ...$this->config->validationConstraints())) {
            throw new InvalidArgumentException('Invalid token provided');
        }
    }
}
```

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

### Use new Key objects with InMemory named constructors

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Migrate from the old Lcobucci\JWT\Signer\Key class to the new InMemory class. Use the appropriate named constructor: plainText for plain text keys, base64Encoded for base64-encoded strings, and file for file contents. The file constructor expects a path without the 'file://' prefix.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

-use Lcobucci\JWT\Signer\Key;
+use Lcobucci\JWT\Signer\Key\InMemory;
-
-use function base64_decode;

 // Key from plain text
-$key = new Key('a-very-secure-key');
+$key = InMemory::plainText('a-very-secure-key');

 // Key from base64 encoded string
-$key = new Key(base64_decode('YS12ZXJ5LXNlY3VyZS1rZXk=', true));
+$key = InMemory::base64Encoded('YS12ZXJ5LXNlY3VyZS1rZXk=');

 // Key from file contents
-$key = new Key('file:///var/secrets/my-private-key.pem');
+$key = InMemory::file('/var/secrets/my-private-key.pem');
```

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

### Configure asymmetric signer with RSA SHA-256

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Configures the library for asymmetric algorithms (e.g., RSA SHA-256). Uses a private key for signing and a public key for verification. The private key must remain secret, while the public key can be distributed.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$configuration = Configuration::forAsymmetricSigner(
    new Signer\Rsa\Sha256(),
    InMemory::file(__DIR__ . '/my-private-key.pem'),
    InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
    // You may also override the JOSE encoder/decoder if needed
    // by providing extra arguments here
);
```

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

### Migrate token creation to new Builder API

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Migrates token creation from the old Builder API to the new Configuration-based API. Shows renamed methods, use of DateTimeImmutable, and manual header replication. Requires the new Configuration class and InMemory key.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

+use DateTimeImmutable; 
-use Lcobucci\JWT\Builder;
+use Lcobucci\JWT\Configuration;
+use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Signer\Hmac\Sha256;
-
-use function time;

-$now = time();
+$now = new DateTimeImmutable();
+$config = Configuration::forSymmetricSigner(new Sha256(), InMemory::plainText('testing'));

-$token = (new Builder())
+$token = $config->builder()
-    ->setIssuer('http://example.com', true)
+    ->issuedBy('http://example.com')
+    ->withHeader('iss', 'http://example.com')
-    ->setAudience('http://example.org')
+    ->permittedFor('http://example.org')
-    ->setId('4f1g23a12aa')
+    ->identifiedBy('4f1g23a12aa')
-    ->setSubject('user123')
+    ->relatedTo('user123')
-    ->setIssuedAt($now)
+    ->issuedAt($now)
-    ->setNotBefore($now + 60)
+    ->canOnlyBeUsedAfter($now->modify('+1 minute'))
-    ->setExpiration($now + 3600)
+    ->expiresAt($now->modify('+1 hour'))
-    ->set('uid', 1)
+    ->withClaim('uid', 1)
-    ->sign(new Sha256(), 'testing')
-    ->getToken();
+    ->getToken($config->signer(), $config->signingKey());
```

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

### Replace none algorithm with Blake2b

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows the diff for replacing the unsecured signer (none algorithm) with a symmetric signer using the non-standard Blake2b implementation. This is recommended for users relying on the removed 'none' algorithm.

```diff
<?php
declare(strict_types=1);

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

-$configuration = Configuration::forUnsecuredSigner();
+$configuration = Configuration::forSymmetricSigner(
+    new Signer\Blake2b(),
+    InMemory::base64Encoded('MpQd6dDPiqnzFSWmpUfLy4+Rdls90Ca4C8e0QD0IxqY=')
+);
```

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

### Create custom ClaimsFormatter and use with builder

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Creates a custom claims formatter by implementing ClaimsFormatter and uses it to build a token. The formatter serializes any claim value that implements Serializable. The configuration object is fetched from a hypothetical dependency injection container.

```php
use Lcobucci\JWT\ClaimsFormatter;
use Lcobucci\JWT\Configuration;
use Serializable;

final class ClaimSerializer implements ClaimsFormatter
{
    /** @inheritdoc  */
    public function formatClaims(array $claims): array
    {
        foreach ($claims as $claim => $claimValue) {
            if ($claimValue instanceof Serializable) {
                $claims[$claim] = $claimValue->serialize();
            }
        }

        return $claims;
    }
}

$config = $container->get(Configuration::class);
assert($config instanceof Configuration);

$builder = $config->builder(new ClaimSerializer());
```

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

### Create InMemory key from file path

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Creates an in-memory key by reading a file from the filesystem. The file contents are kept in memory.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

// this reads the file and keeps its contents in memory
$key = InMemory::file(__DIR__ . '/path-to-my-key-stored-in-a-file.pem');
```

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

### Register custom builder factory with withBuilderFactory

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Registers a custom builder factory in the configuration object. The factory receives a ClaimsFormatter and returns a Builder instance. The configuration object is fetched from a hypothetical dependency injection container.

```php
use Lcobucci\JWT\Builder;
use Lcobucci\JWT\ClaimsFormatter;
use Lcobucci\JWT\Configuration;

$config = $container->get(Configuration::class);
assert($config instanceof Configuration);

$configuration = $configuration->withBuilderFactory(
    static function (ClaimsFormatter $formatter): Builder {
        return new MyCustomTokenBuilder($formatter);
    }
);
```

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

### Use withUnixTimestampDates() for Unix timestamps

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows how to continue using Unix timestamps for date claims by using the withUnixTimestampDates() formatter. The old Builder constructor is replaced with the new builder method.

```diff
<?php

-$builder = new Builder());
+$builder = $config->builder(ChainedFormatter::withUnixTimestampDates());
```

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

### Implement Lcobucci\JWT\Builder interface

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/extending-the-library.md

Defines a custom token builder by implementing the Lcobucci\JWT\Builder interface. The class must implement all methods of the interface.

```php
use Lcobucci\JWT\Builder;

final class MyCustomTokenBuilder implements Builder
{
    // implement all methods
}
```

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

### Build and issue a JWT with Lcobucci\JWT

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/issuing-tokens.md

Creates a new JWT using the Lcobucci\JWT library with HMAC SHA-256 signing. Configures standard claims (iss, aud, sub, jti, iat, nbf, exp) plus a custom claim and header, then prints the token string. Requires a 32-byte random signing key and the vendor autoloader.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Encoding\ChainedFormatter;
use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Token\Builder;

require 'vendor/autoload.php';

$tokenBuilder = Builder::new(new JoseEncoder(), ChainedFormatter::default());
$algorithm    = new Sha256();
$signingKey   = InMemory::plainText(random_bytes(32));

$now   = new DateTimeImmutable();
$token = $tokenBuilder
    // Configures the issuer (iss claim)
    ->issuedBy('http://example.com')
    // Configures the audience (aud claim)
    ->permittedFor('http://example.org')
    // Configures the subject of the token (sub claim)
    ->relatedTo('component1')
    // Configures the id (jti claim)
    ->identifiedBy('4f1g23a12aa')
    // Configures the time that the token was issue (iat claim)
    ->issuedAt($now)
    // Configures the time that the token can be used (nbf claim)
    ->canOnlyBeUsedAfter($now->modify('+1 minute'))
    // Configures the expiration time of the token (exp claim)
    ->expiresAt($now->modify('+1 hour'))
    // Configures a new claim, called "uid"
    ->withClaim('uid', 1)
    // Configures a new header, called "foo"
    ->withHeader('foo', 'bar')
    // Builds a new token
    ->getToken($algorithm, $signingKey);

echo $token->toString();
```

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

### Create InMemory key from plain text

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Creates an in-memory key from a plain text string. Use this when the key content is directly available as a string.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$key = InMemory::plainText('my-key-as-plaintext');
```

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

### Configure symmetric signer with HMAC SHA-256

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Configures the library for symmetric algorithms (e.g., HMAC SHA-256). The same key is used for signing and verification, so it must remain secret. Use a key with high entropy, preferably generated with a CSPRNG.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$configuration = Configuration::forSymmetricSigner(
    new Signer\Hmac\Sha256(),
    // replace the value below with a key of your own!
    InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
    // You may also override the JOSE encoder/decoder if needed
    // by providing extra arguments here
);
```

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

### Create InMemory key from base64-encoded string

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Creates an in-memory key from a base64-encoded string. Use this when the key is provided in base64 format.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$key = InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=');
```

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

### Rotate parsing and validation logic with SignedWithOneInSet

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/rotating-keys.md

Diff showing the changes to the parsing and validation logic for a backwards compatible rotation. The old SignedWith constraint is replaced with SignedWithOneInSet containing two SignedWithUntilDate constraints, allowing tokens signed with either the old or new key until their respective expiration dates.

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Validation\Constraint;

// `FrozenClock` is used here to fix to a point in time that allows our
// validation to pass
$clock = new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:35+00:00'));

$validationConstraints = [
-    new Constraint\SignedWith(
-        new Signer\Hmac\Sha256(),
-        InMemory::plainText(
-            'a-very-long-and-secure-key-that-should-actually-be-something-else'
-        ),
-    ),
+    new Constraint\SignedWithOneInSet(
+       new Constraint\SignedWithUntilDate(
+           new Signer\Blake2b(),
+           InMemory::base64Encoded(
+               'GOu4rLyVCBxmxP+sbniU68ojAja5PkRdvv7vNvBCqDQ='
+           ),
+           new DateTimeImmutable('2025-12-31 23:59:59+00:00'),
+           $clock,
+       ),
+       new Constraint\SignedWithUntilDate(
+            new Signer\Hmac\Sha256(),
+           InMemory::plainText(
+                'a-very-long-and-secure-key-that-should-actually-be-something-else'
+           ),
+           new DateTimeImmutable('2023-12-31 23:59:59+00:00'),
+           $clock,
+       ),
+    ),
    new Constraint\StrictValidAt($clock),
];

$jwt = ''; // Fetched from, for example, a request header

$token = (new JwtFacade())->parse($jwt, ...$validationConstraints);
```

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

### Customize Parser with withParser

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Configures the token parser to use a custom Parser implementation. Must be called before any getter to take effect.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$configuration = Configuration::forSymmetricSigner(
    new Signer\Hmac\Sha256(),
    InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
);

// This assumes `MyParser` is an existing class 
$configuration = $configuration->withParser(new MyParser());
```

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

### Inject Configuration instead of builder/signer/key

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Migrate the injection of builder, signer, and key to a single Configuration object. The Configuration serves as a service locator centralising JWT-related dependencies. This change simplifies injection and provides a single way to initialise JWT components.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

-use Lcobucci\JWT\Builder;
 use Lcobucci\JWT\Configuration;
-use Lcobucci\JWT\Signer;
-use Lcobucci\JWT\Signer\Key;
 use Lcobucci\JWT\Token;

 use function bin2hex;
 use function random_bytes;

 final class JwtIssuer
 {
-    private Builder $builder;
-    private Signer $signer;
-    private Key $key;
- 
-    public function __construct(Builder $builder, Signer $signer, Key $key)
-    {
-        $this->builder = $builder;
-        $this->signer  = $signer;
-        $this->key     = $key;
-    }   
+    private Configuration $config;
+    
+    public function __construct(Configuration $config)
+    {
+        $this->config = $config;
+    }
    
    public function issueToken(): Token
    {
-        return $this->builder
+        return $this->config->builder()
            ->identifiedBy(bin2hex(random_bytes(16)))
-            ->getToken($this->signer, $this->key);
+            ->getToken($this->config->signer(), $this->config->signingKey());
    }
 }
```

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

### Migrate multiple audiences with argument unpacking

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Migrates multiple audience claims to a single permittedFor() call with argument unpacking. This replaces the old withClaim('aud', array) approach.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

-use Lcobucci\JWT\Builder;
+use Lcobucci\JWT\Configuration;
+use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Signer\Hmac\Sha256;

+$config = Configuration::forSymmetricSigner(new Sha256(), InMemory::plainText('testing'));

-$token = (new Builder())
+$token = $config->builder()
-    ->withClaim('aud', ['one', 'two', 'three'])
+    ->permittedFor(...['one', 'two', 'three'])
-    ->sign(new Sha256(), 'testing')
-    ->getToken();
+    ->getToken($config->signer(), $config->signingKey());
```

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

### Update to latest 4.3.x version using composer

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Run this command to update to the latest 4.3.x version of lcobucci/jwt before upgrading to v5.0.0. This is necessary to receive deprecation annotations.

```sh
composer require lcobucci/jwt ^4.3
```

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

### Customize Builder Factory with withBuilderFactory

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Configures the token builder factory to use a custom Builder implementation. Must be called before any getter to take effect.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Builder;
use Lcobucci\JWT\ClaimsFormatter;
use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

require 'vendor/autoload.php';

$configuration = Configuration::forSymmetricSigner(
    new Signer\Hmac\Sha256(),
    InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
);

$configuration = $configuration->withBuilderFactory(
    static function (ClaimsFormatter $formatter): Builder {
        // This assumes `MyCustomBuilder` is an existing class 
        return new MyCustomBuilder(new JoseEncoder(), $formatter);
    }
);
```

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

### Include Composer Autoloader

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/installation.md

Includes Composer's autoloader to use the library's classes. The documentation omits this line from other code samples for brevity.

```php
require 'vendor/autoload.php';
```

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

### Rotate issuing logic to BLAKE2B

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/rotating-keys.md

Diff showing the changes to the issuing logic when adopting the new BLAKE2B symmetric algorithm. The old HMAC SHA-256 signer and plain-text key are replaced with the Blake2b signer and a base64-encoded key.

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock;
use Lcobucci\JWT\Builder;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

// `FrozenClock` is used here to fix to a point in time that allows our validation to pass
$clock = new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:01+00:00')); 
$token = (new JwtFacade(clock: $clock))->issue(
-    new Signer\Hmac\Sha256(),
+    new Signer\Blake2b(),
-    InMemory::plainText(
-        'a-very-long-and-secure-key-that-should-actually-be-something-else'
+    InMemory::base64Encoded(
+        'GOu4rLyVCBxmxP+sbniU68ojAja5PkRdvv7vNvBCqDQ='
    ),
    static fn (Builder $builder): Builder => $builder
        ->issuedBy('https://api.my-awesome-app.io')
        ->permittedFor('https://client-app.io')
);
```

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

### Migrate multiple audiences with multiple permittedFor() calls

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Migrates multiple audience claims to multiple calls to permittedFor(). Each audience is added individually, replacing the old withClaim('aud', array) approach.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

-use Lcobucci\JWT\Builder;
+use Lcobucci\JWT\Configuration;
+use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Signer\Hmac\Sha256;

+$config = Configuration::forSymmetricSigner(new Sha256(), InMemory::plainText('testing'));

-$token = (new Builder())
+$token = $config->builder()
-    ->withClaim('aud', ['one', 'two', 'three'])
+    ->permittedFor('one')
+    ->permittedFor('two')
+    ->permittedFor('three')
-    ->sign(new Sha256(), 'testing')
-    ->getToken();
+    ->getToken($config->signer(), $config->signingKey());
```

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

### Set Validation Constraints with withValidationConstraints

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/configuration.md

Sets the base validation constraints used during validation. Includes SignedWith, StrictValidAt, and IssuedBy constraints.

```php
<?php
declare(strict_types=1);

use Lcobucci\Clock\SystemClock; // If you prefer, other PSR-20 implementations may also be used
                                // (https://packagist.org/providers/psr/clock-implementation)
use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Validation\Constraint\IssuedBy;
use Lcobucci\JWT\Validation\Constraint\SignedWith;
use Lcobucci\JWT\Validation\Constraint\StrictValidAt;

require 'vendor/autoload.php';

$configuration = Configuration::forSymmetricSigner(
    new Signer\Hmac\Sha256(),
    InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
);

$configuration = $configuration->withValidationConstraints(
    new SignedWith($configuration->signer(), $configuration->signingKey()),
    new StrictValidAt(SystemClock::fromUTC()),
    new IssuedBy('https://api.my-awesome-company.com')
);
```

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

### Upgrade to lcobucci/jwt 4.x

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Upgrade to the latest 4.x version after fixing all deprecation notices from 3.4.x. Some deprecation messages may indicate that things are still different in 4.0, so you may need to adapt your code once more.

```sh
composer require lcobucci/jwt ^4.0
```

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

### Use immutable Builder with JwtFacade

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Shows the diff for using the immutable Builder API with JwtFacade. The Builder methods now return a new instance, so you must assign the result back to the variable.

```diff
$token = (new JwtFacade())->issue(
    new Sha256(),
    $key,
    static function (
        Builder $builder,
        DateTimeImmutable $now
    ): Builder {
-        $builder->issuedBy('https://api.my-awesome-app.io');
-        $builder->permittedFor('https://client-app.io');
-        $builder->expiresAt($now->modify('+10 minutes'));
+        $builder = $builder->issuedBy('https://api.my-awesome-app.io');
+        $builder = $builder->permittedFor('https://client-app.io');
+        $builder = $builder->expiresAt($now->modify('+10 minutes'));

        return $builder;
    }
);
```

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

### Update to lcobucci/jwt 3.4.x

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Update to the latest 3.4.x version before migrating to v4.0.0. Run your tests and fix all deprecation notices, including those not triggering notices. Consider using phpstan/phpstan-deprecation-rules to help find deprecated calls.

```sh
composer require lcobucci/jwt ^3.4
```

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

### Migrate multiple audiences with single permittedFor() call

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/upgrading.md

Migrates multiple audience claims to a single permittedFor() call with multiple arguments. This replaces the old withClaim('aud', array) approach.

```diff
<?php
declare(strict_types=1);

namespace Me\MyApp\Authentication;

-use Lcobucci\JWT\Builder;
+use Lcobucci\JWT\Configuration;
+use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Signer\Hmac\Sha256;

+$config = Configuration::forSymmetricSigner(new Sha256(), InMemory::plainText('testing'));

-$token = (new Builder())
+$token = $config->builder()
-    ->withClaim('aud', ['one', 'two', 'three'])
+    ->permittedFor('one', 'two', 'three')
-    ->sign(new Sha256(), 'testing')
-    ->getToken();
+    ->getToken($config->signer(), $config->signingKey());
```

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

### Parse a JWT string with Parser and JoseEncoder

Source: https://github.com/lcobucci/jwt/blob/6.0.x/docs/parsing-tokens.md

Creates a parser with JoseEncoder and parses a JWT string. Catches CannotDecodeContent, InvalidTokenStructure, and UnsupportedHeaderFound exceptions. Asserts the result is an UnencryptedToken and prints the 'sub' claim.

```php
<?php
declare(strict_types=1);

use Lcobucci\JWT\Encoding\CannotDecodeContent;
use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Token\InvalidTokenStructure;
use Lcobucci\JWT\Token\Parser;
use Lcobucci\JWT\Token\UnsupportedHeaderFound;
use Lcobucci\JWT\UnencryptedToken;

require 'vendor/autoload.php';

$parser = new Parser(new JoseEncoder());

try {
    $token = $parser->parse(
        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
        . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
        . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
    );
} catch (CannotDecodeContent | InvalidTokenStructure | UnsupportedHeaderFound $e) {
    echo 'Oh no, an error: ' . $e->getMessage();
}
assert($token instanceof UnencryptedToken);

echo $token->claims()->get('sub'), PHP_EOL; // will print "1234567890"
```
Tokens:
Raw