Merge pull request #1092 from Slamdunk/builder_new_api

Add migration API for `readonly` classes

Author: Slamdunk

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