Merge pull request #1141 from Slamdunk/no_discard

Add `#[\NoDiscard]` attribute

Author: lcobucci

.composer-require-checker.config.json

@@ -0,0 +1,13 @@
+{
+  "symbol-whitelist" : [
+    "NoDiscard"
+  ],
+  "php-core-extensions" : [
+    "Core",
+    "date",
+    "json",
+    "hash",
+    "SPL",
+    "standard"
+  ]
+}

.gitattributes

@@ -3,6 +3,7 @@
 /.gitattributes                           export-ignore
 /.github                                  export-ignore
 /.gitignore                               export-ignore
+/.composer-require-checker.config.json    export-ignore
 /*.yml                                    export-ignore
 /CONTRIBUTING.md                          export-ignore
 /*.dist                                   export-ignore

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

@@ -43,7 +43,7 @@ jobs:
         run: "composer-normalize --dry-run"
 
       - name: "Check composer.json explicit dependencies"
-        run: "composer-require-checker check"
+        run: "composer-require-checker check --config-file=.composer-require-checker.config.json"
 
 #      - name: "Check composer.json unused dependencies"
 #        run: "composer-unused"

src/Builder.php

@@ -10,6 +10,7 @@
 use Lcobucci\JWT\Signer\InvalidKeyProvided;
 use Lcobucci\JWT\Signer\Key;
 use Lcobucci\JWT\Token\RegisteredClaimGiven;
+use NoDiscard;
 
 /** @immutable */
 interface Builder
@@ -19,49 +20,57 @@ interface Builder
      *
      * @param non-empty-string ...$audiences
      */
+    #[NoDiscard]
     public function permittedFor(string ...$audiences): Builder;
 
     /**
      * Configures the expiration time
      */
+    #[NoDiscard]
     public function expiresAt(DateTimeImmutable $expiration): Builder;
 
     /**
      * Configures the token id
      *
      * @param non-empty-string $id
      */
+    #[NoDiscard]
     public function identifiedBy(string $id): Builder;
 
     /**
      * Configures the time that the token was issued
      */
+    #[NoDiscard]
     public function issuedAt(DateTimeImmutable $issuedAt): Builder;
 
     /**
      * Configures the issuer
      *
      * @param non-empty-string $issuer
      */
+    #[NoDiscard]
     public function issuedBy(string $issuer): Builder;
 
     /**
      * Configures the time before which the token cannot be accepted
      */
+    #[NoDiscard]
     public function canOnlyBeUsedAfter(DateTimeImmutable $notBefore): Builder;
 
     /**
      * Configures the subject
      *
      * @param non-empty-string $subject
      */
+    #[NoDiscard]
     public function relatedTo(string $subject): Builder;
 
     /**
      * Configures a header item
      *
      * @param non-empty-string $name
      */
+    #[NoDiscard]
     public function withHeader(string $name, mixed $value): Builder;
 
     /**
@@ -71,6 +80,7 @@ public function withHeader(string $name, mixed $value): Builder;
      *
      * @throws RegisteredClaimGiven When trying to set a registered claim.
      */
+    #[NoDiscard]
     public function withClaim(string $name, mixed $value): Builder;
 
     /**
@@ -81,5 +91,6 @@ public function withClaim(string $name, mixed $value): Builder;
      * @throws InvalidKeyProvided  When issue key is invalid/incompatible.
      * @throws ConversionFailed    When signature could not be converted.
      */
+    #[NoDiscard]
     public function getToken(Signer $signer, Key $key): UnencryptedToken;
 }

src/ClaimsFormatter.php

@@ -3,12 +3,15 @@
 
 namespace Lcobucci\JWT;
 
+use NoDiscard;
+
 interface ClaimsFormatter
 {
     /**
      * @param array<non-empty-string, mixed> $claims
      *
      * @return array<non-empty-string, mixed>
      */
+    #[NoDiscard]
     public function formatClaims(array $claims): array;
 }

src/Configuration.php

@@ -8,6 +8,7 @@
 use Lcobucci\JWT\Encoding\JoseEncoder;
 use Lcobucci\JWT\Signer\Key;
 use Lcobucci\JWT\Validation\Constraint;
+use NoDiscard;
 
 /**
  * Configuration container for the JWT Builder and Parser
@@ -49,6 +50,7 @@ private function __construct(
         $this->validationConstraints = $validationConstraints;
     }
 
+    #[NoDiscard]
     public static function forAsymmetricSigner(
         Signer $signer,
         Key $signingKey,
@@ -68,6 +70,7 @@ public static function forAsymmetricSigner(
         );
     }
 
+    #[NoDiscard]
     public static function forSymmetricSigner(
         Signer $signer,
         Key $key,
@@ -87,6 +90,7 @@ public static function forSymmetricSigner(
     }
 
     /** @param callable(ClaimsFormatter): Builder $builderFactory */
+    #[NoDiscard]
     public function withBuilderFactory(callable $builderFactory): self
     {
         return new self(
@@ -112,6 +116,7 @@ public function parser(): Parser
         return $this->parser;
     }
 
+    #[NoDiscard]
     public function withParser(Parser $parser): self
     {
         return new self(
@@ -147,6 +152,7 @@ public function validator(): Validator
         return $this->validator;
     }
 
+    #[NoDiscard]
     public function withValidator(Validator $validator): self
     {
         return new self(
@@ -168,6 +174,7 @@ public function validationConstraints(): array
         return $this->validationConstraints;
     }
 
+    #[NoDiscard]
     public function withValidationConstraints(Constraint ...$validationConstraints): self
     {
         return new self(

src/Decoder.php

@@ -4,6 +4,7 @@
 namespace Lcobucci\JWT;
 
 use Lcobucci\JWT\Encoding\CannotDecodeContent;
+use NoDiscard;
 
 interface Decoder
 {
@@ -14,6 +15,7 @@ interface Decoder
      *
      * @throws CannotDecodeContent When something goes wrong while decoding.
      */
+    #[NoDiscard]
     public function jsonDecode(string $json): mixed;
 
     /**
@@ -25,5 +27,6 @@ public function jsonDecode(string $json): mixed;
      *
      * @throws CannotDecodeContent When something goes wrong while decoding.
      */
+    #[NoDiscard]
     public function base64UrlDecode(string $data): string;
 }

src/Encoder.php

@@ -4,6 +4,7 @@
 namespace Lcobucci\JWT;
 
 use Lcobucci\JWT\Encoding\CannotEncodeContent;
+use NoDiscard;
 
 interface Encoder
 {
@@ -14,6 +15,7 @@ interface Encoder
      *
      * @throws CannotEncodeContent When something goes wrong while encoding.
      */
+    #[NoDiscard]
     public function jsonEncode(mixed $data): string;
 
     /**
@@ -23,5 +25,6 @@ public function jsonEncode(mixed $data): string;
      *
      * @return ($data is non-empty-string ? non-empty-string : string)
      */
+    #[NoDiscard]
     public function base64UrlEncode(string $data): string;
 }

src/JwtFacade.php

@@ -12,6 +12,7 @@
 use Lcobucci\JWT\Validation\SignedWith;
 use Lcobucci\JWT\Validation\ValidAt;
 use Lcobucci\JWT\Validation\Validator;
+use NoDiscard;
 use Psr\Clock\ClockInterface as Clock;
 
 use function assert;
@@ -33,6 +34,7 @@ public function now(): DateTimeImmutable
     }
 
     /** @param Closure(Builder, DateTimeImmutable):Builder $customiseBuilder */
+    #[NoDiscard]
     public function issue(
         Signer $signer,
         Key $signingKey,
@@ -50,6 +52,7 @@ public function issue(
     }
 
     /** @param non-empty-string $jwt */
+    #[NoDiscard]
     public function parse(
         string $jwt,
         SignedWith $signedWith,

src/Parser.php

@@ -6,6 +6,7 @@
 use Lcobucci\JWT\Encoding\CannotDecodeContent;
 use Lcobucci\JWT\Token\InvalidTokenStructure;
 use Lcobucci\JWT\Token\UnsupportedHeaderFound;
+use NoDiscard;
 
 interface Parser
 {
@@ -18,5 +19,6 @@ interface Parser
      * @throws InvalidTokenStructure    When token string structure is invalid.
      * @throws UnsupportedHeaderFound   When parsed token has an unsupported header.
      */
+    #[NoDiscard]
     public function parse(string $jwt): Token;
 }