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

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

License

This package is open source do whatever.