Download the PHP package dev-toolbelt/jwt-token-manager without Composer

JWT Token Manager

A framework-agnostic PHP library for encoding, decoding, and validating JSON Web Tokens (JWT) with support for RSA, HMAC, ECDSA, and EdDSA algorithms.

Built with simplicity and security in mind, this package provides an easy way to manage JWT tokens without coupling your application to any specific framework.

Features

• Framework Agnostic - Use with Laravel, Symfony, Yii, Slim, or any PHP application
• Multiple Algorithms - Support for HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512, and EdDSA
• Type-Safe Configuration - Strongly typed Algorithm enum and configuration objects
• Protected Claims - Critical claims (iss, sub, iat, exp, jti, sid) cannot be overridden for security
• Flexible Validation - Configurable required claims and audience validation
• Session Tracking - Built-in session ID (sid) and JWT ID (jti) generation using UUID v7
• Comprehensive Exceptions - Specific exceptions for expired, invalid, and malformed tokens
• Timezone Support - Type-safe timezone configuration with a comprehensive Timezone enum covering all PHP supported timezones

Requirements

• PHP 8.1 or higher
• OpenSSL extension (for RSA/ECDSA algorithms)

Installation

Install via Composer:

Quick Start

1. Generate RSA Keys (if you don't have them)

Before using the library, you'll need an RSA key pair for signing and verifying tokens. If you already have keys, skip to step 2.

Linux / macOS

Open your terminal and run:

Windows

Option 1: Using Git Bash (recommended)

If you have Git installed, open Git Bash and use the same commands as Linux/macOS:

Option 2: Using WSL (Windows Subsystem for Linux)

Option 3: Using OpenSSL for Windows

1. Download OpenSSL from slproweb.com/products/Win32OpenSSL.html
2. Install and add to PATH
3. Open Command Prompt and run the same commands

Production Keys (4096-bit)

For production environments, consider using stronger 4096-bit keys:

Security Note: Keep your private key secure and never commit it to version control. Add *.key to your .gitignore file.

2. Basic Usage

Configuration

Basic Configuration

Using Factory Methods

Supported Algorithms

Why RS256 is the default? RS256 (RSA with SHA-256) is the most widely adopted algorithm in the industry, offering an excellent balance between security and performance. It uses asymmetric keys, allowing you to share the public key for verification while keeping the private key secure. This makes it ideal for distributed systems and microservices architectures.

Timezone Configuration

The library provides a type-safe Timezone enum with all PHP supported timezones. The default timezone is UTC.

Common timezone examples:

• Americas: AMERICA_NEW_YORK, AMERICA_LOS_ANGELES, AMERICA_CHICAGO, AMERICA_SAO_PAULO
• Europe: EUROPE_LONDON, EUROPE_PARIS, EUROPE_BERLIN, EUROPE_MADRID
• Asia: ASIA_TOKYO, ASIA_SHANGHAI, ASIA_SINGAPORE, ASIA_DUBAI
• UTC: UTC

Note: JWT timestamps (iat, exp, nbf) are always Unix timestamps (seconds since Unix epoch), which are timezone-agnostic. The timezone configuration is used internally for consistent DateTimeImmutable operations and can be useful for logging, debugging, and future enhancements.

Usage

Generating Tokens

Token Claims

The generated token includes these standard claims:

Note: Claims marked as Customizable: No are automatically generated and managed by the library to ensure token integrity and security. You cannot override these values.

Decoding Tokens

Below is a comprehensive example showing all possible exceptions that can be thrown during token decoding and validation:

Refresh Tokens

While refresh tokens are not mandatory, implementing them is highly recommended for a secure authentication flow. The concept is simple: access tokens should be short-lived (minutes to hours) to minimize the impact if compromised, while refresh tokens are long-lived (days to weeks) and used solely to obtain new access tokens. This approach reduces the attack window for stolen tokens while maintaining a smooth user experience without frequent re-authentication.

Best Practice: Store refresh tokens securely (e.g., in a database with the user association) and invalidate them when the user logs out or when suspicious activity is detected.

Overriding Optional Claims

Some claims can be overridden via custom claims for flexibility:

Note: Protected claims (iss, sub, iat, exp, jti, sid) cannot be overridden for security reasons.

Framework Integration Examples

Laravel

Symfony

Slim / PHP-DI

CodeIgniter 4

CakePHP 5

Yii2

Testing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• Kilderson Sena
• All Contributors

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow PSR-12 coding standards.

Code Quality Requirements

Pull Request Guidelines

Before submitting a PR, ensure:

1. All tests pass: composer test
2. Coverage is at least 85%: composer test:coverage
3. Code style is correct: composer phpcs
4. No static analysis errors: composer phpstan

Important: Pull requests with coverage below 85% will be automatically blocked by CI.

Coverage Report

• Dashboard: Codecov
• HTML Report: GitHub Pages

License

MIT License. See LICENSE for details.

Made with ❤️ by Dev Toolbelt