feat: allow get headers when decoding token

[kpn13]

This PR in an enhancement to allow to get headers directly using JWT::decode() by allowing to pass a third param by reference.

#431

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[ohader]

Extracting headers would be useful, since they might contain hints to used key identifiers.
However, instead of introducing this functionality as a side-effect of JWT::decode(..), decoding the header (without verifying the signature) should be more explicit, organized in a dedicated function JWT::decodeHeader(..), e.g. like
https://github.com/TYPO3/typo3/blob/main/typo3/sysext/core/Classes/Security/JwtTrait.php#L86-L97

[kpn13]

This is interesting, thx for your feedback. But is decoding header really a side effect? Couldn't we consider decoding a token is both decoding header and payload?

[ohader]

This is interesting, thx for your feedback. But is decoding header really a side effect? Couldn't we consider decoding a token is both decoding header and payload?

Ah sorry, I was not clear on that. I'm referring to Side effect (computer science). It's about how the header is decoded. In the current patch, it's not done explicitly - e.g. decoding a JWT with an invalid signing hash would change the $headers by reference, but also thrown an exception (due to the wrong signature). Using a dedicated function JWT::decodeHeader(string $jwt) would make it that process more explicit.

[vishwarajanand]

Thanks @kpn13 for working on this. LGTM
I made some comments and doc suggestions and merged them too.