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.
This project is open source and available under the MIT License.
- PHP
^8.0 - JSON PHP extension
composer require bayfrontmedia/php-jwt
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);
- createSecret
- getHeader
- setHeader
- removeHeader
- getPayload
- setPayload
- removePayload
- aud
- exp
- iat
- iss
- jti
- nbf
- sub
- encode
- decode
- validateSignature
- validateClaims
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());
}
Description:
Returns current header array.
Parameters:
- None
Returns:
- (array)
Example:
print_r($jwt->getHeader());
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);
Description:
Remove header key, if existing.
Parameters:
$key(string)
Returns:
- (self)
Example:
$jwt->removeHeader('cty');
Description:
Returns current payload array.
Parameters:
- None
Returns:
- (array)
Example:
print_r($jwt->getPayload());
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);
Description:
Remove payload key, if existing.
Parameters:
$key(string)
Returns:
- (self)
Example:
$jwt->removePayload('user_id');
Description:
Set audience.
Parameters:
$aud(string)
Returns:
- (self)
Description:
Set expiration time.
Parameters:
$exp(int)
Returns:
- (self)
Description:
Set issued at time.
Parameters:
$iat(int)
Returns:
- (self)
Description:
Set issuer.
Parameters:
$iss(string)
Returns:
- (self)
Description:
Set JWT ID.
Parameters:
$jti(string)
Returns:
- (self)
Description:
Set not before time.
Parameters:
$nbf(int)
Returns:
- (self)
Description:
Set subject.
Parameters:
$sub(string)
Returns:
- (self)
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
]);
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());
}
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());
}
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());
}