Search by

bolivir / laravel-doctrine-sanctum

Bolivir

Laravel doctrine integration for the official laravel-sanctum package

Package info

github.com/bolivir/laravel-doctrine-sanctum

pkg:composer/bolivir/laravel-doctrine-sanctum

Statistics

Installs: 21 593

Dependents: 0

Suggesters: 0

Stars: 3

Open Issues: 0

5.0.0 2025-02-24 10:19 UTC

This package is auto-updated.

Last update: 2026-11-08 04:58:36 UTC


README

CI

Laravel Sanctum API tokens for applications that use Laravel Doctrine ORM instead of Eloquent.

Sanctum stores its personal access tokens as Eloquent models. This package replaces that storage with Doctrine entities and registers a sanctum guard that looks tokens up through Doctrine. Everything else works the way Sanctum documents it: the auth:sanctum middleware, token abilities and token expiration.

Contents

Requirements

Installation

composer require bolivir/laravel-doctrine-sanctum

The package isn't auto-discovered, so register its service provider in bootstrap/providers.php:

return [
    App\Providers\AppServiceProvider::class,
    Bolivir\LaravelDoctrineSanctum\LaravelDoctrineSanctumProvider::class,
];

Then publish the configuration file:

php artisan vendor:publish --provider="Bolivir\LaravelDoctrineSanctum\LaravelDoctrineSanctumProvider" --tag="config"

This creates config/sanctum_orm.php.

Setup

1. Create the access token entity

Create an entity that implements IAccessToken. The TAccessToken trait provides the complete implementation, including the Doctrine attribute mapping, so all you add is the entity and its table:

<?php

namespace App\Entities;

use Bolivir\LaravelDoctrineSanctum\Contracts\IAccessToken;
use Bolivir\LaravelDoctrineSanctum\TAccessToken;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'personal_access_tokens')]
class AccessToken implements IAccessToken
{
    use TAccessToken;
}

The trait maps these fields: id (UUID), name, token (SHA-256 hash, unique), abilities, lastUsedAt, createdAt, expiresAt and the owner relation to your user. If you need a different mapping, implement IAccessToken yourself instead of using the trait.

The uuid column type comes from ramsey/uuid-doctrine. The package registers it for you.

2. Prepare the user entity

Your user entity must implement ISanctumUser. It extends Laravel's Authenticatable contract, so you don't declare that one separately. The HasApiTokens trait implements the token methods:

<?php

namespace App\Entities;

use Bolivir\LaravelDoctrineSanctum\Contracts\IAccessToken;
use Bolivir\LaravelDoctrineSanctum\Contracts\ISanctumUser;
use Bolivir\LaravelDoctrineSanctum\HasApiTokens;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'users')]
class User implements ISanctumUser
{
    use HasApiTokens;

    /** @var Collection<int, IAccessToken> */
    #[ORM\OneToMany(targetEntity: IAccessToken::class, mappedBy: 'owner', cascade: ['persist'], orphanRemoval: true)]
    protected Collection $accessTokens;

    public function __construct()
    {
        $this->accessTokens = new ArrayCollection();
    }

    // ... your own fields and the Authenticatable methods
}

HasApiTokens declares the $accessTokens collection but doesn't map it. Map it on your entity as shown above if you use findToken(), revokeToken() or revokeAllAccessTokens() on the user.

Both entities can reference the interfaces (IAccessToken, ISanctumUser) instead of your concrete classes. The package configures Doctrine's resolve_target_entities to map them to the classes in your configuration.

3. Configure the package

Point config/sanctum_orm.php at your entities:

return [
    'doctrine' => [
        'models' => [
            'token' => App\Entities\AccessToken::class,
            'user' => App\Entities\User::class,
        ],
        // The Doctrine entity manager that manages the token entity.
        'manager' => 'default',
    ],

    // Delete tokens that have not been used for this many minutes. 0 keeps them forever.
    'unused_token_ttl' => 0,
];

4. Configure authentication

Users are loaded through Laravel Doctrine's doctrine user provider. In config/auth.php:

'providers' => [
    'users' => [
        'driver' => 'doctrine',
        'model' => App\Entities\User::class,
    ],
],

Sanctum registers the sanctum guard itself, and this package replaces its driver with a Doctrine-backed one. You don't need to add the guard to config/auth.php. Sanctum's own settings in config/sanctum.php still apply, such as guard (for stateful SPA requests) and expiration.

5. Create the database table

Generate the table from your entity mapping. With laravel-doctrine/migrations:

php artisan doctrine:migrations:diff
php artisan doctrine:migrations:migrate

Without migrations, php artisan doctrine:schema:update also works.

Usage

Issuing tokens

Inject IAccessTokenRepository and call createToken(). The plain-text token is only available on the returned NewAccessToken. Only its SHA-256 hash is stored, so return it to the client right away.

use Bolivir\LaravelDoctrineSanctum\Repository\IAccessTokenRepository;

class LoginController
{
    public function __construct(private IAccessTokenRepository $tokens)
    {
    }

    public function __invoke(Request $request)
    {
        // ... validate the credentials and load $user

        $newToken = $this->tokens->createToken($user, 'mobile-app', ['orders:read']);

        return ['token' => $newToken->plainTextToken];
    }
}

The third argument is the list of abilities. It defaults to ['*'], which grants every ability.

Protecting routes

Clients send the token as a bearer token: Authorization: Bearer <token>. Protect routes with Sanctum's middleware:

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

Token abilities

if ($request->user()->tokenCan('orders:read')) {
    // ...
}

$request->user()->currentAccessToken() returns the IAccessToken the request authenticated with.

Revoking tokens

$user->revokeToken($user->currentAccessToken()); // the current token
$user->revokeAllAccessTokens();                  // every token of this user

$entityManager->flush();

These methods remove the tokens from the user's $accessTokens collection. They are deleted from the database on flush when the collection is mapped with orphanRemoval: true, as in step 2.

Token expiration

A token is rejected when either of these is true:

  • it is older than expiration in config/sanctum.php, in minutes (null means it never expires), or
  • its own expiry date has passed. Set it with $token->changeExpiresAt(new \DateTime('+1 week')).

Pruning unused tokens

Set unused_token_ttl in config/sanctum_orm.php, then run the command, or schedule it:

php artisan sanctum_orm:delete-unused-tokens
// routes/console.php
Schedule::command('sanctum_orm:delete-unused-tokens')->daily();

Version compatibility

Package Laravel Sanctum Laravel Doctrine ORM
5.x ^4.0 ^3.0
4.x ^4.0 ^2.0
3.x ^3.0 ^2.0
2.x ^2.0 ^2.0
1.x ^2.0 ^1.0

Upgrading

See UPGRADE.md. More examples are in the wiki.

License

MIT. See LICENSE.