README

Laravel Tokenable

Introduction

Laravel Tokenable is a modern authentication package that extends Laravel’s token capabilities beyond Sanctum.

It supports:

• APIs for stateless clients.
• SPAs (Single Page Applications) for JavaScript-driven frontends.
• SSR (Server-Side Rendered apps) with cookie-based authentication.

Key features include:

• Multi-model support — authenticate multiple user models (e.g. User, Admin, Member) seamlessly.
• Multi-platform support — issue tokens per platform (e.g. App, Web, Mini Programs) with fine-grained control.
• Refresh tokens — enable long-lived sessions with secure refresh workflows.
• Flexible token structure — customize token structure and lifecycle management.
• Cookie + API support — works equally well for session-based SSR and token-based APIs.

Laravel Sanctum provides basic API authentication and multiple model support, but falls short when:

• You need fine-grained token control per platform (e.g. App vs Web).
• You require refresh token flows.
• You want customizable token structures instead of being tied to Sanctum’s defaults.

Laravel Tokenable bridges this gap, making token authentication first-class, flexible, and universal across your Laravel projects.

[back to top]

Documentation

Documentation for Laravel Tokenable can be found on the documentation.

[back to top]

Installation

You can install the package via Composer:

composer require jundayw/tokenable

Publish Resources

Your users can also publish all publishable files defined by your package's service provider using the --provider flag:

php artisan vendor:publish --provider="Jundayw\Tokenable\TokenableServiceProvider"

You may wish to publish only the configuration files:

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

You may wish to publish only the migration files:

php artisan vendor:publish --tag=tokenable-migrations

Run Migrations

php artisan migrate --path=database/migrations/2025_06_01_000000_create_auth_token_table.php

[back to top]

Usage

Configuration

Use the tokenable guard in the guards configuration of your application's auth.php configuration file:

'guards' => [
    'api' => [
        'driver' => 'tokenable',
        'provider' => 'users',
    ],
],

Model

To start issuing tokens for users, your User model should use the Jundayw\Tokenable\HasTokenable trait and implement the Jundayw\Tokenable\Contracts\Tokenable interface.

namespace App\Models;

use Jundayw\Tokenable\Contracts\Tokenable;
use Jundayw\Tokenable\HasTokenable;

class User extends Authenticatable implements Tokenable
{
    use HasTokenable, HasFactory, Notifiable;
}

Create Token

$user = User::query()->where([
    'email'    => $request->get('email'),
    'password' => Hash::make($request->get('password')),
])->first();

if(is_null($user)){
    return null;
}

return $this->guard('web')
    ->login($user)
    ->createToken(name: 'PC Token', platform: 'pc');

Refresh Token

return $this->guard('web')->refreshToken();

Revoke Token

return $this->guard()->revokeToken();

Exception

TokenableException
├── AuthenticationException (HTTP 401)                // 所有认证失败的基类
│   └── TokenInvalidException                         // 令牌相关的认证异常基类
│       ├── TokenNotFoundException                    // 令牌不存在
│       ├── TokenExpiredException                     // 令牌过期基类
│       │   ├── AccessTokenExpiredException           // 访问令牌过期
│       │   └── RefreshTokenExpiredException          // 刷新令牌过期
│       └── RefreshTokenNotAvailableException         // 刷新令牌尚未生效
└── AuthorizationException (HTTP 403)                 // 所有授权失败的基类
    └── MissingScopeException                         // 缺少必要权限范围

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

[back to top]

Contributors

Thanks goes to these wonderful people:

Contributions of any kind are welcome!

[back to top]

License

Distributed under the MIT License (MIT). Please see License File for more information.

[back to top]