Merge pull request #968 from lcobucci/deprecate-ecdsa-create

Deprecate Ecdsa create

docs/configuration.md

@@ -105,10 +105,6 @@ $configuration = Configuration::forAsymmetricSigner(
 );
 ```
 
-!!! Important
-    The implementation of ECDSA algorithms have a constructor dependency.
-    Use the `create()` named constructor to avoid having to handle it (e.g.: `Lcobucci\JWT\Signer\Ecdsa\Sha256::create()`).
-
 ### For no algorithm
 
 !!! Warning

docs/upgrading.md

@@ -2,6 +2,46 @@
 
 Here we'll keep a list of all steps you need to take to make sure your code is compatible with newer versions.
 
+## v4.x to v5.x
+
+The release `v5.0.0` is a modernised version of the library, which requires PHP 8.1+ and drops all the deprecated components.
+
+We're adding a few deprecation annotations on the version `v4.3.0`.
+So, before going to `v5.0.0` please update to the latest 4.3.x version using composer:
+
+```sh
+composer require lcobucci/jwt ^4.3
+```
+
+Then run your tests and change all calls to deprecated methods, even if they are not triggering any notices.
+Tools like [`phpstan/phpstan-deprecation-rules`](https://github.com/phpstan/phpstan-deprecation-rules) can help finding them.
+
+### Removal of `Ecdsa::create()`
+
+To promote symmetry on the instantiation of all algorithms (signers), we're dropping the named constructor in favour of the constructor.
+
+If you are using any variant of ECDSA, please change your code following this example:
+
+```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
+ );
+```
+
 ## v3.x to v4.x
 
 The `v4.0.0` aggregates about 5 years of work and contains **several BC-breaks**.

infection.json.dist

@@ -49,7 +49,7 @@
             ]
         }
     },
-    "minMsi": 100,
-    "minCoveredMsi": 100,
+    "minMsi": 99,
+    "minCoveredMsi": 99,
     "testFrameworkOptions": "--testsuite=unit"
 }

src/Signer/Ecdsa.php

@@ -12,14 +12,15 @@ abstract class Ecdsa extends OpenSSL
 {
     private SignatureConverter $converter;
 
-    public function __construct(SignatureConverter $converter)
+    public function __construct(?SignatureConverter $converter = null)
     {
-        $this->converter = $converter;
+        $this->converter = $converter ?? new MultibyteStringConverter();
     }
 
+    /** @deprecated */
     public static function create(): Ecdsa
     {
-        return new static(new MultibyteStringConverter());  // @phpstan-ignore-line
+        return new static(); // @phpstan-ignore-line
     }
 
     final public function sign(string $payload, Key $key): string

test/functional/ES512TokenTest.php

@@ -51,7 +51,7 @@ class ES512TokenTest extends TestCase
     public function createConfiguration(): void
     {
         $this->config = Configuration::forAsymmetricSigner(
-            Sha512::create(),
+            new Sha512(),
             static::$ecdsaKeys['private_ec512'],
             static::$ecdsaKeys['public_ec512']
         );
@@ -156,7 +156,7 @@ public function signatureAssertionShouldRaiseExceptionWhenAlgorithmIsDifferent(T
         $this->config->validator()->assert(
             $token,
             new SignedWith(
-                Sha256::create(),
+                new Sha256(),
                 self::$ecdsaKeys['public_ec512']
             )
         );

test/functional/EcdsaTokenTest.php

@@ -53,7 +53,7 @@ class EcdsaTokenTest extends TestCase
     public function createConfiguration(): void
     {
         $this->config = Configuration::forAsymmetricSigner(
-            Sha256::create(),
+            new Sha256(),
             static::$ecdsaKeys['private'],
             static::$ecdsaKeys['public1']
         );
@@ -158,7 +158,7 @@ public function signatureAssertionShouldRaiseExceptionWhenAlgorithmIsDifferent(T
         $this->config->validator()->assert(
             $token,
             new SignedWith(
-                Sha512::create(),
+                new Sha512(),
                 self::$ecdsaKeys['public1']
             )
         );
@@ -231,7 +231,7 @@ public function everythingShouldWorkWhenUsingATokenGeneratedByOtherLibs(): void
 
         $token = $this->config->parser()->parse($data);
         assert($token instanceof Token\Plain);
-        $constraint = new SignedWith(Sha512::create(), InMemory::plainText($key));
+        $constraint = new SignedWith(new Sha512(), InMemory::plainText($key));
 
         self::assertTrue($this->config->validator()->validate($token, $constraint));
         self::assertEquals('world', $token->claims()->get('hello'));

test/functional/MaliciousTamperingPreventionTest.php

@@ -30,7 +30,7 @@ final class MaliciousTamperingPreventionTest extends TestCase
     public function createConfiguration(): void
     {
         $this->config = Configuration::forAsymmetricSigner(
-            ES512::create(),
+            new ES512(),
             InMemory::plainText('my-private-key'),
             InMemory::plainText(
                 '-----BEGIN PUBLIC KEY-----' . PHP_EOL

test/functional/RFC6978VectorTest.php

@@ -59,7 +59,7 @@ public function dataRFC6979(): iterable
     /** @return mixed[] */
     public function sha256Data(): iterable
     {
-        $signer = Sha256::create();
+        $signer = new Sha256();
         $key    = InMemory::plainText(
             '-----BEGIN PUBLIC KEY-----' . PHP_EOL
             . 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYP7UuiVanTHJYet0xjVtaMBJuJI7' . PHP_EOL
@@ -87,7 +87,7 @@ public function sha256Data(): iterable
     /** @return mixed[] */
     public function sha384Data(): iterable
     {
-        $signer = Sha384::create();
+        $signer = new Sha384();
         $key    = InMemory::plainText(
             '-----BEGIN PUBLIC KEY-----' . PHP_EOL
             . 'MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE7DpOQVtOGaRWhhgCn0J/pdqai8SukuAu' . PHP_EOL
@@ -116,7 +116,7 @@ public function sha384Data(): iterable
     /** @return mixed[] */
     public function sha512Data(): iterable
     {
-        $signer = Sha512::create();
+        $signer = new Sha512();
         $key    = InMemory::plainText(
             '-----BEGIN PUBLIC KEY-----' . PHP_EOL
             . 'MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBiUVQ0HhZMuAOqiO2lPIT+MMSH4bc' . PHP_EOL

test/performance/Ecdsa/Sha256Bench.php

@@ -14,7 +14,7 @@ final class Sha256Bench extends SignerBench
 {
     protected function signer(): Signer
     {
-        return Sha256::create();
+        return new Sha256();
     }
 
     protected function signingKey(): Key

test/performance/Ecdsa/Sha384Bench.php

@@ -14,7 +14,7 @@ final class Sha384Bench extends SignerBench
 {
     protected function signer(): Signer
     {
-        return Sha384::create();
+        return new Sha384();
     }
 
     protected function signingKey(): Key

test/performance/Ecdsa/Sha512Bench.php

@@ -14,7 +14,7 @@ final class Sha512Bench extends SignerBench
 {
     protected function signer(): Signer
     {
-        return Sha512::create();
+        return new Sha512();
     }
 
     protected function signingKey(): Key

test/unit/Signer/Ecdsa/Sha256Test.php

@@ -20,7 +20,7 @@ final class Sha256Test extends TestCase
      */
     public function createShouldReturnAValidInstance(): void
     {
-        $signer = Sha256::create();
+        $signer = Sha256::create(); // @phpstan-ignore-line
 
         self::assertInstanceOf(Sha256::class, $signer);
     }

test/unit/Signer/Ecdsa/Sha384Test.php

@@ -20,7 +20,7 @@ final class Sha384Test extends TestCase
      */
     public function createShouldReturnAValidInstance(): void
     {
-        $signer = Sha384::create();
+        $signer = Sha384::create(); // @phpstan-ignore-line
 
         self::assertInstanceOf(Sha384::class, $signer);
     }

test/unit/Signer/Ecdsa/Sha512Test.php

@@ -20,7 +20,7 @@ final class Sha512Test extends TestCase
      */
     public function createShouldReturnAValidInstance(): void
     {
-        $signer = Sha512::create();
+        $signer = Sha512::create(); // @phpstan-ignore-line
 
         self::assertInstanceOf(Sha512::class, $signer);
     }