[NFR]: Add a method for creating custom claims to JWT token

[sinbadxiii]

When generating a token in a JWT Phalcon, there is no way to add a custom claim, for example ["email" => "example@gmail.com, "username" => "phalconist" ].

Phalcon Builder https://github.com/phalcon/cphalcon/blob/master/phalcon/Security/JWT/Builder.zep#L406 has a protected setClaim method, which other reserved methods use, such as setIssuer(), setSubject etc.

I propose to introduce a public setCustom method:

 public function setCustom(string! name, var value) -> <Builder>
    {
        return this->setClaim(name, value);
    }

which will allow you to create custom claims in the payload of the token, ex.:

$signer  = new Hmac();
$builder = new Builder($signer);

$now        = new DateTimeImmutable();
$issued     = $now->getTimestamp();
$notBefore  = $now->modify('-1 minute')->getTimestamp();
$expires    = $now->modify('+1 day')->getTimestamp();
$passphrase = 'QcMpZ&b&mo3TPsPk668J6QH8JA$&U&m2';

$builder
    ->setAudience('https://target.phalcon.io')  // aud
    ->setContentType('application/json')        // cty - header
    ->setExpirationTime($expires)               // exp 
    ->setId('abcd123456789')                    // JTI id 
    ->setIssuedAt($issued)                      // iat 
    ->setIssuer('https://phalcon.io')           // iss 
    ->setNotBefore($notBefore)                  // nbf
    ->setSubject('my subject for this claim')   // sub
    ->setPassphrase($passphrase)                // password 
    ->setCustom("email", "example@gmail.com")                // custim claim email 
    ->setCustom("username", "phalconist")                // custim claim username 
;

$tokenObject = $builder->getToken();
echo $tokenObject->getToken();

//eyJ.....

Possible method names:

• setCustomClaim()
• withClaim()
• addClaim()
• attachClaim()

There is something , this is to make the protected setClaim method public, and then you can simply use it:

...
    ->setSubject('my subject for this claim')   // sub
    ->setPassphrase($passphrase)                // password 
    ->setClaim("email", "example@gmail.com")                // claim email 
    ->setClaim("username", "phalconist")                // claim username 
;

but there may be reasons not to do so :)

[Jeckerson]

/cc @niden

[niden]

Implemented in #15657