feat: add payload to jwt exception (#521)

Author: bshaffer

src/BeforeValidException.php

@@ -2,6 +2,17 @@
 
 namespace Firebase\JWT;
 
-class BeforeValidException extends \UnexpectedValueException
+class BeforeValidException extends \UnexpectedValueException implements JWTExceptionWithPayloadInterface
 {
+    private object $payload;
+
+    public function setPayload(object $payload): void
+    {
+        $this->payload = $payload;
+    }
+
+    public function getPayload(): object
+    {
+        return $this->payload;
+    }
 }

src/ExpiredException.php

@@ -2,6 +2,17 @@
 
 namespace Firebase\JWT;
 
-class ExpiredException extends \UnexpectedValueException
+class ExpiredException extends \UnexpectedValueException implements JWTExceptionWithPayloadInterface
 {
+    private object $payload;
+
+    public function setPayload(object $payload): void
+    {
+        $this->payload = $payload;
+    }
+
+    public function getPayload(): object
+    {
+        return $this->payload;
+    }
 }

src/JWT.php

@@ -153,23 +153,29 @@ public static function decode(
         // Check the nbf if it is defined. This is the time that the
         // token can actually be used. If it's not yet that time, abort.
         if (isset($payload->nbf) && floor($payload->nbf) > ($timestamp + static::$leeway)) {
-            throw new BeforeValidException(
+            $ex = new BeforeValidException(
                 'Cannot handle token with nbf prior to ' . \date(DateTime::ISO8601, (int) $payload->nbf)
             );
+            $ex->setPayload($payload);
+            throw $ex;
         }
 
         // Check that this token has been created before 'now'. This prevents
         // using tokens that have been created for later use (and haven't
         // correctly used the nbf claim).
         if (!isset($payload->nbf) && isset($payload->iat) && floor($payload->iat) > ($timestamp + static::$leeway)) {
-            throw new BeforeValidException(
+            $ex = new BeforeValidException(
                 'Cannot handle token with iat prior to ' . \date(DateTime::ISO8601, (int) $payload->iat)
             );
+            $ex->setPayload($payload);
+            throw $ex;
         }
 
         // Check if this token has expired.
         if (isset($payload->exp) && ($timestamp - static::$leeway) >= $payload->exp) {
-            throw new ExpiredException('Expired token');
+            $ex = new ExpiredException('Expired token');
+            $ex->setPayload($payload);
+            throw $ex;
         }
 
         return $payload;

src/JWTExceptionWithPayloadInterface.php

@@ -0,0 +1,20 @@
+<?php
+namespace Firebase\JWT;
+
+interface JWTExceptionWithPayloadInterface
+{
+    /**
+     * Get the payload that caused this exception.
+     *
+     * @return object
+     */
+    public function getPayload(): object;
+
+    /**
+     * Get the payload that caused this exception.
+     *
+     * @param object $payload
+     * @return void
+     */
+    public function setPayload(object $payload): void;
+}

tests/JWTTest.php

@@ -107,6 +107,40 @@ public function testExpiredTokenWithLeeway()
         $this->assertSame($decoded->message, 'abc');
     }
 
+    public function testExpiredExceptionPayload()
+    {
+        $this->expectException(ExpiredException::class);
+        $payload = [
+            'message' => 'abc',
+            'exp' => time() - 100, // time in the past
+        ];
+        $encoded = JWT::encode($payload, 'my_key', 'HS256');
+        try {
+            JWT::decode($encoded, new Key('my_key', 'HS256'));
+        } catch (ExpiredException $e) {
+            $exceptionPayload = (array) $e->getPayload();
+            $this->assertEquals($exceptionPayload, $payload);
+            throw $e;
+        }
+    }
+
+    public function testBeforeValidExceptionPayload()
+    {
+        $this->expectException(BeforeValidException::class);
+        $payload = [
+            'message' => 'abc',
+            'iat' => time() + 100, // time in the future
+        ];
+        $encoded = JWT::encode($payload, 'my_key', 'HS256');
+        try {
+            JWT::decode($encoded, new Key('my_key', 'HS256'));
+        } catch (BeforeValidException $e) {
+            $exceptionPayload = (array) $e->getPayload();
+            $this->assertEquals($exceptionPayload, $payload);
+            throw $e;
+        }
+    }
+
     public function testValidTokenWithNbf()
     {
         $payload = [