Getting Started

Minimal Setup

Installation

composer require devtical/filament-sanctum
php artisan vendor:publish --tag=filament-sanctum-config
php artisan vendor:publish --tag=filament-sanctum-translations

Publish the config and translations to customize behavior, expiration defaults, and language.

Register the Plugin Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \Devtical\FilamentSanctum\FilamentSanctumPlugin::make(),
        ]);
}

First Use Case Access the Sanctum token management UI at /admin/sanctum-tokens (configurable via sanctum_url in config). Key features:
- Create tokens with preset expiration (7/30/60/90 days) or custom dates.
- Revoke tokens via bulk actions or per-row buttons.
- View details in a modal (abilities, expiration, timestamps).
- Restricted access via Laravel gates (configured in authorization config).

Implementation Patterns

Core Workflows

Token Management with Expiration

Create Tokens with Expiration: The UI now includes expiration presets. Programmatically:

// Custom expiration (e.g., 15 days)
$token = $user->createToken('API Token', [], now()->addDays(15));

// Use preset (e.g., 30 days)
$token = $user->createToken('API Token', [], now()->addDays(config('filament-sanctum.default_expiration_days')));

Bulk Revoke: Use the table’s bulk action dropdown or revoke individually via per-row buttons.

Integration with Filament 5

Resource Filtering:

public static function getTableRecordsQuery(Table $table): QueryBuilder
{
    return parent::getTableRecordsQuery($table)
        ->when(
            $table->getUser()->cannot('view-all-tokens'),
            fn($q) => $q->where('user_id', $table->getUser()->id)
        );
}

Customize Navigation: Update the config to change the URL slug:

'sanctum_url' => 'api-tokens', // Changes path to `/admin/api-tokens`

Customizing Token Creation

Extend the CreateTokenAction to add logic (e.g., logging, notifications):

use Devtical\FilamentSanctum\Actions\CreateTokenAction;

class CustomCreateTokenAction extends CreateTokenAction
{
    protected function handle(): void
    {
        $expiration = $this->expiration ?? now()->addDays(config('filament-sanctum.default_expiration_days'));
        $token = $this->user->createToken($this->name, $this->abilities, $expiration);
        // Custom logic (e.g., send email)
        $this->dispatch(new TokenCreated($token));
    }
}

'create_token_action' => \App\Actions\CustomCreateTokenAction::class,

Authorization

Restrict access to the Sanctum page via a Laravel gate:

// config/filament-sanctum.php
'authorization' => 'view-sanctum-tokens',

Define the gate in AuthServiceProvider:

Gate::define('view-sanctum-tokens', function ($user) {
    return $user->hasRole(['admin', 'api-manager']);
});

Localization

Override translations for expiration labels or token details:

// resources/lang/vendor/filament-sanctum/en/messages.php
return [
    'expiration' => 'Valid Until',
    'never_expires' => 'Never Expires',
];

Gotchas and Tips

Pitfalls

URL Resolution Issues
- Fixed in v1.1.0: Duplicate /admin/admin/sanctum paths are resolved via Sanctum::getUrl().
- Debugging: Verify the sanctum_url config key and clear Filament’s cache:
```
php artisan filament:cache-reset
```
Token Abilities Display
- Fixed in v1.1.0: Repeated "None" text for abilities is resolved. Ensure your abilities column uses TextColumn (not TagsColumn):
```
TextColumn::make('abilities')
    ->formatStateUsing(fn($state) => implode(', ', $state)),
```

Expiration Handling

No Auto-Revoke: Tokens expire at the set time but aren’t auto-revoked. Schedule a job:

// app/Console/Commands/RevokeExpiredTokens.php
public function handle()
{
    DB::table('personal_access_tokens')
        ->where('expires_at', '<=', now())
        ->delete();
}

Config Defaults: Set default_expiration_days in config/filament-sanctum.php:
```
'default_expiration_days' => 30,
```

Filament 5 Migration

Breaking Change: MenuItem is replaced with Action. Update custom plugins:

// Old (v1.0.x)
MenuItem::make('Sanctum Tokens', 'heroicon-o-key')

// New (v1.1.0)
Action::make('sanctum-tokens')
    ->icon('heroicon-o-key')
    ->url(fn() => Sanctum::getUrl());

Debugging Tips

Token Not Showing?
- Check the personal_access_tokens table for orphaned records:
```
php artisan tinker
>>> \Devtical\FilamentSanctum\Facades\Sanctum::getTokensForUser(auth()->user());
```
- Verify the user has the view-sanctum-tokens gate.
Permission Denied
- Test gate access:
```
php artisan gate:test view-sanctum-tokens
```
- Ensure the gate is defined in AuthServiceProvider.
Plugin Not Loading
- Clear Filament’s cache and check for config errors:
```
php artisan filament:cache-reset
php artisan config:clear
```

Extension Points

Custom Token Fields

Extend the token table by publishing views:

php artisan vendor:publish --tag=filament-sanctum-views

Add columns to resources/views/filament-sanctum/columns/...:

<x-filament-tables::td>
    {{ $getRecord()->expires_at?->diffForHumans() ?? __('filament-sanctum::messages.never_expires') }}
</x-filament-tables::td>

Token Events

Listen for token creation/revocation:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \Devtical\FilamentSanctum\Events\TokenCreated::class => [
        \App\Listeners\LogTokenEvent::class,
    ],
    \Devtical\FilamentSanctum\Events\TokenRevoked::class => [
        \App\Listeners\NotifyTokenRevocation::class,
    ],
];

Multi-Tenant Support

Filter tokens by tenant in the resource query:

public static function getTableRecordsQuery(Table $table): QueryBuilder
{
    return parent::getTableRecordsQuery($table)
        ->where('tokens.tenant_id', tenant()->id);
}

Expiration Presets

Customize presets in config/filament-sanctum.php:

'expiration_presets' => [
    '7_days' => __('filament-sanctum::messages.days_7'),
    '30_days' => __('filament-sanctum::messages.days_30'),
    'custom' => __('filament-sanctum::messages.custom_date'),
],

Filament Sanctum Laravel Package