README

Una librería simple, eficiente y fácil de usar para generar y validar tokens JWT (JSON Web Tokens) en aplicaciones Laravel 11 y 12.

Características

✅ Compatible con Laravel 11 y 12
✅ Alto rendimiento con caché de secretos y optimizaciones
✅ Fácil de usar con API simple e intuitiva
✅ Seguro con validación de firmas y expiración
✅ Bien documentado con PHPDoc completo
✅ Pruebas unitarias completas con PHPUnit
✅ Middleware listo para usar para autenticación
✅ Independiente de modelos - funciona sin depender de Eloquent

Instalación

Requisitos

PHP >= 8.2
Laravel >= 11.0 o >= 12.0
Composer

Instalación vía Composer

composer require wramirez83/sjwt

Publicar configuración (Opcional)

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

Esto creará el archivo config/sjwt.php donde puedes configurar:

secret: Clave secreta para firmar tokens (por defecto usa SECRET_JWT del .env)
default_expiration: Tiempo de expiración por defecto en minutos (60)
header_name: Nombre del header HTTP (por defecto: Authorization)
token_index: Índice del token en el header (por defecto: 1, para "Bearer {token}")

Configuración

Variables de Entorno

Agrega a tu archivo .env:

SECRET_JWT=tu-clave-secreta-muy-segura-aqui
JWT_EXPIRATION=60
JWT_HEADER_NAME=Authorization
JWT_TOKEN_INDEX=1

Generar una Clave Secreta

Puedes generar una clave secreta segura usando:

php -r "echo bin2hex(random_bytes(32));"

O usar el script incluido:

php src/Tools/Generate.php

Uso Básico

Generar un Token JWT

use Wramirez83\Sjwt\SJWT;

// Crear un token con datos del usuario
$payload = [
    'user_id' => 123,
    'email' => 'usuario@example.com',
    'name' => 'Juan Pérez',
];

// Token válido por 60 minutos (por defecto)
$token = SJWT::encode($payload);

// Token válido por 120 minutos
$token = SJWT::encode($payload, 120);

Validar y Decodificar un Token

use Wramirez83\Sjwt\SJWT;

// Decodificar un token
$result = SJWT::decode($token);

// Verificar si el token es válido
if ($result->valid) {
    $userId = $result->payload->user_id;
    $email = $result->payload->email;
    
    echo "Usuario autenticado: $email";
} else {
    if ($result->tokenExpired) {
        echo "Token expirado";
    } elseif (!$result->signatureValid) {
        echo "Firma inválida";
    }
}

Leer Token desde Headers HTTP

// El método decode() puede leer automáticamente desde el header Authorization
$result = SJWT::decode(); // Lee de 'Authorization' header por defecto

// O especificar un header personalizado
$result = SJWT::decode('.', 'X-Auth-Token', 0);

Middleware de Autenticación

Registrar el Middleware

En app/Http/Kernel.php o bootstrap/app.php (Laravel 11+):

use Wramirez83\Sjwt\Tools\AuthJWTMiddleware;

// Laravel 11+
$middleware->alias([
    'auth.jwt' => AuthJWTMiddleware::class,
]);

Usar en Rutas

use Illuminate\Support\Facades\Route;
use Wramirez83\Sjwt\Tools\AuthJWTMiddleware;

// Proteger una ruta
Route::get('/api/user', function () {
    return UserAuth::user()->getAtt();
})->middleware(AuthJWTMiddleware::class);

// O con alias
Route::middleware(['auth.jwt'])->group(function () {
    Route::get('/api/profile', function () {
        return UserAuth::user()->getAtt();
    });
});

Acceder a Datos del Usuario Autenticado

use Wramirez83\Sjwt\UserAuth;

// Obtener todos los atributos
$userData = UserAuth::user()->getAtt();

// Obtener atributos específicos
$userId = UserAuth::user()->id();
$email = UserAuth::user()->email();
$name = UserAuth::user()->name();

// Obtener cualquier atributo
$role = UserAuth::user()->get('role', 'user');

// Verificar si existe un atributo
if (UserAuth::user()->has('permissions')) {
    // ...
}

Ejemplos de Uso

Login con JWT

use Wramirez83\Sjwt\SJWT;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (Auth::attempt($credentials)) {
        $user = Auth::user();
        
        $token = SJWT::encode([
            'id' => $user->id,
            'email' => $user->email,
            'name' => $user->name,
        ], 120); // Válido por 2 horas

        return response()->json([
            'token' => $token,
            'user' => $user,
        ]);
    }

    return response()->json(['error' => 'Credenciales inválidas'], 401);
}

Proteger API Endpoints

Route::middleware([AuthJWTMiddleware::class])->group(function () {
    Route::get('/api/dashboard', function () {
        $user = UserAuth::user();
        return [
            'user_id' => $user->id(),
            'email' => $user->email(),
            'dashboard_data' => getDashboardData($user->id()),
        ];
    });
});

Estructura del Proyecto

SJWT/
├── src/
│   ├── SJWT.php                    # Clase principal para encode/decode
│   ├── UserAuth.php                # Singleton para datos de usuario
│   ├── SjwtServiceProvider.php     # Service Provider de Laravel
│   └── Tools/
│       ├── AuthJWTMiddleware.php   # Middleware de autenticación
│       ├── StructJWT.php           # Constructor de estructura JWT
│       ├── UrlEncode.php           # Codificación Base64URL
│       └── Generate.php            # Generador de secretos
├── config/
│   └── sjwt.php                    # Archivo de configuración
├── tests/
│   ├── Unit/                        # Pruebas unitarias
│   └── Feature/                    # Pruebas de integración
└── composer.json

Pruebas

Ejecutar todas las pruebas:

composer test

O con PHPUnit directamente:

./vendor/bin/phpunit

Ejecutar pruebas específicas:

./vendor/bin/phpunit tests/Unit/SJWTTest.php

Mejoras de Rendimiento

Esta versión incluye varias optimizaciones:

Caché de Secretos: El secreto JWT se cachea para evitar búsquedas repetidas
Validación Eficiente: Uso de hash_equals() para comparación segura de firmas
Manejo Optimizado de Headers: Búsqueda eficiente de tokens en headers HTTP
Eliminación de Duplicación: Código consolidado sin clases duplicadas

Seguridad

✅ Validación de firmas con hash_equals() (timing-safe)
✅ Verificación de expiración de tokens
✅ Validación de formato JWT
✅ Manejo seguro de errores sin exponer información sensible
✅ Soporte para claves secretas configurables

Compatibilidad

Laravel: 11.x, 12.x
PHP: >= 8.2
Dependencias:
- illuminate/support: ^11.0|^12.0
- illuminate/http: ^11.0|^12.0
- nesbot/carbon: ^3.0

Contribuir

Las contribuciones son bienvenidas. Por favor:

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Autor

Wilson Ramirez Z

Email: wilson.rz@gmail.com

Changelog

v3.0.0

✨ Compatibilidad con Laravel 12
⚡ Mejoras significativas de rendimiento
🧪 Pruebas unitarias completas
📚 Documentación mejorada
🔧 Refactorización del código
🛡️ Mejoras de seguridad

v2.1.0

Versión anterior

Soporte

Si encuentras algún problema o tienes preguntas, por favor abre un issue en el repositorio.

wramirez83 / sjwt

Maintainers

Details