makaveli/laravel-jwt-auth

JWT authentication for Laravel

1.1.0 2025-12-30 16:00 UTC

Requires

• php: ^8.2
• laravel/framework: ^10.10|^11.0|^12.0
• makaveli/laravel-core: ^1.0
• makaveli/laravel-logger: ^1.1

Requires (Dev)

• mockery/mockery: ^1.5
• orchestra/testbench: ^8.0
• phpunit/phpunit: ^10.0
• predis/predis: ^2.0

MIT

• framework
• laravel

README

Laravel JWT Auth — это лёгкий и полностью самописный пакет для реализации JWT-авторизации в Laravel без использования сторонних библиотек типа tymon/jwt-auth или firebase/php-jwt.
Пакет предоставляет генерацию access/refresh токенов, верификацию, refresh, blacklist, поддержку нескольких хранилищ (memory/cache, redis, database) и простую интеграцию в проекты.

Возможности

• Генерация пары токенов: access + refresh
• Поддержка алгоритмов HS256 (по умолчанию), RS*, ES*
• Автоматическая проверка signature, header, payload (exp, sub, name)
• Blacklist токенов при refresh/logout (с TTL)
• Три разных драйвера хранилища blacklist:
  • memory (array store Laravel — для тестов)
  • redis (рекомендуется в продакшене)
  • database (таблица blacklisted_tokens)
• Полная поддержка unit-тестов (Orchestra Testbench + SQLite)
• Консольные команды для генерации секрета и миграций
• Простая конфигурация через config/jwt.php

Требования

• PHP ≥ 8.2
• Laravel ≥ 10.x (тестировалось на 10–12)
• Composer
• (опционально) Redis для драйвера redis
• (опционально) predis/predis если нет php-redis extension

Установка

1. Установите пакет:

composer require makaveli/laravel-jwt-auth

1. Опубликуйте конфигурацию (если нужно):

php artisan vendor:publish --tag=jwt-config

Файл появится в config/jwt.php.

1. Выполните миграции (для драйвера database):

php artisan migrate

(Миграции автоматически загружаются из пакета, публикация не требуется.)

Конфигурация (config/jwt.php)

Основные настройки:

return [
    'algo'                 => 'HS256',                // HS256, RS256, ES256 и т.д.
    'private'              => env('JWT_SECRET', 'test-secret-key'),
    'ttl'                  => env('JWT_TTL', 60),     // access token lifetime, минуты
    'refresh_ttl'          => env('JWT_REFRESH_TTL', 120),
    'allow_infinite_ttl'   => false,
    'infinite_ttl_fallback'=> 31536000,               // 1 год в секундах

    'sub_payload_field'    => 'email',                // поле модели пользователя для sub
    'name_payload_fields'  => ['name'],               // поля для name в payload

    'user_model'           => Tests\Fakes\FakeUser::class, // в тестах, в проде — ваша модель

    'token_storage' => [
        'driver'       => env('JWT_TOKEN_STORAGE_DRIVER', 'memory'), // memory | redis | database
        'storage_ttl'  => env('JWT_BLACKLIST_STORAGE_TTL', 86400 * 7), // 7 дней
    ],
];

Рекомендуемые значения в .env для продакшена:

JWT_ALGO=HS256
JWT_SECRET=your-very-long-random-secret
JWT_TTL=15                  # 15 минут
JWT_REFRESH_TTL=10080       # 7 дней
JWT_TOKEN_STORAGE_DRIVER=redis
JWT_BLACKLIST_STORAGE_TTL=604800

Использование

1. Генерация токенов

use JWTAuth\JWTAuth;

[$accessToken, $refreshToken] = $this->fromUser($user);

2. Верификация токена

$payload = $this->verify($accessToken);

if ($payload['verify_fail']) {
    // 401 Unauthorized
}

$user = $payload['user'];

3. Refresh токена

$newTokens = $this->refreshToken($refreshToken);

if ($newTokens === null) {
    // Refresh expired или blacklisted
}

4. Logout (blacklist access token)

$this->logout($accessToken);

Blacklist хранилища

Пакет поддерживает 3 драйвера:

Драйвер	Хранилище	Преимущества	Когда использовать
memory	Laravel ArrayStore	Очень быстро	Тесты, разработка
redis	Redis (setex + scan)	Быстро, TTL, масштабируемо	Продакшен (рекомендуется)
database	Таблица blacklisted_tokens	Надёжно, просто, без доп. сервисов	Когда Redis недоступен

Переключение в .env:

JWT_TOKEN_STORAGE_DRIVER=redis
# или database / memory

Консольные команды

# Сгенерировать новый секрет для JWT
php artisan jwt:secret

# Выполнить миграции пакета (если driver=database)
php artisan migrate

Пример задачи для очистки просроченных токенов (если вы используете драйвер database или redis)

1. Добавьте в массив $commands в \Console\Kernel класс

protected $commands = [
    \JWTAuth\Console\Commands\JWTSecretGenerate::class,
    ...
];

1. Добавьте в schedule дневной вызов команды

// App\Console\Kernel
protected function schedule(Schedule $schedule)
{
    $schedule->command('jwt:clear-tokens')->daily();
}

Тестирование

Пакет полностью покрыт unit-тестами (PHPUnit + Orchestra Testbench):

• Генерация/верификация/refresh токенов
• Все сценарии expire (access, refresh, both)
• Blacklist (memory, redis, database)
• Edge-кейсы (invalid signature, future exp, etc.)

Запуск:

vendor/bin/phpunit

Структура пакета

src/
├── Actions/                  # фасады для внешнего API (addToBlacklist, isBlacklisted, removeExpired)
├── Services/                 # операции записи/удаления
├── Repositories/             # операции чтения
├── Helpers/                  # JWTSlice, JWTVerify, JWTCoder, etc.
├── Factories/                # TokenStorageFactory
├── Interfaces/               # TokenStorageInterface
├── Constants/                # CacheConstants, RedisConstants
└── JWTAuth.php               # основной trait с методами fromUser, verify, refreshToken, logout

Расширение

• Хотите новый driver хранилища? Реализуйте TokenStorageInterface и добавьте в TokenStorageFactory.
• Нужно поддержать другой алгоритм? Расширьте JWTAlgo и JWTSlice::generateSignature.
• Нужен audit log? Добавьте observer на BlacklistedToken (database).

Лицензия

MIT

Если нужны дополнения (примеры middleware, guard, sanctum-совместимость, rate-limiting) — напишите, добавлю разделы.