feat: add opt-in support for millisecond timestamps

[saifulferoz]

Some non-compliant token issuers emit the iat/nbf/exp claims in milliseconds rather than the seconds mandated by RFC 7519, which causes decode() to reject the token with a date far in the future (see #539).

Add a JWT::$useMillisecondTimestamps flag (default false). When enabled, the reference time defaults to milliseconds (microtime(true) * 1000) so claims are compared in the same unit, and the BeforeValidException date messages are rendered from the correct second value.

[cy-yun]

Thanks for putting this together! The implementation looks solid, but there is a critical edge case regarding 32-bit systems and the ExpiredException class that should be addressed in this PR.

Because millisecond timestamps (e.g., 1710000000000) exceed the 32-bit integer limit (PHP_INT_MAX is 2147483647), any code casting these timestamps to (int) will trigger an integer overflow and cause validation to fail completely on 32-bit PHP systems.

This creates a cascading issue with ExpiredException.php, which currently enforces a strict int type hint.

To ensure this new feature works reliably across all environments without causing static analysis errors or TypeErrors, I highly recommend implementing the in-line suggestions and the following:

Update ExpiredException.php to accept floats:
If a user (or the library itself) passes a float to avoid 32-bit integer overflow, ExpiredException::setTimestamp(int $timestamp) will trigger a fatal TypeError in PHP 8.1+ on 32-bit systems. Since the library requires PHP ^8.0, you can safely use union types here:

// src/ExpiredException.php
public function setTimestamp(int|float $timestamp): void
{
    $this->timestamp = $timestamp;
}

public function getTimestamp(): int|float|null
{
    return $this->timestamp;
}

[saifulferoz]

Thanks for the careful review, @cy-yun — good catch on the 32-bit overflow. Pushed a fix:

1. src/JWT.php: reference time now uses round(microtime(true) * 1000) so the millisecond value stays a float instead of overflowing PHP_INT_MAX on 32-bit PHP.
2. src/ExpiredException.php: widened $timestamp and its setTimestamp()/getTimestamp() accessors to int|float so a float timestamp doesn't trigger a TypeError on PHP 8.0+.
3. JWT::$timestamp docblock widened to int|float|null.
4. tests/JWTTest.php: the millisecond timestamps are now built with round().

[saifulferoz]

All review comments have been addressed. Could you please re-review the PR?

[cy-yun]

Great work! I'm approving this because the implementation is solid and solves the issue nicely. I've left a couple of minor, non-blocking suggestions for documentation and test coverage that you can apply if you'd like before this gets merged.

[bshaffer]

I don't know to what extent we want to support features for APIs which blatantly disregard the JWT spec. I would like to look into this and see what other libraries are doing. If other libraries are doing this in PHP, then maybe use those instead.

[bshaffer]

accidental change

[bshaffer]

I am closing this as WONT FIX. We do not want to support a feature which messes with the validation of access tokens in a non-compliant way. This could have serious security implications and result in unexpected behavior.