README

A Laravel package for implementing JSON Web Token (JWT) authentication with a robust service layer, middleware, traits, and commands.

Features

JWT token generation and validation
Middleware for protected routes
Trait for easy token creation in models
Command-line setup tool
Facade for convenient access
Comprehensive error handling

Requirements

PHP >= 8.2
Laravel >= 11.x/ 12.x
Composer

Installation

Install the package via Composer:

composer require tahajaiti/jwt

Run the setup command to configure the package:

php artisan jwt:setup

This will:
Create or update your .env file with JWT variables
Publish the configuration file to config/jwt.php
Clear configuration and cache

Configuration

The package publishes a configuration file at config/jwt.php. Default values are set in the .env file:

JWT_SECRET=your-secret
JWT_ALGO=HS256
JWT_TTL=3600

You can customize these in either the .env file or config/jwt.php:

return [
    'secret' => env('JWT_SECRET', 'fallback-secret'),
    'algo' => env('JWT_ALGO', 'HS256'),
    'ttl' => env('JWT_TTL', 3600),
];

Usage

Service Provider

The package automatically registers its service provider. If you need to customize it, add to bootstrap/providers.php:

'providers' => [
    // ...
    Kyojin\JWT\Providers\JWTServiceProvider::class,
],

Generating Tokens

Using the Trait

Add the HasJWT trait to your User model:

use Kyojin\JWT\Traits\HasJWT;

class User extends Authenticatable
{
    use HasJWT;

    // Optional: Customize payload
    public function payload(): array
    {
        return [
            'role' => $this->role
        ];
    }
}

Create a token:

$user = User::find(1);
$token = $user->createToken(); // New token

Using the Facade

use Kyojin\JWT\Facades\JWT;

$payload = ['sub' => 1, 'role' => 'admin'];
$token = JWT::encode($payload);

Middleware

Protect routes with the JWT authentication middleware:

// In routes/api.php
Route::middleware('jwt')->group(function () {
    Route::get('/test', function () {
        return response()->json(['message' => 'Authenticated']);
    });
});

Requests must include an Authorization header:

Authorization: Bearer your-jwt-token

Or optionally you can send the token through Http Cookies as 'jwt_token'

Validating Tokens

The default middleware automatically binds the user to the Auth facade

use Kyojin\JWT\Facades\JWT;

$isValid = JWT::validate($token); // Returns boolean
$payload = JWT::decode($token);   // Returns array or throws exception
$user = Auth::user();            // Returns the user based on the validated token 
$user = JWT::user();            // (Optional method for retrieving the user)

Error Handling

The package throws two main exceptions:

TokenNotFoundException: When no token is provided (401)
InvalidTokenException: When token is invalid or expired (401)

Handle them in your application exception handler:

use Kyojin\JWT\Exceptions\InvalidTokenException;
use Kyojin\JWT\Exceptions\TokenNotFoundException;

public function render($request, Throwable $exception)
{
    if ($exception instanceof TokenNotFoundException || $exception instanceof InvalidTokenException) {
        return response()->json(['error' => $exception->getMessage()], 401);
    }
}

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/name)
Commit your changes (git commit -m 'Add new feature')
Push to the branch (git push origin feature/name)
Open a Pull Request

License

This package is open source do whatever.

tahajaiti / jwt

Maintainers

Details