Add a way to get the JWT header as well as the payload from ::decode()

[pwolanin]

In some cases it would be nice to have easy access to the values in the JWT header. Especially the Key ID, but also the algorithm if more than one was allowed.

Currently, one has to extract the header and decode it again.

Options for this would include a new version of decode() (naming is hard... like decodeWithHeader() maybe) that would return both the payload and the header in an array or object. The current decode() method could stay the same for BC and return the payload part of the compound result.

Another option could be to add another, optional method parameter passed-by-reference that would be populated with the header.

[bshaffer]

I like the idea of adding an optional &$headers to the encode signature. This keeps things simple and is both a better developer experience and a more efficient way of obtaining the headers:

// public static function decode(string $jwt, $keyOrKeyArray, &$headers = null)
$payload = JWT::decode($jwt, $keys);
$payload = JWT::decode($jwt, $keys, $headers); // $headers will be the decoded header array

We could typehint the $headers variable and make it array $headers = null, since $headers will be an array, but I think it would make more sense to not typehint $headers, as whatever is passed in will be completely overwritten anyway.

[vishwarajanand]

@pwolanin thanks for raising this issue.
Kudos to @kpn13 who raised the fix.