bayfrontmedia / php-jwt
A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519.
Requires
- php: ^8.0
- ext-json: *
README
A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519.
Currently, the only supported algorithm is "HS256". Support for additional algorithms is planned for future versions.
License
This project is open source and available under the MIT License.
Author
Requirements
- PHP
^8.0 - JSON PHP extension
Installation
composer require bayfrontmedia/php-jwt
Usage
A private, reproducible secret must be passed to the constructor. The same secret used to encode the JWT must also be used when decoding in order to verify the signature.
A cryptographically secure secret can be generated using the static createSecret() method, if needed.
use Bayfront\JWT\Jwt;
$secret = Jwt::createSecret(); // Be sure to save the secret to be used to decode the JWT
$jwt = new Jwt($secret);
Public methods
- createSecret
- getHeader
- setHeader
- removeHeader
- getPayload
- setPayload
- removePayload
- aud
- exp
- iat
- iss
- jti
- nbf
- sub
- encode
- decode
- validateSignature
- validateClaims
createSecret
Description:
Create a cryptographically secure secret of random bytes.
NOTE: Secrets are meant to be stored, as the same secret used to encode a JWT must be used to decode it.
Parameters:
$characters = 32(int): Number of characters
Returns:
- (string)
Throws:
Exception
Example:
use Bayfront\JWT\Jwt;
try {
$secret = Jwt::createSecret();
} catch (Exception $e) {
die($e->getMessage());
}
getHeader
Description:
Returns current header array.
Parameters:
- None
Returns:
- (array)
Example:
print_r($jwt->getHeader());
setHeader
Description:
Set custom value(s) to the current header array.
Parameters:
$header(array): Key/value pairs to set to the header array
Returns:
- (self)
Example:
$header = [
'cty' => 'custom-content-type;v=1'
];
$jwt->setHeader($header);
removeHeader
Description:
Remove header key, if existing.
Parameters:
$key(string)
Returns:
- (self)
Example:
$jwt->removeHeader('cty');
getPayload
Description:
Returns current payload array.
Parameters:
- None
Returns:
- (array)
Example:
print_r($jwt->getPayload());
setPayload
Description:
Set custom value(s) to the current payload array.
Parameters:
$payload(array): Key/value pairs to set to the payload array
Returns:
- (self)
Example:
$payload = [
'user_id' => 10
];
$jwt->setPayload($payload);
removePayload
Description:
Remove payload key, if existing.
Parameters:
$key(string)
Returns:
- (self)
Example:
$jwt->removePayload('user_id');
aud
Description:
Set audience.
Parameters:
$aud(string)
Returns:
- (self)
exp
Description:
Set expiration time.
Parameters:
$exp(int)
Returns:
- (self)
iat
Description:
Set issued at time.
Parameters:
$iat(int)
Returns:
- (self)
iss
Description:
Set issuer.
Parameters:
$iss(string)
Returns:
- (self)
jti
Description:
Set JWT ID.
Parameters:
$jti(string)
Returns:
- (self)
nbf
Description:
Set not before time.
Parameters:
$nbf(int)
Returns:
- (self)
sub
Description:
Set subject.
Parameters:
$sub(string)
Returns:
- (self)
encode
Description:
Encode and return a signed JWT.
Parameters:
$payload = [](array)
Returns:
- (string)
Example:
$now = time();
$token = $jwt->iss('API key whose secret signs the token')
->iat($now)
->nbf($now)
->exp($now + 86400) // 24 hours
->encode([
'user_id' => 10
]);
decode
Description:
Decode a JWT.
This method validates the token structure as three segments separated by dots.
The returned array will contain the keys header, payload and signature.
If $validate = true, the signature and claims will also be validated.
Parameters:
$jwt(string): The JWT itself or the entireAuthorizationheader can be used$validate = true(bool): Validate signature and claims
Returns:
- (array)
Throws:
Bayfront\JWT\TokenException
Example:
try {
$decoded = $jwt->decode('encoded.jwt');
} catch (TokenException $e) {
die($e->getMessage());
}
validateSignature
Description:
Validate signature.
Parameters:
$jwt(string): The JWT itself or the entireAuthorizationheader can be used
Returns:
- (self)
Throws:
Bayfront\JWT\TokenException
Example:
try {
$decoded = $jwt->validateSignature('encoded.jwt')->decode('encoded.jwt', false);
} catch (TokenException $e) {
die($e->getMessage());
}
validateClaims
Description:
Validate the claims "iat", "nbf" and "exp", if existing.
Parameters:
$jwt(string): The JWT itself or the entireAuthorizationheader can be used
Returns:
- (self)
Throws:
Bayfront\JWT\TokenException
Example:
try {
$decoded = $jwt->validateClaims('encoded.jwt')->decode('encoded.jwt', false);
} catch (TokenException $e) {
die($e->getMessage());
}