This patch release adds support for PHP 8.

This release breaks backwards compatibility as it includes some major rework to prevent verification failures due to encoding discrepancies (for example, when one application escapes forward slashes and one does not).

If you have been using an earlier version of this library you will want to read through the short README again. However, I have also tried to summarize all the relevant changes in the list below:

• The library now requires PHP 7.2 (or higher)
• The verify() method now accepts an array of expected claim values rather than just an audience
• The library now includes built-in support for the iss claim
• The StandardJWT class has been removed (as it's easy enough to extend the abstract model)
• The static JWT::$leeway property is now public
• The getPayload() method has been removed (use the getClaims() method instead)
• All exceptions have been reworked to better match what one might actually want to try/catch for
• All exceptions now include the JWT for which the exception was thrown
• The abstract model no longer implements Iterator (as you can use the getClaims() method for that)
• You should now use the JWT::create() method rather than the constructor when creating new JWTs

This patch release fixes the constructor implementation in the StandardJWT class.

This release breaks backwards compatibility as it includes a major rework of the algorithm support, extracting the encryption and verification logic to separate methods (and traits). This rework will hopefully make it trivial to extend the library with any algorithm that may be required for your use case. Please see the included algorithm traits for details on how to implement additional algorithms.

With the algorithm rework, the JWT class has been made abstract, which means that if you were previously using the class without extending it, you must start doing so now.

This release bumps the PHP requirement to version 7.1 or higher, and with that breaks backwards compatibility as certain invalid argument values will now result in a different exception being thrown.

In addition to the changes mentioned above, this release also includes the following fixes:

• Added support for benchmarking via PHPBench
• The typ header field is now always set to "JWT"
• Revised code comments and PHPDoc blocks
• Added information about supported claims to the README

This release includes breaking changes because of a change in how the JWTs are decoded. JSON documents are no longer cast as associative arrays during the decoding phase, which means that in order to access nested claim fields you will have to access them using object property access syntax instead of associative array syntax.

// You will have to replace this
$name = $decodedJwt->data['name'];

// ...with this
$name = $decodedJwt->data->name;

There's also been a major hierarchical change to the library exceptions which may or may not break current try-catch blocks. All exceptions now inherit an interface, Lindelius\JWT\Exception\Exception, which makes it possible for you to catch every single exception thrown by the library in one go; and the Lindelius\JWT\Exception\InvalidJwtException class now extends \Exception instead of \RuntimeException.

In addition to this there are two new exception classes

• Lindelius\JWT\Exception\InvalidKeyException
• Lindelius\JWT\Exception\InvalidAudienceException

In order to improve the library further there is now also built-in support for limiting the JWTs to specific audiences (the "aud" claim). You can read more about this in the documentation (aka the README file).

Apart from the changes mentioned above, there has also been some various, less noteworthy improvements to both the code and to the documentation.

This release includes breaking changes as the$key parameter has been removed from the JWT::decode() method, leaving it with only one parameter ($jwt). The change was made due to the JWT::decode() and JWT::verify() methods behaving differently when presented with a null key.

Therefore, starting with this release, the proper—and only—way to decode and verify a JWT is the following:

$jwt = JWT::decode($rawJwt);
$jwt->verify($key);

This release also includes new unit tests and some minor improvements.

This release includes breaking changes as most methods have been reworked in order to support use cases where the payload of the JWT needs to be accessed before the decode key is known (for example, in cases where the encode and decode keys are user specific).

What this means in terms of API changes is the following:

• The previously required $key parameter in the constructor has been removed, and an optional $signature parameter has been added as a third (and last) parameter,
• The JWT::encode() method now requires a $key parameter,
• The $key parameter in the JWT::decode() method is now optional, and the $verify parameter has been removed, and
• The JWT::verify() method now requires a $key parameter instead of the $rawSignature parameter.

Also worth noting is that the library now assumes that the exp, iat, and nbf, claims are numeric if they are included in the JWT (the is_numeric() checks have been removed).

This release includes breaking changes as there have been some modifications to the exception classes used within the library.

• InvalidException is now known as InvalidJwtException
• ExpiredException is now known as ExpiredJwtException
• \InvalidArgumentException has been changed to Lindelius\JWT\Exception\InvalidArgumentException
• \DomainException has been changed to Lindelius\JWT\Exception\DomainException

Also included in this release is

• Support for the RS384 and RS512 algorithms,
• Additional checks for when decoding JWTs,
• Separate unit tests for all the supported algorithms,
• Minor PHPDoc fixes, and
• Minor code formatting fixes.

The JWT model now overrides the magic __isset() and __unset() methods, which now makes it possible to check whether claims that are accessed via property overloading have been set.

isset($jwt->claimName); // This will no longer always return false

This release also includes a full test suite (using PHPUnit) to make sure the JWT model is working properly.