README.md

adhocore/jwt

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.