byjg / jwt-wrapper

6.1.0 2026-02-21 23:48 UTC

Requires

• php: >=8.3 <8.6
• ext-openssl: *
• firebase/php-jwt: ^7

Requires (Dev)

• phpunit/phpunit: ^10.5|^11.5
• vimeo/psalm: ^5.9|^6.13

MIT

Published on Packagist.org on 2026-02-21 23:51 UTC

README

sidebar_key	jwt-wrapper
tags	php cryptography authentication

JWT Wrapper

A simple and flexible wrapper around the Firebase JWT library that makes JWT token handling easy and intuitive in PHP applications.

Features

• Simple API: Create and validate JWT tokens with minimal code
• Flexible Signing: Support for both HMAC (shared secret) and RSA/ECDSA (public/private key) methods
• Automatic Claims: Built-in handling of standard JWT claims (iat, exp, nbf)
• HTTP Integration: Helper methods for extracting tokens from HTTP headers
• Key Management: Intuitive interfaces for different key types

Installation

composer require "byjg/jwt-wrapper"

Quick Example

The HMAC secret must be base64 encoded and decode to at least 64 bytes for the default HS512 algorithm (32 for HS256, 48 for HS384); a shorter key fails with Provided key is too short. See Key Types.

// Create a JWT token using HMAC
$server = "example.com";
// Base64 of at least 64 random bytes, created once with JwtWrapper::generateSecret(64)
$secret = new \ByJG\JwtWrapper\JwtHashHmacSecret(getenv("JWT_SECRET"));
$jwtWrapper = new \ByJG\JwtWrapper\JwtWrapper($server, $secret);

// Add custom data and set expiration
$token = $jwtWrapper->generateToken(
    $jwtWrapper->createJwtData(["userId" => 123], 3600)
);

// Validate and extract data
try {
    $jwtData = $jwtWrapper->extractData($token);
    $userId = $jwtData->data->userId;
} catch (\UnexpectedValueException | \ByJG\JwtWrapper\JwtWrapperException $e) {
    // Handle invalid, expired or tampered token
}

Documentation

Detailed documentation:

Document	Description
Overview	Introduction and core concepts
Key Types	HMAC and OpenSSL key configuration
Creating Tokens	Token generation and customization
Validating Tokens	Token validation and data extraction
API Reference	Complete class and method documentation

Examples

The library includes complete examples in the example directory showing:

• Token creation with login.php
• Token validation with api.php
• Client-side usage with client.html

sequenceDiagram
    participant LOCAL
    participant CLIENT
    participant SERVER
    participant PRIVATE_RESOURCE
    LOCAL->>CLIENT: Retrieve Local Token
    CLIENT->>SERVER: Pass Token
    SERVER->>PRIVATE_RESOURCE: Validate Token
    PRIVATE_RESOURCE->>CLIENT: Return Result if token is valid
    CLIENT->>LOCAL: Store Token

Loading

Running Tests

vendor/bin/phpunit

Open source ByJG