Broken upgrade path from 3.4 to 4.0

[b-hayes]

How are we supposed to set the "sub" claim now?

I have been stuck on this for too long. There appears to be no documentation about how I am supposed to set the "sub" claim in version 4.0.*

FYI: I am using version 4.0.* specifically because I need it to run on both PHP 7.4 and 8.0 and I also need to bypass the additional token size check (my tokens are less than 2048 bytes) as this is breaking my application.
(Going from 4.0.* to 4.* is a breaking change because of this by the way).

I don't even want to look at the token size issue right now I just need to get to php8 with as minimal change as possible and this is the only thing stopping me right now.

What I've done so far:

I followed the upgrade documentation: https://lcobucci-jwt.readthedocs.io/en/stable/upgrading/#v3x-to-v4x
I am using the in-memory methods, updating injections to remove deprecated usages of sign etc

Now, ->set('sub', $id) is marked as deprecated with 0 indications of what to use instead it just said it will be removed in version 4.
The upgrade doc says nothing about this nor can I find it mentioned anywhere else.

I replaced ->set('sub', $id) with ->withClaim('sub', $id) because there is 0 indication on the deprecation tag in the code of what to use, and no mention of this in the documentation, indicating what to use instead either, and looking at the code it seems the only way forwards is to use withClaim() method.

I use this and everything appears to work fine with v3.4. I no longer have deprecated usages so it appears we are all good.

So next I upgrade to 4.0 and suddenly withClaim is no longer allowed to be used.

Lcobucci\JWT\Token\RegisteredClaimGiven: Builder#withClaim() is meant to be used for non-registered claims, check the documentation on how to set claim "sub"

I can't find any documentation about how to move forward I've been googling all day and I can't seem to find a way forward.

If there is any documentation I've missed please point me to where it tells me how to set the "sub" claim.

Ideas?

[lcobucci]

Hello, it's represented on the code sample here: https://lcobucci-jwt.readthedocs.io/en/stable/upgrading/#use-the-new-builder-api

The subject claim represents what the token is related to, hence Builder#relatedTo().

Feel free to send a PR if you have a suggestion to explain it clearer.