### Development Setup Commands

Source: https://github.com/web-token/jwt-doc/blob/4.1/introduction/contributing.md

Commands to clone the repository, install dependencies, run tests, and check/fix coding standards.

```bash
git clone https://github.com/web-token/jwt-framework.git
cd jwt-framework

composer install

composer test

composer cs-check

composer cs-fix
```

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

### Quick Start: Build and Sign a JWT

Source: https://github.com/web-token/jwt-doc/blob/4.1/README.md

This example demonstrates how to create a JSON Web Signature (JWS) using the JWT Framework. It involves setting up an algorithm manager, a JWS builder, defining a key, and building/serializing the token.

```php
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Core\JWK;
use Jose\Component\Signature\Algorithm\HS256;
use Jose\Component\Signature\JWSBuilder;
use Jose\Component\Signature\Serializer\CompactSerializer;

// Create an algorithm manager
$algorithmManager = new AlgorithmManager([new HS256()]);

// Create a JWS Builder
$jwsBuilder = new JWSBuilder($algorithmManager);

// Create a key
$jwk = new JWK([
    'kty' => 'oct',
    'k' => 'your-secret-key-here',
]);

// Build and sign your token
$jws = $jwsBuilder
    ->create()
    ->withPayload(json_encode(['user_id' => 123]))
    ->addSignature($jwk, ['alg' => 'HS256'])
    ->build();

// Serialize to compact format
$serializer = new CompactSerializer();
$token = $serializer->serialize($jws, 0);
```

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

### Install Standalone Application

Source: https://github.com/web-token/jwt-doc/blob/4.1/console-command/standalone.md

Clone the repository and install dependencies using Composer. Ensure git and composer are installed.

```bash
git clone https://github.com/web-token/jwt-app.git
cd jwt-app
composer install --no-dev --optimize-autoloader --classmap-authoritative
```

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

### Install JWT Library

Source: https://github.com/web-token/jwt-doc/blob/4.1/introduction/the-framework.md

Use this command to install the core JWT library for any PHP project.

```bash
composer require web-token/jwt-library
```

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

### Get Help for a Key Generation Command

Source: https://github.com/web-token/jwt-doc/blob/4.1/console-command/console.md

Use the --help option to get detailed usage information for specific commands like key generation.

```bash
./jose.phar key:generate --help
```

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

### Install Dependencies

Source: https://github.com/web-token/jwt-doc/blob/4.1/CLAUDE.md

Install project dependencies using Castor.

```bash
castor install
```

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

### Add Experimental Features

Source: https://github.com/web-token/jwt-doc/blob/4.1/introduction/the-framework.md

Install the experimental package to access cutting-edge features and algorithms.

```bash
composer require web-token/jwt-experimental
```

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

### Install JWT Framework

Source: https://github.com/web-token/jwt-doc/blob/4.1/README.md

Install the JWT Framework using Composer. For Symfony projects, the bundle is automatically registered.

```bash
composer require web-token/jwt-framework
```

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

### Basic Bundle Extension Setup with Configuration Helper

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/configuration-helper.md

Demonstrates the basic structure of a Symfony bundle extension that implements `PrependExtensionInterface` to utilize the `ConfigurationHelper` during the `prepend` step.

```php
<?php

declare(strict_types=1);

namespace AcmeBundle\DependencyInjection;

use Jose\Bundle\JoseFramework\Helper\ConfigurationHelper;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
use Symfony\Component\HttpKernel\DependencyInjection\Extension;

final class AcmeExtension extends Extension implements PrependExtensionInterface
{
    ...

    /**
     * {@inheritdoc}
     */
    public function prepend(ContainerBuilder $container)
    {
        ... // The Helper will be called here
    }
}
```

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

### Run All Algorithm Benchmarks

Source: https://github.com/web-token/jwt-doc/blob/4.1/benchmark/benchmarks.md

Installs the library with all dev dependencies and runs performance tests for all supported JWT algorithms. This command can take over 7 hours to complete.

```bash
./vendor/bin/phpbench run --store
```

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

### Get Configured JWS Builder Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-creation.md

Retrieve a pre-configured JWS Builder service by its name, as defined in the bundle configuration. This allows direct access to a specific builder setup.

```php
<?php
$jwsBuilder = $container->get('jose.jws_builder.builder1');
```

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

### Adding Custom Tags to Key Set Services

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-set-management-jwkset.md

Example demonstrating how to attach custom tags and attributes to a key set service configuration. This can be used for service decoration or other custom logic.

```yaml
jose:
    key_sets:
        key_name:
            jku:
                url: 'https://login.microsoftonline.com/common/discovery/keys'
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}
```

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

### Initialize Algorithm Manager with Encryption Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/encrypted-tokens-jwe/encryption-algorithms.md

Instantiate the Algorithm Manager with common key encryption and content encryption algorithms. Ensure required libraries like 'spomky-labs/aes-key-wrap' are installed for KW algorithms.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\A128KW;
use Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS256A128KW;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A128CBCHS256;

$algorithmManager = new AlgorithmManager([
    new A128KW(),
    new PBES2HS256A128KW(),
    new A128CBCHS256(),
]);
```

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

### Key Set Configuration Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-set-management-jwkset.md

Basic configuration structure for defining key sets in the JWT framework. It shows how to name a key set and specify the method for loading keys, with an option to set its public visibility.

```yaml
jose:
    key_sets:
        keyset_name:
            method_name:
                ...
                is_public: true
```

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

### JWK Configuration with Custom Tags and Attributes

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-management-jwk.md

This example demonstrates how to add custom tags and attributes to a JWK configuration. These can be used for service decoration or metadata.

```yaml
jose:
    jwe:
        key_name:
            jwk:
                value: '{"kty":"oct","k":"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"}'
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}
```

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

### Complete JWT Signing, Verification, and Validation

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/examples/validation.md

This example shows the full lifecycle of a JWT: creating and signing it with a private key, loading and verifying the signature with a public key, and finally validating the claims against expected values. It requires the Jose Framework and Symfony Clock components.

```php
<?php

use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Checker\AudienceChecker;
use Jose\Component\Checker\ClaimCheckerManager;
use Jose\Component\Checker\ExpirationTimeChecker;
use Jose\Component\Checker\HeaderCheckerManager;
use Jose\Component\Checker\IssuedAtChecker;
use Jose\Component\Checker\IssuerChecker;
use Jose\Component\Checker\NotBeforeChecker;
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\KeyManagement\JWKFactory;
use Jose\Component\Signature\Algorithm\ES256;
use Jose\Component\Signature\JWSBuilder;
use Jose\Component\Signature\JWSLoader;
use Jose\Component\Signature\JWSTokenSupport;
use Jose\Component\Signature\JWSVerifier;
use Jose\Component\Signature\Serializer\CompactSerializer;
use Jose\Component\Signature\Serializer\JWSSerializerManager;
use Symfony\Component\Clock\NativeClock;

require_once 'vendor/autoload.php';

// --- 1. Create and sign the token ---

$privateKey = JWKFactory::createECKey('P-256', ['alg' => 'ES256', 'use' => 'sig']);

$algorithmManager = new AlgorithmManager([new ES256()]);

$payload = json_encode([
    'iss' => 'https://auth.example.com',
    'aud' => 'https://api.example.com',
    'sub' => 'user-42',
    'iat' => time(),
    'nbf' => time(),
    'exp' => time() + 3600,
]);

$jws = (new JWSBuilder($algorithmManager))
    ->create()
    ->withPayload($payload)
    ->addSignature($privateKey, ['alg' => 'ES256'])
    ->build();

$token = (new CompactSerializer())->serialize($jws);

// --- 2. Load and verify the signature ---

$publicKey = $privateKey->toPublic();

$jwsLoader = new JWSLoader(
    new JWSSerializerManager([new CompactSerializer()]),
    new JWSVerifier($algorithmManager),
    new HeaderCheckerManager(
        [new AlgorithmChecker(['ES256'])],
        [new JWSTokenSupport()]
    )
);

$signature = null;
$jws = $jwsLoader->loadAndVerifyWithKey($token, $publicKey, $signature);

// --- 3. Validate the claims ---

$clock = new NativeClock();

$claimCheckerManager = new ClaimCheckerManager([
    new IssuedAtChecker($clock),
    new NotBeforeChecker($clock),
    new ExpirationTimeChecker($clock),
    new IssuerChecker(['https://auth.example.com']),
    new AudienceChecker('https://api.example.com'),
]);

$claims = json_decode($jws->getPayload(), true);
$claimCheckerManager->check($claims, ['iss', 'aud', 'sub', 'exp']);

// If no exception is thrown, the token is valid and trusted
echo 'Token is valid for user: ' . $claims['sub'];

```

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

### Get Header and Claim Checker Manager Factories

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/header-and-claim-checker-management.md

Retrieve the Header and Claim Checker Manager Factory services from the container to create checker managers.

```php
<?php

use Jose\Component\Checker\HeaderCheckerManagerFactory;
use Jose\Component\Checker\ClaimCheckerManagerFactory;

$headerCheckerManagerFactory = $container->get(HeaderCheckerManagerFactory::class);
$headerCheckerManager = $headerCheckerManagerFactory->create([...]);

$claimCheckerManagerFactory = $container->get(ClaimCheckerManagerFactory::class);
$claimCheckerManager = $claimCheckerManagerFactory->create([...]);

```

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

### Configure JWS Builders and Verifiers

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/symfony-bundle.md

Configure JWS builders and verifiers in your Symfony application's configuration file. This example sets up a builder and verifier using the HS256 signature algorithm.

```yaml
jose:
    # Configure the algorithm manager
    jws:
        builders:
            my_jws_builder:
                signature_algorithms: ['HS256']

        verifiers:
            my_jws_verifier:
                signature_algorithms: ['HS256']

```

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

### Initialize Algorithm Manager with Signature Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/signed-tokens-jws/signature-algorithms.md

Demonstrates how to instantiate the Algorithm Manager with common signature algorithms like PS256, ES512, and None. Ensure the necessary algorithm classes are imported.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\Algorithm\PS256;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\Algorithm\None;

$algorithm_manager = new AlgorithmManager([
    new PS256(),
    new ES512(),
    new None(),
]);

```

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

### Get JWSBuilderFactory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-creation.md

Retrieve the JWSBuilderFactory service from the Symfony application container. This is the primary way to get a JWS builder instance.

```php
<?php
use Jose\Component\Signature\JWSBuilderFactory;

$jwsBuilderFactory = $container->get(JWSBuilderFactory::class);
```

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

### Adding a JWK Service using ConfigurationHelper

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/configuration-helper.md

Shows how to use `ConfigurationHelper::addKey` to define a JWK service. This method simplifies the creation of key services by abstracting the underlying configuration details.

```php
ConfigurationHelper::addKey(
    $container,
    'acme_my_key',
    'jwk', [
        'value' => '{\"kty\":\"oct\",\"k\":\"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"}',
        'is_public' => true,
    ],
    [
        'tag_name1' => [],
        'tag_name2' => ['attribute1' => 'foo'],
    ]
);
```

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

### JWE JSON General Serialization Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/serialization.md

This example demonstrates the JWE JSON General serialization format, which is similar to Flattened but can include multiple recipients.

```javascript
 {
  "protected":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
  "unprotected":{"jku":"https://server.example.com/keys.jwks"},
  "recipients":[
    {
      "header":{"alg":"RSA1_5","kid":"2011-04-29"},
      "encrypted_key":"UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"
    },
    {
      "header":{"alg":"A128KW","kid":"7"},
      "encrypted_key":"6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"
    }
  ],
  "iv":"AxY8DCtDaGlsbGljb3RoZQ",
  "ciphertext":"KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY",
  "tag":"Mz-VPPyU4RlcuYv1IwIvzw"
 }
```

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

### Load and Verify Token with JWSLoader

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/examples/signed-tokens.md

Demonstrates using JWSLoader to deserialize, check headers (e.g., algorithm), and verify a token's signature in a single step. This is the recommended method for loading tokens.

```php
<?php

use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Checker\HeaderCheckerManager;
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Core\JWK;
use Jose\Component\Signature\Algorithm\HS256;
use Jose\Component\Signature\JWSLoader;
use Jose\Component\Signature\JWSTokenSupport;
use Jose\Component\Signature\JWSVerifier;
use Jose\Component\Signature\Serializer\CompactSerializer;
use Jose\Component\Signature\Serializer\JWSSerializerManager;

require_once 'vendor/autoload.php';

$jwk = /* your verification key */;

$algorithmManager = new AlgorithmManager([new HS256()]);

$jwsLoader = new JWSLoader(
    new JWSSerializerManager([new CompactSerializer()]),
    new JWSVerifier($algorithmManager),
    new HeaderCheckerManager(
        [new AlgorithmChecker(['HS256'])] , // Only allow HS256
        [new JWSTokenSupport()]
    )
);

$signature = null;
$jws = $jwsLoader->loadAndVerifyWithKey($token, $jwk, $signature);

$payload = json_decode($jws->getPayload(), true);

```

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

### JWE JSON Flattened Serialization Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/serialization.md

This is an example of the JWE JSON Flattened serialization format, which is a simple JSON object useful when the unprotected header needs to be used.

```javascript
{
  "protected":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
  "unprotected":{"jku":"https://server.example.com/keys.jwks"},
  "header":{"alg":"A128KW","kid":"7"},
  "encrypted_key":"6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ",
  "iv":"AxY8DCtDaGlsbGljb3RoZQ",
  "ciphertext":"KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY",
  "tag":"Mz-VPPyU4RlcuYv1IwIvzw"
}
```

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

### Running the Test Suite

Source: https://github.com/web-token/jwt-doc/blob/4.1/introduction/contributing.md

Command to execute the project's test suite using PHPUnit.

```bash
vendor/bin/phpunit
```

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

### Initialize JWSBuilder

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/signed-tokens-jws/jws-creation.md

Instantiate the JWSBuilder with an AlgorithmManager and a JWK. The AlgorithmManager must be configured with the desired signing algorithm.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Core\JWK;
use Jose\Component\Signature\Algorithm\HS256;
use Jose\Component\Signature\JWSBuilder;

// The algorithm manager with the HS256 algorithm.
$algorithmManager = new AlgorithmManager([
    new HS256(),
]);

// Our key.
$jwk = new JWK([
    'kty' => 'oct',
    'k' => 'dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g',
]);

// We instantiate our JWS Builder.
$jwsBuilder = new JWSBuilder($algorithmManager);
```

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

### Get JWESerializerManagerFactory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-serializers.md

Retrieve the JWESerializerManagerFactory service from the container to create serializer managers.

```php
<?php
use Jose\Component\Encryption\JWESerializerManagerFactory;

$jweSerializerManagerFactory = $container->get(JWESerializerManagerFactory::class);
```

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

### Get JWSSerializerManagerFactory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-serializers.md

Retrieve the JWSSerializerManagerFactory service from the container to create JWS serializer managers.

```php
<?php
use Jose\Component\Signature\JWSSerializerManagerFactory;

$jwsSerializerManagerFactory = $container->get(JWSSerializerManagerFactory::class);
```

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

### Get JWELoaderFactory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-decryption.md

Retrieve the JWELoaderFactory service from the application container to create JWELoader instances.

```php
<?php
use Jose\Component\Encryption\JWELoaderFactory;

$jweLoaderFactory = $container->get(JWELoaderFactory::class);
```

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

### Get Configured JWEDecrypter Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-decryption.md

Retrieve a pre-configured JWEDecrypter service by its service name from the container.

```php
<?php
$jweDecrypter = $container->get('jose.jwe_decrypter.decrypter1');
```

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

### Get JWEDecrypterFactory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-decryption.md

Retrieve the JWEDecrypterFactory service from the application container to create JWEDecrypter instances.

```php
<?php
use Jose\Component\Encryption\JWEDecrypterFactory;

$jweDecrypterFactory = $container->get(JWEDecrypterFactory::class);
```

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

### Get JWEBuilderFactory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-creation.md

Retrieve the JWEBuilderFactory service from the application container to create JWE builders.

```php
<?php
use Jose\Component\Encryption\JWEBuilderFactory;

$jweBuilderFactory = $container->get(JWEBuilderFactory::class);
```

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

### Initialize JWEBuilder with Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/encrypted-tokens-jwe/jwe-creation.md

Instantiate the AlgorithmManager with key encryption and content encryption algorithms, then use it to create a JWEBuilder. This is the first step in JWE creation.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\A256KW;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A256CBCHS512;
use Jose\Component\Encryption\JWEBuilder;

// The algorithm manager with both key encryption and content encryption algorithms.
$algorithmManager = new AlgorithmManager([
    new A256KW(),        // Key Encryption Algorithm
    new A256CBCHS512(),  // Content Encryption Algorithm
]);

// We instantiate our JWE Builder.
$jweBuilder = new JWEBuilder($algorithmManager);
```

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

### Get Configured JWESerializerManager Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-serializers.md

Retrieve the custom JWESerializerManager service ('jose.jwe_serializer.serializer1') configured via YAML from the container.

```php
<?php
$jweSerializerManager = $container->get('jose.jwe_serializer.serializer1');
```

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

### Create Algorithm Manager Instance

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/algorithm-management.md

Instantiate the Algorithm Manager Factory service and use it to create an algorithm manager with a list of desired algorithms.

```php
<?php

use Jose\Component\Core\AlgorithmManagerFactory;

$algorithmManagerFactory = $container->get(AlgorithmManagerFactory::class);
$algorithmManager = $algorithmManagerFactory->create(['RS256', 'HS512']);

```

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

### Get Configured JWE Builder Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-creation.md

Retrieve a pre-configured JWE Builder service by its service name from the container.

```php
<?php
$jweBuilder = $container->get('jose.jwe_builder.builder1');
```

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

### Add JWELoader using ConfigurationHelper

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-decryption.md

Programmatically add a JWELoader service using the ConfigurationHelper, specifying all necessary parameters.

```php
<?php
use Jose\Bundle\JoseFramework\Helper\ConfigurationHelper;

... 
ConfigurationHelper::addJWELoader($container, 'jwe_loader1', ['jwe_compact'], ['A256GCMKW', 'A256CBC-HS256'], ['alg', 'enc'], true);
```

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

### Get JWS Loader Factory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-verification.md

Retrieve the JWSLoaderFactory service from the Symfony container to create JWS Loader instances.

```php
<?php
use Jose\Component\Signature\JWSLoaderFactory;

$jwsLoaderFactory = $container->get(JWSLoaderFactory::class);
```

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

### Loading Key from an X509 Certificate File

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-management-jwk.md

Configure a key to be loaded from an X509 certificate file. Specify the path to the certificate file and optionally include additional values like 'use' and 'alg'.

```yaml
jose:
    keys:
        key_name:
            certificate:
                path: '/path/to/your/X509/certificate'
                additional_values:
                    use: 'sig'
                    alg: 'RS256'
```

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

### Get Configured JWS Verifier Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-verification.md

Retrieve a pre-configured JWS Verifier service by its service name from the Symfony container.

```php
<?php
$jwsVerifier = $container->get('jose.jws_verifier.verifier1');
```

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

### Get JWS Verifier Factory Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-verification.md

Retrieve the JWSVerifierFactory service from the Symfony container to create JWS verifier instances.

```php
<?php
use Jose\Component\Signature\JWSVerifierFactory;

$jwsVerifierFactory = $container->get(JWSVerifierFactory::class);
```

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

### Add JWS Loader using ConfigurationHelper

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-verification.md

Programmatically add a JWS Loader service using the ConfigurationHelper, specifying all necessary parameters.

```php
<?php
use Jose\Bundle\JoseFramework\Helper\ConfigurationHelper;

... 
ConfigurationHelper::addJWSLoader($container, 'jws_loader1', ['jws_compact'], ['HS256'], ['alg'], true);
```

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

### App\EventSubscriber\JwsSubscriber.php

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/events.md

An example event subscriber for JWS-related events. Implement this to react to JWS verification and build success or failure events.

```php
<?php

declare(strict_types=1);

namespace App\EventSubscriber;

use Jose\Bundle\JoseFramework\Event\Events;
use Jose\Bundle\JoseFramework\Event\JWSBuiltSuccessEvent;
use Jose\Bundle\JoseFramework\Event\JWSVerificationFailureEvent;
use Jose\Bundle\JoseFramework\Event\JWSVerificationSuccessEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class JwsSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            Events::JWS_VERIFICATION_SUCCESS => ['onJwsVerificationSuccess'],
            Events::JWS_VERIFICATION_FAILURE => ['onJwsVerificationFailure'],
            Events::JWS_BUILT_SUCCESS => ['onJwsBuiltSuccess'],
            Events::JWS_BUILT_FAILURE => ['onJwsBuiltFailure'],
        ];
    }

    public function onJwsVerificationSuccess(JWSVerificationSuccessEvent $event): void
    {
        // Do something here
    }

    public function onJwsVerificationFailure(JWSVerificationFailureEvent $event): void
    {
        // Do something here
    }

    public function onJwsBuiltSuccess(JWSBuiltSuccessEvent $event): void
    {
        // Do something here
    }

    public function onJwsBuiltFailure(JWSBuiltFailureEvent $event): void
    {
        // Do something here
    }
}

```

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

### Get Configured JWS Serializer Service

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-serializers.md

Retrieve a JWS serializer manager service that has been configured via the bundle's YAML settings.

```php
<?php
$jwsSerializerManager = $container->get('jose.jws_serializer.serializer1');
```

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

### Create an Algorithm Manager with Specific Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/algorithm-management-jwa.md

Instantiate an AlgorithmManager and add specific signature algorithms like PS256 and ES512. Ensure no algorithm is added twice to the same manager.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\Algorithm\PS256;
use Jose\Component\Signature\Algorithm\ES512;

$algorithmManager = new AlgorithmManager([
    new PS256(),
    new ES512(),
]);

```

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

### Test RSA1_5 Algorithm

Source: https://github.com/web-token/jwt-doc/blob/4.1/benchmark/benchmarks.md

Executes performance benchmarks for the RSA1_5 signature algorithm.

```bash
./vendor/bin/phpbench run --group RSA1_5 --store
```

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

### Loading Key Set from X509 Certificates URL (X5U)

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-set-management-jwkset.md

Configuration to load a key set from a distant URL containing X509 certificates. The remote resource must provide a list of X509 certificates.

```yaml
jose:
    key_sets:
        key_name:
            x5u:
                url: 'https://www.googleapis.com/oauth2/v1/certs'
```

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

### Create JWEBuilder Instance

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-creation.md

Instantiate a JWEBuilder using the JWEBuilderFactory with specified encryption algorithms.

```php
$jweBuilder = $jweBuilderFactory->create(['A256GCMKW', 'A256CBC-HS256']);
```

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

### Custom Claim Checker Implementation

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/claim-checker.md

Example of a custom claim checker for the 'foo' claim. It validates that the claim is a string and its value is either 'bar' or 'bat'.

```php
<?php

declare(strict_types=1);

namespace Acme\Checker;

use Jose\Component\Checker\ClaimChecker;
use Jose\Component\Checker\InvalidClaimException;

/**
 * Class FooChecker.
 */
final class FooChecker implements ClaimChecker
{
    /**
     * {@inheritdoc}
     */
    public function checkClaim($value)
    {
        if (!is_string($value)) { // If the value is not a string, then we throw an exception
            throw new InvalidClaimException('The claim "foo" must be a string.', 'foo', $value);
        }
        if (!in_array($value, ['bar', 'bat'])) { // Check if the value is allowed
            throw new InvalidClaimException('The claim "foo" must be "bar" or "bat".', 'foo', $value);
        }
    }

    /**
     * {@inheritdoc}
     */
    public function supportedClaim(): string
    {
        return 'foo'; //The claim to check.
    }
}
```

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

### Run Static Analysis

Source: https://github.com/web-token/jwt-doc/blob/4.1/CLAUDE.md

Execute static analysis using PHPStan via Castor.

```bash
castor phpstan
```

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

### Convert and Save a Key

Source: https://github.com/web-token/jwt-doc/blob/4.1/console-command/console.md

Convert a key to a different format (e.g., JWK to PEM) and save the output to a file.

```bash
./jose.phar key:convert:pkcs1 '{"kty":"EC",...}' > key.pem
```

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

### Initialize PBES2 Algorithm with Custom Salt and Count

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/encrypted-tokens-jwe/encryption-algorithms.md

Instantiate the PBES2-HS256+A128KW algorithm with custom salt size (16 bytes) and iteration count (1024). This is useful when specific security requirements necessitate non-default PBKDF2 parameters.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS256A128KW;

$algorithmManager = new AlgorithmManager([
    new PBES2HS256A128KW(16, 1024),
]);
```

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

### JWS Compact Serialization Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/serialization.md

The JWS Compact serialization is a string of Base64Url encoded parts separated by dots. It is URL-safe and commonly used but does not support unprotected headers.

```text
eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA.AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZqwqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8KpEHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn
```

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

### Run Standalone Console Command

Source: https://github.com/web-token/jwt-doc/blob/4.1/console-command/standalone.md

Execute the standalone console command located in the 'bin' folder.

```bash
./bin/jose
```

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

### JWKSet Object Methods

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/key-jwk-and-key-set-jwkset/key-set-management.md

Illustrates common operations on a JWKSet object, such as retrieving all keys, checking for a specific key by ID, getting a key, counting keys, and iterating through the set.

```php
$jwkset->all();

$jwkset->has('KEY ID');

$jwkset->get('KEY ID');

$jwkset->count(); // The method count($jwkset) has the same behaviour.

foreach($jwkset as $kid => $jwk) {
    // Action with the key done here
}
```

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

### Run Parallel Linting

Source: https://github.com/web-token/jwt-doc/blob/4.1/CLAUDE.md

Perform PHP parallel linting using Castor.

```bash
castor lint
```

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

### Symfony Configuration for Nested Token Builders

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/nested-tokens.md

Configure nested token builders within the Symfony `jose` configuration. This example defines algorithms and serializers for a builder named 'builder_1'.

```yaml
jose:
    nested_token:
        builders:
            builder_1:
                signature_algorithms: ['PS256']
                key_encryption_algorithms: ['RSA-OAEP']
                content_encryption_algorithms: ['A128GCM']
                jws_serializers: ['jws_compact']
                jwe_serializers: ['jwe_compact']
                is_public: true
```

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

### Verify Allowed Licenses

Source: https://github.com/web-token/jwt-doc/blob/4.1/CLAUDE.md

Check if project dependencies comply with allowed licenses using Castor.

```bash
castor checkLicenses
```

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

### Symfony Configuration for Nested Token Loaders

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/nested-tokens.md

Configure nested token loaders within the Symfony `jose` configuration. This example defines algorithms and serializers for a loader named 'loader_1'.

```yaml
jose:
    nested_token:
        loaders:
            loader_1:
                signature_algorithms: ['PS256']
                key_encryption_algorithms: ['RSA-OAEP']
                content_encryption_algorithms: ['A128GCM']
                jws_serializers: ['jws_compact']
                jws_header_checkers: []
                jwe_serializers: ['jwe_compact']
                jwe_header_checkers: []
                is_public: true
```

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

### Initialize JWEDecrypter with Algorithm Manager

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/encrypted-tokens-jwe/jwe-loading.md

Instantiate a JWEDecrypter with an Algorithm Manager that supports both key encryption and content encryption algorithms. This is a prerequisite for decrypting JWE tokens.

```php
<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\A256KW;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A256CBCHS512;
use Jose\Component\Encryption\JWEDecrypter;

// The algorithm manager with both key encryption and content encryption algorithms.
$algorithmManager = new AlgorithmManager([
    new A256KW(),        // Key Encryption Algorithm
    new A256CBCHS512(),  // Content Encryption Algorithm
]);

// We instantiate our JWE Decrypter.
$jweDecrypter = new JWEDecrypter($algorithmManager);

```

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

### Create JWS Verifier with Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/signed-tokens/jws-verification.md

Use the JWSVerifierFactory to create a JWSVerifier instance, specifying the allowed signature algorithms.

```php
$jwsVerifier = $jwsVerifierFactory->create(['HS256']);
```

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

### JWE Compact Serialization Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/serialization.md

The JWE Compact serialization is a string of five Base64Url encoded parts separated by dots. It is not suitable for Additional Authentication Data or shared/per-recipient unprotected headers.

```text
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A.AxY8DCtDaGlsbGljb3RoZQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.9hH0vgRfYgPnAHOd8stkvw
```

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

### Create JWEDecrypter with Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/encrypted-tokens/jwe-decryption.md

Use the JWEDecrypterFactory to create a JWEDecrypter instance, specifying the allowed encryption algorithms.

```php
$jweDecrypter = $jweDecrypterFactory->create(['HS256']);
```

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

### Enabling JKU Factory for Distant Key Sets

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-set-management-jwkset.md

Configuration to enable the JKU Factory service for loading key sets from distant URIs. Requires the Symfony Http Client to be installed and enabled.

```yaml
jose:
    jku_factory:
        enabled: true
        client: 'http_client'
```

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

### Test HMAC Algorithms

Source: https://github.com/web-token/jwt-doc/blob/4.1/benchmark/benchmarks.md

Runs performance benchmarks specifically for HMAC signature algorithms.

```bash
./vendor/bin/phpbench run --group hmac --store
```

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

### Create JWSLoader using JWSLoaderFactory

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/signed-tokens-jws/jws-loading.md

Utilize the JWSLoaderFactory to create JWSLoader instances on demand, specifying the desired serializer, signature algorithm, and header checker aliases.

```php
<?php

use Jose\Component\Signature\JWSLoaderFactory;

$jwsLoaderFactory = new JWSLoaderFactory(
    $jwsSerializerManagerFactory,
    $jwsVerifierFactory,
    $headerCheckerManagerFactory
);

$jwsLoader = $jwsLoaderFactory->create(
    ['jws_compact'], // List of serializer aliases
    ['HS256'],       // List of signature algorithm aliases
    ['alg']          // Optional list of header checker aliases
);

```

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

### Custom Header Checker Implementation

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/header-checker.md

Implement the HeaderChecker interface to create a custom checker for header parameters like 'custom'. This example checks if the 'custom' header is an array with 'foo' or 'bar' as values.

```php
<?php

namespace Acme\Checker;

use Jose\Component\Checker\HeaderChecker;
use Jose\Component\Checker\InvalidHeaderException;

final class CustomChecker implements HeaderChecker
{
    public function checkHeader($value)
    {
        if (!is_array($value) || !in_array($value, ['foo', 'bar'], true)) {
            throw new InvalidHeaderException('Invalid header "custom".', 'custom', $value);
        }
    }

    // This header parameter name.
    public function supportedHeader(): string
    {
        return 'custom';
    }

    // This method indicates if this parameter must be in the protected header or not.
    public function protectedHeaderOnly(): bool
    {
        return true;
    }
}

```

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

### JWS JSON General Serialization Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/serialization.md

The JWS JSON General serialization is a JSON object that can contain multiple signatures, making it suitable for scenarios requiring several verification keys or algorithms.

```javascript
{
  "payload": "SW4gb3VyIHZpbGxhZ2UsIGZvbGtzIHNheSBHb2QgY3J1bWJsZXMgdXAgdGhlIG9sZCBtb29uIGludG8gc3RhcnMu",
  "signatures": [
    {
      "protected": "eyJhbGciOiJSUzI1NiJ9",
      "header": {
        "kid": "myRsaKey"
      },
      "signature": "B04c24gSnpVm1Z-_bemfyNMCpZm6Knj1yB-yzaIOvijsWfDgoF_mSJccTIbzapNgwJudnobr5iDOfZWiRR9iqCyDJLe5M1S40vFF7MFEI3JecYRgrRc6n1lTkYLMRyVq48BwbQlmKgPqmK9drun3agklsr0FmgNx65pfmcnlYdXsgwxf8WbgppefrlrMImp-98-dNtBcUL8ce1aOjbcyVFjGMCzpm3JerQqIzWQvEwBstnMEQle73KHcyx_nsTmlzY70CaydbRTsciOATL7WfiMwuX1q9Y2NIpTg3CbOTWKdwjh7iyfiAKQxNBaF2mApnqj9hjpf8GwR-CfxAzJtPg"
    },
    {
      "protected": "eyJhbGciOiJFUzI1NiJ9",
      "header": {
        "kid": "myEcKey"
      },
      "signature": "2cbugKq0ERaQMh01n2B-86EZFYleeMf8bsccaQMxzOxAg14PxfjR3IImvodTJYqkmfBJYW203etz2-7ZtJUOGw"
    },
    {
      "protected": "eyJhbGciOiJIUzI1NiJ9",
      "header": {
        "kid": "myMacKey"
      },
      "signature": "e7R9gjx0RsUNa3c7qd8k9mQGEhtcG8vsN1W7jbLb2MA"
    }
  ]
}
```

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

### Create Key From File

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/key-jwk-and-key-set-jwkset/key-management.md

Loads a JWK from a key file (PEM or DER format, PKCS#1 or PKCS#8). Supports encrypted keys by providing the secret passphrase. Additional parameters can be set during loading.

```php
<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromKeyFile(
    '/path/to/my/key/file.pem', // The filename
    'Secret',                   // Secret if the key is encrypted, otherwise null
    [
        'use' => 'sig',         // Additional parameters
    ]
);

```

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

### Create Header Checker Managers

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-components/header-checker.md

Instantiate the HeaderCheckerManagerFactory, add checkers and token type supports, and then create specific managers for signatures or encryption.

```php
<?php

use Jose\Component\Checker\HeaderCheckerManagerFactory;
use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Encryption\JWETokenSupport;
use Jose\Component\Signature\JWSTokenSupport;

$headerCheckerManagerFactory = new HeaderCheckerManagerFactory();
$headerCheckerManagerFactory->add('signature_alg', new AlgorithmChecker(['HS256']));
$headerCheckerManagerFactory->add('key_encryption_alg', new AlgorithmChecker(['RSA1_5']));
$headerCheckerManagerFactory->addTokenTypeSupport(new JWSTokenSupport());
$headerCheckerManagerFactory->addTokenTypeSupport(new JWETokenSupport());

$headerCheckerManagerForSignatures = $headerCheckerManagerFactory->create(['signature_alg']);
$headerCheckerManagerForEncryption = $headerCheckerManagerFactory->create(['key_encryption_alg']);

```

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

### JWS JSON Flattened Serialization Example

Source: https://github.com/web-token/jwt-doc/blob/4.1/advanced-topics/serialization.md

The JWS JSON Flattened serialization is a JSON object useful for including unprotected headers. It contains the payload, protected header, optional header, and signature.

```javascript
{
  "payload": "SW4gb3VyIHZpbGxhZ2UsIGZvbGtzIHNheSBHb2QgY3J1bWJsZXMgdXAgdGhlIG9sZCBtb29uIGludG8gc3RhcnMu",
  "protected": "eyJhbGciOiJFUzI1NiJ9",
  "header": {
    "kid": "myEcKey"
  },
  "signature": "b7V2UpDPytr-kMnM_YjiQ3E0J2ucOI9LYA7mt57vccrK1rb84j9areqgQcJwOA00aWGoz4hf6sMTBfobdcJEGg"
}
```

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

### Basic Key Configuration Structure

Source: https://github.com/web-token/jwt-doc/blob/4.1/the-symfony-bundle/key-and-key-set-management/key-management-jwk.md

This YAML structure outlines the basic configuration for defining keys within the JWT framework. It shows the hierarchical setup for naming keys and specifying their loading methods.

```yaml
jose:
    keys:
        key_name:
            method_name:
                ...
                is_public: true
```