Merge release 5.5.0 into 6.0.x

.gitattributes

@@ -11,3 +11,5 @@
 /README.md                                export-ignore
 /Makefile                                 export-ignore
 /.roave-backward-compatibility-check.json export-ignore
+/.readthedocs.yaml                        export-ignore
+/renovate.json                            export-ignore

.github/workflows/backwards-compatibility.yml

@@ -16,7 +16,7 @@ jobs:
           fetch-depth: 0
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           php-version: "8.2"
           ini-values: memory_limit=-1
@@ -29,7 +29,7 @@ jobs:
         run: echo "composer_cache_dir=$(composer global config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: "Cache dependencies"
-        uses: "actions/cache@v4.1.2"
+        uses: "actions/cache@v4.2.0"
         with:
           path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
           key: "php-8.2-bc-break-check-${{ hashFiles('.github/workflows/backwards-compatibility.yml') }}"

.github/workflows/benchmarks.yml

@@ -24,35 +24,17 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, cs2pr
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install lowest dependencies"
-        if: ${{ matrix.dependencies == 'lowest' }}
-        run: "composer update --prefer-lowest --no-interaction --no-progress"
-
-      - name: "Install highest dependencies"
-        if: ${{ matrix.dependencies == 'highest' }}
-        run: "composer update --no-interaction --no-progress"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress"
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: "PhpBench"
         run: "make phpbench"

.github/workflows/coding-standards.yml

@@ -24,35 +24,17 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, cs2pr
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install lowest dependencies"
-        if: ${{ matrix.dependencies == 'lowest' }}
-        run: "composer update --prefer-lowest --no-interaction --no-progress"
-
-      - name: "Install highest dependencies"
-        if: ${{ matrix.dependencies == 'highest' }}
-        run: "composer update --no-interaction --no-progress"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress"
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: "Coding Standard"
         run: "make phpcs PHPCS_FLAGS='-q --report=checkstyle | cs2pr'"

.github/workflows/composer-json-lint.yml

@@ -24,35 +24,17 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, composer-normalize, composer-require-checker, composer-unused
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install lowest dependencies"
-        if: ${{ matrix.dependencies == 'lowest' }}
-        run: "composer update --prefer-lowest --no-interaction --no-progress"
-
-      - name: "Install highest dependencies"
-        if: ${{ matrix.dependencies == 'highest' }}
-        run: "composer update --no-interaction --no-progress"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress"
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: "Validate composer.json"
         run: "composer validate --strict"

.github/workflows/mutation-tests.yml

@@ -24,38 +24,20 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "xdebug"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, cs2pr
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install lowest dependencies"
-        if: ${{ matrix.dependencies == 'lowest' }}
-        run: "composer update --prefer-lowest --no-interaction --no-progress"
-
-      - name: "Install highest dependencies"
-        if: ${{ matrix.dependencies == 'highest' }}
-        run: "composer update --no-interaction --no-progress"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress"
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: "Infection"
         run: "make infection PHPUNIT_FLAGS=--coverage-clover=coverage.xml INFECTION_FLAGS=--logger-github"
 
       - name: "Upload Code Coverage"
-        uses: "codecov/codecov-action@v5.0.7"
+        uses: "codecov/codecov-action@v5.3.1"

.github/workflows/phpunit.yml

@@ -16,7 +16,6 @@ jobs:
           - "lowest"
           - "highest"
           - "locked"
-          - "development"
         php-version:
           - "8.2"
           - "8.3"
@@ -29,39 +28,17 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, cs2pr
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install lowest dependencies"
-        if: ${{ matrix.dependencies == 'lowest' }}
-        run: "composer update --prefer-lowest --no-interaction --no-progress"
-
-      - name: "Install highest dependencies"
-        if: ${{ matrix.dependencies == 'highest' }}
-        run: "composer update --no-interaction --no-progress"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress"
-
-      - name: "Install development dependencies"
-        if: ${{ matrix.dependencies == 'development' }}
-        run: "composer config minimum-stability dev && composer update --no-interaction --no-progress"
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: "Tests"
         run: "make phpunit"
@@ -76,7 +53,7 @@ jobs:
         dependencies:
           - "locked"
         php-version:
-          - "8.4"
+          - "8.5"
         operating-system:
           - "ubuntu-latest"
 
@@ -85,27 +62,18 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, cs2pr
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress --ignore-platform-req=php"
+          dependency-versions: "${{ matrix.dependencies }}"
+          composer-options: " --ignore-platform-req=php"
 
       - name: "Tests"
         run: "make phpunit"

.github/workflows/static-analysis.yml

@@ -24,35 +24,17 @@ jobs:
         uses: "actions/[email protected]"
 
       - name: "Install PHP"
-        uses: "shivammathur/setup-php@2.31.1"
+        uses: "shivammathur/setup-php@2.32.0"
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
           ini-values: memory_limit=-1
           tools: composer:v2, cs2pr
 
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "composer_cache_dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: "actions/[email protected]"
+      - name: "Install dependencies"
+        uses: "ramsey/[email protected]"
         with:
-          path: ${{ steps.composer-cache.outputs.composer_cache_dir }}
-          key: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-${{ matrix.dependencies }}-"
-
-      - name: "Install lowest dependencies"
-        if: ${{ matrix.dependencies == 'lowest' }}
-        run: "composer update --prefer-lowest --no-interaction --no-progress"
-
-      - name: "Install highest dependencies"
-        if: ${{ matrix.dependencies == 'highest' }}
-        run: "composer update --no-interaction --no-progress"
-
-      - name: "Install locked dependencies"
-        if: ${{ matrix.dependencies == 'locked' }}
-        run: "composer install --no-interaction --no-progress"
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: "PHPStan"
         run: "make phpstan"

docs/configuration.md

@@ -136,7 +136,7 @@ $configuration = Configuration::forSymmetricSigner(
     InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
 );
 
-$configuration->setBuilderFactory(
+$configuration = $configuration->withBuilderFactory(
     static function (ClaimsFormatter $formatter): Builder {
         // This assumes `MyCustomBuilder` is an existing class 
         return new MyCustomBuilder(new JoseEncoder(), $formatter);
@@ -165,7 +165,7 @@ $configuration = Configuration::forSymmetricSigner(
 );
 
 // This assumes `MyParser` is an existing class 
-$configuration->setParser(new MyParser());
+$configuration = $configuration->withParser(new MyParser());
 ```
 
 ### Validator
@@ -189,7 +189,7 @@ $configuration = Configuration::forSymmetricSigner(
 );
 
 // This assumes `MyValidator` is an existing class
-$configuration->setValidator(new MyValidator());
+$configuration = $configuration->withValidator(new MyValidator());
 ```
 
 ### Validation constraints
@@ -216,7 +216,7 @@ $configuration = Configuration::forSymmetricSigner(
     InMemory::base64Encoded('mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=')
 );
 
-$configuration->setValidationConstraints(
+$configuration = $configuration->withValidationConstraints(
     new SignedWith($configuration->signer(), $configuration->signingKey()),
     new StrictValidAt(SystemClock::fromUTC()),
     new IssuedBy('https://api.my-awesome-company.com')

docs/extending-the-library.md

@@ -32,7 +32,7 @@ use Lcobucci\JWT\Configuration;
 $config = $container->get(Configuration::class);
 assert($config instanceof Configuration);
 
-$config->setBuilderFactory(
+$configuration = $configuration->withBuilderFactory(
     static function (ClaimsFormatter $formatter): Builder {
         return new MyCustomTokenBuilder($formatter);
     }
@@ -99,7 +99,7 @@ use Lcobucci\JWT\Configuration;
 $config = $container->get(Configuration::class);
 assert($config instanceof Configuration);
 
-$config->setParser(new MyCustomTokenParser());
+$configuration = $configuration->withParser(new MyCustomTokenParser());
 ```
 
 ## Signer
@@ -157,7 +157,7 @@ use Lcobucci\JWT\Configuration;
 $config = $container->get(Configuration::class);
 assert($config instanceof Configuration);
 
-$config->setValidator(new MyCustomTokenValidator());
+$configuration = $configuration->withValidator(new MyCustomTokenValidator());
 ```
 
 ## Validation constraints

docs/issuing-tokens.md

@@ -14,7 +14,7 @@ use Lcobucci\JWT\Token\Builder;
 
 require 'vendor/autoload.php';
 
-$tokenBuilder = (new Builder(new JoseEncoder(), ChainedFormatter::default()));
+$tokenBuilder = Builder::new(new JoseEncoder(), ChainedFormatter::default());
 $algorithm    = new Sha256();
 $signingKey   = InMemory::plainText(random_bytes(32));
 
@@ -58,7 +58,7 @@ use Lcobucci\JWT\Token\Builder;
 
 require 'vendor/autoload.php';
 
-$tokenBuilder = (new Builder(new JoseEncoder(), ChainedFormatter::default()));
+$tokenBuilder = Builder::new(new JoseEncoder(), ChainedFormatter::default());
 $algorithm    = new Sha256();
 $signingKey   = InMemory::plainText(random_bytes(32));
 

src/Configuration.php

@@ -24,21 +24,29 @@ final class Configuration
     private Closure $builderFactory;
 
     /** @var Constraint[] */
-    private array $validationConstraints = [];
+    private array $validationConstraints;
 
+    /** @param Closure(ClaimsFormatter $claimFormatter): Builder|null $builderFactory */
     private function __construct(
         private readonly Signer $signer,
         private readonly Key $signingKey,
         private readonly Key $verificationKey,
-        Encoder $encoder,
-        Decoder $decoder,
+        private readonly Encoder $encoder,
+        private readonly Decoder $decoder,
+        ?Parser $parser,
+        ?Validator $validator,
+        ?Closure $builderFactory,
+        Constraint ...$validationConstraints,
     ) {
-        $this->parser    = new Token\Parser($decoder);
-        $this->validator = new Validation\Validator();
+        $this->parser    = $parser ?? new Token\Parser($decoder);
+        $this->validator = $validator ?? new Validation\Validator();
 
-        $this->builderFactory = static function (ClaimsFormatter $claimFormatter) use ($encoder): Builder {
-            return new Token\Builder($encoder, $claimFormatter);
-        };
+        $this->builderFactory = $builderFactory
+            ?? static function (ClaimsFormatter $claimFormatter) use ($encoder): Builder {
+                return Token\Builder::new($encoder, $claimFormatter);
+            };
+
+        $this->validationConstraints = $validationConstraints;
     }
 
     public static function forAsymmetricSigner(
@@ -54,6 +62,9 @@ public static function forAsymmetricSigner(
             $verificationKey,
             $encoder,
             $decoder,
+            null,
+            null,
+            null,
         );
     }
 
@@ -69,15 +80,38 @@ public static function forSymmetricSigner(
             $key,
             $encoder,
             $decoder,
+            null,
+            null,
+            null,
         );
     }
 
-    /** @param callable(ClaimsFormatter): Builder $builderFactory */
+    /**
+     * @deprecated Deprecated since v5.5, please use {@see self::withBuilderFactory()} instead
+     *
+     * @param callable(ClaimsFormatter): Builder $builderFactory
+     */
     public function setBuilderFactory(callable $builderFactory): void
     {
         $this->builderFactory = $builderFactory(...);
     }
 
+    /** @param callable(ClaimsFormatter): Builder $builderFactory */
+    public function withBuilderFactory(callable $builderFactory): self
+    {
+        return new self(
+            $this->signer,
+            $this->signingKey,
+            $this->verificationKey,
+            $this->encoder,
+            $this->decoder,
+            $this->parser,
+            $this->validator,
+            $builderFactory(...),
+            ...$this->validationConstraints,
+        );
+    }
+
     public function builder(?ClaimsFormatter $claimFormatter = null): Builder
     {
         return ($this->builderFactory)($claimFormatter ?? ChainedFormatter::default());
@@ -88,11 +122,27 @@ public function parser(): Parser
         return $this->parser;
     }
 
+    /** @deprecated Deprecated since v5.5, please use {@see self::withParser()} instead */
     public function setParser(Parser $parser): void
     {
         $this->parser = $parser;
     }
 
+    public function withParser(Parser $parser): self
+    {
+        return new self(
+            $this->signer,
+            $this->signingKey,
+            $this->verificationKey,
+            $this->encoder,
+            $this->decoder,
+            $parser,
+            $this->validator,
+            $this->builderFactory,
+            ...$this->validationConstraints,
+        );
+    }
+
     public function signer(): Signer
     {
         return $this->signer;
@@ -113,19 +163,51 @@ public function validator(): Validator
         return $this->validator;
     }
 
+    /** @deprecated Deprecated since v5.5, please use {@see self::withValidator()} instead */
     public function setValidator(Validator $validator): void
     {
         $this->validator = $validator;
     }
 
+    public function withValidator(Validator $validator): self
+    {
+        return new self(
+            $this->signer,
+            $this->signingKey,
+            $this->verificationKey,
+            $this->encoder,
+            $this->decoder,
+            $this->parser,
+            $validator,
+            $this->builderFactory,
+            ...$this->validationConstraints,
+        );
+    }
+
     /** @return Constraint[] */
     public function validationConstraints(): array
     {
         return $this->validationConstraints;
     }
 
+    /** @deprecated Deprecated since v5.5, please use {@see self::withValidationConstraints()} instead */
     public function setValidationConstraints(Constraint ...$validationConstraints): void
     {
         $this->validationConstraints = $validationConstraints;
     }
+
+    public function withValidationConstraints(Constraint ...$validationConstraints): self
+    {
+        return new self(
+            $this->signer,
+            $this->signingKey,
+            $this->verificationKey,
+            $this->encoder,
+            $this->decoder,
+            $this->parser,
+            $this->validator,
+            $this->builderFactory,
+            ...$validationConstraints,
+        );
+    }
 }

src/JwtFacade.php

@@ -38,7 +38,7 @@ public function issue(
         Key $signingKey,
         Closure $customiseBuilder,
     ): UnencryptedToken {
-        $builder = new Token\Builder(new JoseEncoder(), ChainedFormatter::withUnixTimestampDates());
+        $builder = Token\Builder::new(new JoseEncoder(), ChainedFormatter::withUnixTimestampDates());
 
         $now     = $this->clock->now();
         $builder = $builder

src/Token/Builder.php

@@ -25,10 +25,16 @@ final class Builder implements BuilderInterface
     /** @var array<non-empty-string, mixed> */
     private array $claims = [];
 
+    /** @deprecated Deprecated since v5.5, please use {@see self::new()} instead */
     public function __construct(private readonly Encoder $encoder, private readonly ClaimsFormatter $claimFormatter)
     {
     }
 
+    public static function new(Encoder $encoder, ClaimsFormatter $claimFormatter): self
+    {
+        return new self($encoder, $claimFormatter);
+    }
+
     /**
      * @inheritDoc
      * @pure

tests/ConfigurationTest.php

@@ -81,8 +81,8 @@ public function builderShouldCreateABuilderWithDefaultEncoderAndClaimFactory():
         $builder = $config->builder();
 
         self::assertInstanceOf(BuilderImpl::class, $builder);
-        self::assertNotEquals(new BuilderImpl($this->encoder, ChainedFormatter::default()), $builder);
-        self::assertEquals(new BuilderImpl(new JoseEncoder(), ChainedFormatter::default()), $builder);
+        self::assertNotEquals(BuilderImpl::new($this->encoder, ChainedFormatter::default()), $builder);
+        self::assertEquals(BuilderImpl::new(new JoseEncoder(), ChainedFormatter::default()), $builder);
     }
 
     #[PHPUnit\Test]
@@ -96,18 +96,19 @@ public function builderShouldCreateABuilderWithCustomizedEncoderAndClaimFactory(
         $builder = $config->builder();
 
         self::assertInstanceOf(BuilderImpl::class, $builder);
-        self::assertEquals(new BuilderImpl($this->encoder, ChainedFormatter::default()), $builder);
+        self::assertEquals(BuilderImpl::new($this->encoder, ChainedFormatter::default()), $builder);
     }
 
     #[PHPUnit\Test]
-    public function builderShouldUseBuilderFactoryWhenThatIsConfigured(): void
+    public function builderShouldUseBuilderFactoryWhenThatIsConfiguredWithDeprecatedSet(): void
     {
         $builder = $this->createMock(Builder::class);
 
         $config = Configuration::forSymmetricSigner(
             new KeyDumpSigner(),
             InMemory::plainText('private'),
         );
+        /** @phpstan-ignore method.deprecated */
         $config->setBuilderFactory(
             static function () use ($builder): Builder {
                 return $builder;
@@ -116,6 +117,24 @@ static function () use ($builder): Builder {
         self::assertSame($builder, $config->builder());
     }
 
+    #[PHPUnit\Test]
+    public function builderShouldUseBuilderFactoryWhenThatIsConfigured(): void
+    {
+        $builder = $this->createMock(Builder::class);
+
+        $config    = Configuration::forSymmetricSigner(
+            new KeyDumpSigner(),
+            InMemory::plainText('private'),
+        );
+        $newConfig = $config->withBuilderFactory(
+            static function () use ($builder): Builder {
+                return $builder;
+            },
+        );
+        self::assertNotSame($builder, $config->builder());
+        self::assertSame($builder, $newConfig->builder());
+    }
+
     #[PHPUnit\Test]
     public function parserShouldReturnAParserWithDefaultDecoder(): void
     {
@@ -142,17 +161,31 @@ public function parserShouldReturnAParserWithCustomizedDecoder(): void
     }
 
     #[PHPUnit\Test]
-    public function parserShouldNotCreateAnInstanceIfItWasConfigured(): void
+    public function parserShouldNotCreateAnInstanceIfItWasConfiguredWithDeprecatedSet(): void
     {
         $config = Configuration::forSymmetricSigner(
             new KeyDumpSigner(),
             InMemory::plainText('private'),
         );
+        /** @phpstan-ignore method.deprecated */
         $config->setParser($this->parser);
 
         self::assertSame($this->parser, $config->parser());
     }
 
+    #[PHPUnit\Test]
+    public function parserShouldNotCreateAnInstanceIfItWasConfigured(): void
+    {
+        $config    = Configuration::forSymmetricSigner(
+            new KeyDumpSigner(),
+            InMemory::plainText('private'),
+        );
+        $newConfig = $config->withParser($this->parser);
+
+        self::assertNotSame($this->parser, $config->parser());
+        self::assertSame($this->parser, $newConfig->parser());
+    }
+
     #[PHPUnit\Test]
     public function validatorShouldReturnTheDefaultWhenItWasNotConfigured(): void
     {
@@ -166,17 +199,31 @@ public function validatorShouldReturnTheDefaultWhenItWasNotConfigured(): void
     }
 
     #[PHPUnit\Test]
-    public function validatorShouldReturnTheConfiguredValidator(): void
+    public function validatorShouldReturnTheConfiguredValidatorWithDeprecatedSet(): void
     {
         $config = Configuration::forSymmetricSigner(
             new KeyDumpSigner(),
             InMemory::plainText('private'),
         );
+        /** @phpstan-ignore method.deprecated */
         $config->setValidator($this->validator);
 
         self::assertSame($this->validator, $config->validator());
     }
 
+    #[PHPUnit\Test]
+    public function validatorShouldReturnTheConfiguredValidator(): void
+    {
+        $config    = Configuration::forSymmetricSigner(
+            new KeyDumpSigner(),
+            InMemory::plainText('private'),
+        );
+        $newConfig = $config->withValidator($this->validator);
+
+        self::assertNotSame($this->validator, $config->validator());
+        self::assertSame($this->validator, $newConfig->validator());
+    }
+
     #[PHPUnit\Test]
     public function validationConstraintsShouldReturnAnEmptyArrayWhenItWasNotConfigured(): void
     {
@@ -189,17 +236,31 @@ public function validationConstraintsShouldReturnAnEmptyArrayWhenItWasNotConfigu
     }
 
     #[PHPUnit\Test]
-    public function validationConstraintsShouldReturnTheConfiguredValidator(): void
+    public function validationConstraintsShouldReturnTheConfiguredValidatorWithDeprecatedSet(): void
     {
         $config = Configuration::forSymmetricSigner(
             new KeyDumpSigner(),
             InMemory::plainText('private'),
         );
+        /** @phpstan-ignore method.deprecated */
         $config->setValidationConstraints($this->validationConstraints);
 
         self::assertSame([$this->validationConstraints], $config->validationConstraints());
     }
 
+    #[PHPUnit\Test]
+    public function validationConstraintsShouldReturnTheConfiguredValidator(): void
+    {
+        $config    = Configuration::forSymmetricSigner(
+            new KeyDumpSigner(),
+            InMemory::plainText('private'),
+        );
+        $newConfig = $config->withValidationConstraints($this->validationConstraints);
+
+        self::assertNotSame([$this->validationConstraints], $config->validationConstraints());
+        self::assertSame([$this->validationConstraints], $newConfig->validationConstraints());
+    }
+
     #[PHPUnit\Test]
     public function customClaimFormatterCanBeUsed(): void
     {
@@ -209,6 +270,6 @@ public function customClaimFormatterCanBeUsed(): void
             InMemory::plainText('private'),
         );
 
-        self::assertEquals(new BuilderImpl(new JoseEncoder(), $formatter), $config->builder($formatter));
+        self::assertEquals(BuilderImpl::new(new JoseEncoder(), $formatter), $config->builder($formatter));
     }
 }

tests/Token/BuilderTest.php

@@ -42,7 +42,7 @@ public function initializeDependencies(): void
     #[PHPUnit\Test]
     public function withClaimShouldRaiseExceptionWhenTryingToConfigureARegisteredClaim(): void
     {
-        $builder = new Builder($this->encoder, new MicrosecondBasedDateConversion());
+        $builder = Builder::new($this->encoder, new MicrosecondBasedDateConversion());
 
         $this->expectException(RegisteredClaimGiven::class);
         $this->expectExceptionMessage(
@@ -76,7 +76,7 @@ public function getTokenShouldReturnACompletelyConfigureToken(): void
             ->with('1.2')
             ->willReturn('3');
 
-        $builder = new Builder($this->encoder, new MicrosecondBasedDateConversion());
+        $builder = Builder::new($this->encoder, new MicrosecondBasedDateConversion());
         $token   = $builder->identifiedBy('123456')
                            ->issuedBy('https://issuer.com')
                            ->issuedAt($issuedAt)
@@ -108,7 +108,7 @@ public function getTokenShouldReturnACompletelyConfigureToken(): void
     public function immutability(): void
     {
         $map           = new SplObjectStorage();
-        $builder       = new Builder($this->encoder, new MicrosecondBasedDateConversion());
+        $builder       = Builder::new($this->encoder, new MicrosecondBasedDateConversion());
         $map[$builder] = true;
         $builder       = $builder->identifiedBy('123456');
         $map[$builder] = true;