zotenme/hyperf-jwt-auth

JWT Authentication package for Hyperf framework

v1.0.8 2025-08-13 15:25 UTC

Requires

• php: >=8.3
• hyperf/cache: ^3.1
• lcobucci/jwt: ^5.0
• ramsey/uuid: ^4.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• mockery/mockery: ^1.6
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^12.0

MIT

• Zotenme

• Authentication
• auth
• token
• jwt
• hyperf

README

A comprehensive JWT (JSON Web Token) authentication package for the Hyperf framework with advanced features like token rotation, blacklisting, SSO mode, and multiple algorithm support.

Features

• 🔐 Multiple Algorithm Support - HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512
• 🔄 Token Rotation - Automatic refresh token rotation for enhanced security
• 🚫 Token Blacklisting - Revoke tokens before expiration with grace period support
• 👤 Single Sign-On (SSO) - Limit users to one active session
• ⚡ High Performance - Built-in caching with Hyperf cache system
• 🛡️ Type Safe - Full PHP 8.3+ type declarations with PHPStan level 8

Quick Start

Installation

composer require zotenme/hyperf-jwt-auth
php bin/hyperf.php vendor:publish zotenme/hyperf-jwt-auth

Basic Usage

<?php

use Zotenme\JwtAuth\Contract\JwtManagerInterface;

class AuthController
{
    public function __construct(
        private JwtManagerInterface $jwtManager
    ) {}

    public function login(LoginRequest $request): JsonResponse
    {
        $userId = $this->validateCredentials($request);
        
        $tokenPair = $this->jwtManager->generateTokenPair(
            subjectId: $userId,
            payload: ['role' => 'user', 'permissions' => ['read', 'write']]
        );

        return new JsonResponse([
            'access_token' => $tokenPair->accessToken,
            'refresh_token' => $tokenPair->refreshToken,
            'expires_in' => $tokenPair->accessExpiresIn,
        ]);
    }

    public function refresh(RefreshRequest $request): JsonResponse
    {
        $refreshToken = $request->input('refresh_token');
        $tokenPair = $this->jwtManager->refreshAccessToken($refreshToken);

        return new JsonResponse([
            'access_token' => $tokenPair->accessToken,
            'refresh_token' => $tokenPair->refreshToken,
            'expires_in' => $tokenPair->accessExpiresIn,
        ]);
    }
}

Configuration

Edit config/autoload/jwt.php:

<?php

return [
    'algorithm' => 'HS256',
    'keys' => [
        'secret_key' => env('JWT_SECRET', 'your-secret-key-change-this'),
    ],
    'access_token' => ['ttl' => 900],  // 15 minutes
    'refresh_token' => ['ttl' => 604800], // 7 days
    'blacklist' => ['enabled' => true],
    'sso_mode' => false,
];

Documentation

• 📖 Installation & Configuration - Complete setup guide
• 🚀 Usage Examples - Practical examples and patterns
• 🔧 API Reference - Complete API documentation
• 🛡️ Security Guide - Best practices and security considerations
• 🏗️ Advanced Features - Token rotation, SSO, RSA/ECDSA algorithms
• 🔌 Middleware Integration - HTTP middleware setup
• ⚠️ Error Handling - Exception handling guide

Requirements

• PHP 8.3 or higher
• Hyperf 3.1 or higher
• ext-json

Contributing

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

Please ensure your code follows PSR-12 coding standards and includes tests.

Testing

# Run all tests
composer test

# Static analysis
composer analyse

# Code style fixer
composer cs-fix

License

This package is open-sourced software licensed under the MIT license.

Support

If you discover any security vulnerabilities or have questions, please email [e-mail].