Filament Sanctum Laravel Package

Technical Evaluation

Architecture Fit

• Filament 5 + Laravel 13 Synergy: The package now explicitly supports Filament 5 and Laravel 13, aligning with the latest Laravel ecosystem. The modular plugin architecture remains intact, ensuring minimal intrusion into core Filament or Sanctum systems.
• Enhanced Token Lifecycle Management: New features like token expiration presets, detailed token modals, and per-row revocation improve granularity for API token management, reducing manual Sanctum CLI usage.
• Authorization Integration: The addition of configurable Laravel gates for Sanctum page access enables tighter RBAC alignment, addressing a gap in v1.0’s assessment.
• Stateful UI Improvements: The token details modal (with timestamps, abilities, and usage history) provides admins with contextual insights, reducing debugging overhead.

Integration Feasibility

• Filament 5 Migration Path: The package now requires Filament 5, which may necessitate a major version upgrade if the project is on Filament 4. Mitigation: Test Filament 5’s breaking changes (e.g., MenuItem → Action) early.
• Laravel 13 Compatibility: Explicit support for Laravel 13 (via CI matrix) reduces risk, but custom Sanctum setups (e.g., non-default token models) may still require validation.
• Backward Compatibility: The package deprecates Filament 4 support, forcing an upgrade. Projects on Filament 4 must either:
  • Stay on v1.0.x, or
  • Migrate to Filament 5 (recommended for long-term support).
• Configuration Overrides: Expanded config/filament-sanctum.php options (e.g., default_expiration_days, authorization gate) centralize customization, reducing hardcoded logic.

Technical Risk

• Filament 5 Breaking Changes: The migration from MenuItem to Action and TagsColumn → TextColumn may break custom Filament plugins. Mitigation: Audit Filament 5’s upgrade guide and test the package in a staging environment.
• Token Expiration Logic: Custom expiration logic (e.g., business-specific rules) may conflict with the package’s presets. Mitigation: Extend the PersonalAccessToken model or override the package’s createToken method.
• Authorization Gate Complexity: Misconfigured gates could lock admins out of the Sanctum panel. Mitigation: Use Filament’s canAccess middleware for fallback access during testing.
• Performance with Expiration: Adding expiration fields to token queries could impact large-scale deployments. Mitigation: Index expires_at in the personal_access_tokens table.

Key Questions

1. Filament Upgrade Feasibility: Is the project ready to migrate from Filament 4 to 5? If not, can v1.0.x be maintained in parallel?
2. Token Expiration Strategy: Should token expiration be mandatory, optional, or custom-per-user? The package’s presets may need extension.
3. RBAC Alignment: Does the project’s Laravel gate system support the new authorization config? Test with php artisan gate:list.
4. Multi-Tenant Expiration: If using multi-tenancy, will token expiration logic respect tenant contexts? Override Sanctum::resolveToken() if needed.
5. Audit Logging: Are token expiration/revocation events logged? Integrate with Filament’s audit log or a third-party tool like Laravel Telescope.
6. Fallback for Filament 4: If stuck on Filament 4, can the package be forked to revert Filament 5 changes? Assess effort vs. upgrade cost.

Integration Approach

Stack Fit

• Laravel 13 + Filament 5: Native fit. The package is optimized for these versions; downgrades are unsupported.
• Sanctum v3+: Required for token expiration and lifecycle features. Verify compatibility if using a fork (e.g., spatie/laravel-permission-extended Sanctum).
• Database: Relies on Sanctum’s default personal_access_tokens table. New: Adds expires_at column (migrated automatically via Sanctum’s HasApiTokens trait).
• Frontend: No direct impact, but the token details modal and expiration UI improve UX for admins managing API clients.

Migration Path

1. Pre-Integration:
   • Audit Current Stack: Confirm Filament 5 and Laravel 13 compatibility. Run:

     composer why filament filament/filament
     composer why laravel/framework
     

   • Backup Sanctum Configs: Export config/sanctum.php and existing token data.
   • Test Filament 5 Upgrade: Follow Filament’s upgrade guide in staging.
2. Installation:

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

3. Configuration:
   • Update config/filament-sanctum.php:

     'default_expiration_days' => 30,
     'authorization' => [
         'gate' => 'view-sanctum-page',
         'policy' => null,
     ],
     'expiration_presets' => [
         '7_days' => '7 Days',
         '30_days' => '30 Days',
         '90_days' => '90 Days',
     ],
     

   • Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

     ->plugin(FilamentSanctumPlugin::make())
     

4. Database Migration:
   • Sanctum’s HasApiTokens trait will add expires_at to personal_access_tokens. Run:

     php artisan migrate
     

5. Testing:
   • Validate token expiration in Filament UI and API:

     // Test API
     $token = Sanctum::createToken($user, ['create']);
     $this->assertEquals(now()->addDays(30)->timestamp, $token->expires_at->timestamp);
     

   • Test authorization gates:

     php artisan gate:test view-sanctum-page
     

Compatibility

• Filament Plugins:
  • Conflicts: Test with filament/spatie-laravel-permission (RBAC) and filament/medialibrary (no direct impact).
  • Custom Plugins: Ensure plugins using MenuItem or TagsColumn are updated for Filament 5.
• Sanctum Extensions:
  • Packages like spatie/laravel-permission should coexist if they extend Sanctum’s PersonalAccessToken model.
  • Custom Token Models: Override Sanctum::tokenModel() if using a non-default model.
• Legacy Code:
  • Token Expiration: Existing code using Sanctum::tokens() must handle expires_at null checks.
  • CLI Tools: Deprecate manual Sanctum token management in favor of Filament’s UI.

Sequencing

1. Phase 1: Upgrade Filament to v5 and Laravel to v13 in staging.
2. Phase 2: Install filament-sanctum v1.1 and configure expiration/gate settings.
3. Phase 3: Migrate existing tokens (if any) via Sanctum’s PersonalAccessToken model or CLI.
4. Phase 4: Train admins on the new token modal, expiration presets, and per-row revoke.
5. Phase 5: Deprecate legacy token management workflows (e.g., Tinker commands).

Operational Impact

Maintenance

• Dependency Updates:
  • Pin devtical/filament-sanctum to ^1.1 to avoid auto-updates during Filament 5’s early release cycle.
  • Monitor Filament 5’s release notes for breaking changes.
• Configuration Drift:
  • Centralize Sanctum/Filament configs in config/filament-sanctum.php and config/sanctum.php.
  • Use environment variables for sensitive settings (e.g., SANCTUM_EXPIRATION_DEFAULT_DAYS).
• Plugin Updates:
  • Test the package against Filament 5.x minor updates (e.g., v5.1 → v5.2) in CI.

Support

• Troubleshooting:
  • Token Expiration Issues: Check expires_at in the DB and Sanctum’s HasApiTokens trait.
  • UI Glitches: Clear Filament cache:

    php artisan filament:cache:clear
    php artisan view:clear