README

此软件包用于生成JWS令牌。

初始化类

use Spoova\JwsToken\JwsToken;

$jws = new JwsToken;

修改用于生成令牌的头部

由于预期将创建一个JWS令牌，因此定义令牌头部至关重要。这可以通过使用set()方法完成。头部通常包含一个头部类型和一个指定的算法，如下所示

$jws->set($type, $algo);

$type - 提供的数据类型可以是JWS或JWT。
$algo - (可选) [HS256|HS384|HS512|RS256]中可接受的任何散列算法

以下是一个设置任何头部的示例

$jws->set('JWS', 'HS256');

$type - 提供的数据类型可以是JWS或JWT。
$algo - (可选) 可接受的任何散列算法。

如果未定义set()方法，则假定上述参数是默认值。

仅修改用于生成令牌的算法

在不需要定义整个头部的情况下，我们可以使用algo()方法仅修改算法而无需设置完整的头部。在这种情况下，仅修改默认算法。例如

$jws = new JwsToken;

$jws->algo('HS384'); //modify algorithm only

设置有效负载

JwsToken有效负载通常是包含预期要散列的令牌的相关信息的指定数据键的数组数据。JwsToken的payload()接受以下特定键的数组

sub - 令牌的主题
iss - 令牌的发行者
aud - 令牌的所有者
nbf - 生成令牌变得活跃的时间
exp - 生成令牌到期的时间
data - 预期要存储的其他信息

提供的有效负载的data键不应包含任何机密数据。以下是如何设置有效负载的示例

$jws = new JwsToken;

$payload = [

    'sub' => 'Token for accessing a class',
    'iss' => 'Issuer name or id'
    'aud' => 'Owner name or id'
    'iat' => time(),
    'nbf' => time() + 120, //token becomes active after 2 minutes of generation
    'exp' => time() + 240, //token becomes expired after 4 minutes of generation
    'data' => [
        'age' => 'user age',
        'gender' => 'male',
    ]
]

$jws->payload($payload);

In the example above,

sub 定义令牌的标题或主题（可选）
iss 定义令牌发行者的id
aud 定义令牌所有者的id（可选）
iat 定义令牌生成的时间（可选）
nbf 定义令牌活跃的时间（可选）
exp 定义令牌到期的时间（可选）
data 不应包含任何敏感信息。

通常，整个有效负载不应包含任何敏感信息，因为它只是被令牌化，但仍然对任何人可见。还应注意，并非所有键都是必需的。如果没有定义exp键，我们也可以通过以下方法设置它：expires()，如下所示
```
$jws->payload($payload)->expires(time() + 240); //expires after  4 minutes of generation
```
没有nbf的有效负载将在生成时立即变得活跃，而没有exp的有效负载将永远不会到期。此外，有效负载还可以包含除上述特定保留键之外的其他任何自定义键。

获取散列令牌

在可以获取令牌之前，必须使用sign()方法使用秘密密钥对其进行签名，然后使用token()方法获取令牌。

以下是如何签名令牌的示例，假设已定义有效负载

$jws->sign('secret_key', 'sha256');

当对密钥进行签名时，预期将定义一个密钥。默认情况下，sign() 方法使用加密散列算法 sha256，但是可以通过向 sign() 方法提供第二个参数来重定义，该参数应为有效的散列算法。一旦对有效负载进行签名，我们就可以继续获取生成的令牌。

$token = $jws->token(); //return the generated token

验证生成的令牌

一旦生成令牌，可以使用专门设计的方法进行验证

设置用于验证的令牌

$jws->token($token); //set a token for validation

为了测试令牌是否有效，使用 isValid() 方法。这通常包含在生成令牌时使用的密钥和散列算法。

测试令牌是否有效的示例

$jws->token($token);  

if($jws->isValid('secret_key', 'sha256')){

   echo "token is valid";

} else { 

  echo $jws->error();

}

通常，当令牌无效时，可能是以下三个原因之一，这也是我们需要知道为什么令牌无效的原因，我们使用 error() 方法来了解原因。令牌可能无效的原因如下

令牌格式错误
令牌尚未激活
令牌已过期。

我们可以通过向 expired() 方法提供密钥和散列算法来检测令牌是否已过期。

$jws->token($token); 

if($jws->expired('secret_key', 'sha256')){

    echo "token has expired";

} else if(!$jws->error()) { 

    echo 'token is has not expired';

}

我们还可以通过向 pending() 方法提供密钥和散列算法来检测令牌是否尚未激活。

$jws->token($token); 

if($jws->pending('secret_key', 'sha256')){

    echo "token has expired";

} else if(!$jws->error()) { 

    echo 'token is has not expired';

}

请注意，如果有效负载有效但未激活，则 pending() 方法将返回 false。如果尚未进行测试，则 pending() 方法将返回空字符串。但是，只有当有效负载有效且令牌尚未激活或激活时，才会返回 true。

解密令牌

有效的令牌可以使用 decrypt() 方法进行解密。这里的解密并不意味着负载对用户不可见，而只是用于从有效的令牌中检索负载。不可能正确检测提供的任何令牌是否有效，但是如果令牌有效，则我们肯定知道我们可以使用 decrypt() 方法从中获取有效的负载。此方法将第一个参数作为要解密的令牌，第二个参数是用于生成令牌的密钥。最后，第三个参数是用于散列令牌的哈希算法。

> Decrypting a valid token sample

$payload = $jws->decrypt($token, 'secret_key' 'sha256');

var_dump($payload);

在检查令牌的有效性时，可以使用解密方法立即检索有效的负载

if($jws->token($token)->isValid('secret_key' 'sha256')) {

  $payload = $jws->decrypt();

  var_dump($payload);
 
}else {

  echo $jws->error();

}

spoova / jwstoken

维护者

详细信息