Laravel Sanctum: modelo PersonalAccessToken y tabla personal_access_tokens

Cita de la doc de Sanctum: Although not typically required, you are free to extend the PersonalAccessToken model used internally by Sanctum.

 

¿Qué quiere decir que se puede extender el modelo PersonalAccessToken?

---

¡Claro! Ese texto explica una capacidad importante de Laravel Sanctum que te da más flexibilidad para personalizar la autenticación de tu API.

Básicamente, lo que te dice es lo siguiente:

"Aunque normalmente no sea necesario, eres libre de extender el modelo PersonalAccessToken usado internamente por Sanctum."

Vamos a desglosarlo:

• "PersonalAccessToken model": Cuando instalas Laravel Sanctum y ejecutas sus migraciones (php artisan migrate), se crea una tabla en tu base de datos llamada personal_access_tokens. Esta tabla almacena todos los tokens de API que se generan para tus usuarios. El "modelo PersonalAccessToken" es la representación Eloquent de esa tabla en Laravel. Es el objeto PHP que Laravel usa para interactuar con los datos de cada token (como el ID, el nombre, las habilidades/scopes, la fecha de expiración, etc.).

• "usado internamente por Sanctum": Este modelo es el corazón de cómo Sanctum gestiona y verifica los tokens. Cada vez que un usuario se autentica con un token, o un token es generado o revocado, Sanctum interactúa con este modelo y su tabla asociada.

• "aunque normalmente no sea necesario": Para la gran mayoría de las aplicaciones y necesidades de autenticación, el modelo PersonalAccessToken que Sanctum provee por defecto es perfectamente suficiente. Ya incluye campos para el nombre del token, las habilidades (abilities), la fecha de última utilización (last_used_at), y la fecha de expiración (expires_at).

• "eres libre de extender": Esto significa que si las funcionalidades por defecto del modelo PersonalAccessToken no son suficientes para tus necesidades específicas, tienes la capacidad de modificar o añadirle funcionalidades.

---

¿Por qué querrías extender el modelo PersonalAccessToken?

Podrías extenderlo si, por ejemplo:

1. Necesitas almacenar información adicional sobre el token: Imagina que quieres guardar el user_agent desde el que se creó el token, o la IP desde la que se usa, o un campo is_revoked_by_admin para un tipo específico de revocación.
2. Necesitas lógica personalizada para la gestión de tokens: Podrías querer sobrescribir cómo se comprueban las habilidades (can()) para añadir una lógica más compleja, o añadir métodos personalizados para buscar tokens de una manera específica.
3. Integración con otros sistemas: Si tienes un sistema de logs o auditoría muy específico, podrías añadir eventos o observadores al modelo PersonalAccessToken.

---

¿Cómo se extendería?

1. Crearías tu propio modelo de Laravel que extienda el modelo base de Sanctum:
   PHP

   // app/Models/MyCustomAccessToken.php
   <?php
   
   namespace App\Models;
   
   use Laravel\Sanctum\PersonalAccessToken as SanctumPersonalAccessToken;
   
   class MyCustomAccessToken extends SanctumPersonalAccessToken
   {
       // Aquí puedes añadir tus nuevos campos (asegurándote de agregarlos también a la migración de la tabla)
       // Por ejemplo: protected $fillable = ['name', 'token', 'abilities', 'last_used_at', 'expires_at', 'user_agent'];
       // Y aquí puedes añadir tus propios métodos o sobrescribir los existentes
       public function wasCreatedFromMobile()
       {
           // Lógica para determinar si el token fue creado desde un móvil, si guardaste esa info
           return str_contains($this->user_agent ?? '', 'Mobile');
       }
   }
   

2. Le dirías a Sanctum que use tu nuevo modelo en lugar del predeterminado. Esto se hace en el archivo de configuración de Sanctum (config/sanctum.php):
   PHP

   // config/sanctum.php
   'token_model' => App\Models\MyCustomAccessToken::class,
   

3. Si añades nuevos campos, también tendrías que crear una nueva migración para añadir esas columnas a la tabla personal_access_tokens.

---

En resumen, la frase te da la libertad de personalizar un componente central de Sanctum si las características predeterminadas no satisfacen todas tus necesidades, manteniendo la extensibilidad que caracteriza a Laravel.