adhocore / jwt
Ultra lightweight JSON web token (JWT) library for PHP5.5+.
Fund package maintenance!
adhocore
paypal.me/ji10
Installs: 1 035 885
Dependents: 17
Suggesters: 0
Security: 0
Stars: 294
Watchers: 10
Forks: 21
Open Issues: 3
Requires
- php: ^7.0 || ^8.0
Requires (Dev)
- phpunit/phpunit: ^6.5 || ^7.5
README
If you are new to JWT or want to refresh your familiarity with it, please check jwt.io
- Lightweight JSON Web Token (JWT) library for PHP7, PHP8 and beyond.
- Zero dependency (no vendor bloat).
- If you still use PHP5.6, use version 0.1.2
Installation
# PHP7.x, PHP8.x composer require adhocore/jwt # PHP5.6 (deprecated) composer require adhocore/jwt:0.1.2 # For PHP5.4-5.5 (deprecated), use version 0.1.2 with a polyfill for https://php.net/hash_equals
Features
- Six algorithms supported:
'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512'
kid
support.- Leeway support 0-120 seconds.
- Timestamp spoofing for tests.
- Passphrase support for
RS*
algos.
Usage
use Ahc\Jwt\JWT; // Instantiate with key, algo, maxAge and leeway. $jwt = new JWT('secret', 'HS256', 3600, 10);
Only the key is required. Defaults will be used for the rest:
$jwt = new JWT('secret'); // algo = HS256, maxAge = 3600, leeway = 0
For
RS*
algo, the key should be either a resource like below:
$key = openssl_pkey_new([ 'digest_alg' => 'sha256', 'private_key_bits' => 1024, 'private_key_type' => OPENSSL_KEYTYPE_RSA, ]);
OR, a string with full path to the RSA private key like below:
$key = '/path/to/rsa.key'; // Then, instantiate JWT with this key and RS* as algo: $jwt = new JWT($key, 'RS384');
Pro You dont need to specify pub key path, that is deduced from priv key.
Generate JWT token from payload array:
$token = $jwt->encode([ 'uid' => 1, 'aud' => 'http://site.com', 'scopes' => ['user'], 'iss' => 'http://api.mysite.com', ]);
Retrieve the payload array:
$payload = $jwt->decode($token);
Oneliner:
$token = (new JWT('topSecret', 'HS512', 1800))->encode(['uid' => 1, 'scopes' => ['user']]); $payload = (new JWT('topSecret', 'HS512', 1800))->decode($token);
Pro
Can pass extra headers into encode() with second parameter:
$token = $jwt->encode($payload, ['hdr' => 'hdr_value']);
Test mocking
Spoof time() for testing token expiry:
$jwt->setTestTimestamp(time() + 10000); // Throws Exception. $jwt->parse($token);
Call again without parameter to stop spoofing time():
$jwt->setTestTimestamp();
Examples with kid
$jwt = new JWT(['key1' => 'secret1', 'key2' => 'secret2']); // Use key2 $token = $jwt->encode(['a' => 1, 'exp' => time() + 1000], ['kid' => 'key2']); $payload = $jwt->decode($token); $token = $jwt->encode(['a' => 1, 'exp' => time() + 1000], ['kid' => 'key3']); // -> Exception with message Unknown key ID key3
Stabillity
The library is now marked at version 1.*.*
as being stable in functionality and API.
Integration
Phalcon
Check adhocore/phalcon-ext.
Consideration
Be aware of some security related considerations as outlined here which can be valid for any JWT implementations.