php artisan sanctum:prune-expired
Laravel Sanctum のパーソナルアクセストークンを、一定時間が経過した後に自動で削除します。
目的：古くて無効になったトークンをデータベースから消去し、テーブルの肥大化を防ぐ。
コマンド概要
| オプション | 意味 | デフォルト |
|---|---|---|
--hours=HOURS | 削除対象とする「有効期限経過後の時間」 | 24 |
--quiet | 出力を抑制 | false |
--no-interaction | 対話なしで実行 | false |
注意
このコマンドはpersonal_access_tokensテーブルのexpires_atカラムではなく、config/sanctum.phpのexpiration（単位: 分）を基準にして削除します。
つまり、expires_atがNULLでも、設定された期限が過ぎたトークンは削除対象です。
基本的な実行例
# 24時間（デフォルト）経過したトークンを削除
php artisan sanctum:prune-expired
# 48時間経過したトークンを削除
php artisan sanctum:prune-expired --hours=48
# 実行結果例
Pruning personal access tokens that have been expired for the last 48 hours...
Deleted 12 tokens.
Laravel 12.x でのスケジューリング
// app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
// 毎日 02:00 UTC に実行（24時間経過したトークンを削除）
$schedule->command('sanctum:prune-expired --hours=24')
->dailyAt('02:00');
}
cron の設定例（サーバ側）
* * * * * cd /path/to/your/project && php artisan schedule:run >> /dev/null 2>&1
よくあるトラブルと対策
| トラブル | 原因 | 対策 |
|---|---|---|
| 削除されない | sanctum.expiration が null / 0 | config/sanctum.php の expiration を有効な整数に設定し、php artisan config:clear / php artisan config:cache を実行 |
トークンがまだ NULL で期限切れ扱いにならない | Sanctum が正しく設定されていない | config('sanctum.expiration') を確認し、Sanctum のパッケージを再インストールまたは設定を再度見直す |
| スケジューラが失敗 | PHP パスが間違っている / 権限が不足 | cron の実行パスを確認し、Web サーバーのユーザー権限で artisan が実行できるかテスト |
| 大量データで遅延 | personal_access_tokens が巨大 | 大きなテーブルは定期的にスケジューリングし、必要に応じて expires_at カラムにインデックスを追加する（※カスタム実装の場合） |
expires_at カラムは無視される | コマンドは sanctum.expiration のみを参照 | より細かい制御が必要なら、カスタムコマンドを作成するか、Sanctum のソースを fork する |
実務での活用例
- 月末バッチ
php artisan sanctum:prune-expired --hours=720
# 30日（720時間）以上経過したトークンを削除
- アプリ稼働中の保守
スケジューラを有効にして、夜間（トラフィックが少ない時間帯）に自動で実行。
これにより、ユーザーがアプリを使用していない古いトークンが残っても、データベースが肥大化しない。
まとめ
| 項目 | 内容 |
|---|---|
| 目的 | 古くて無効な Sanctum トークンを自動で削除 |
| 主なオプション | --hours（削除対象時間） |
| 依存設定 | config/sanctum.php → expiration |
| 推奨 | スケジューラで定期実行、ログは確認して削除件数を把握 |
最短の使い方
php artisan sanctum:prune-expired --hours=48これだけで 48 時間以上経過した全トークンを削除できます。
次のステップ
- スケジューラを設定して定期実行
config/sanctum.phpのexpirationをビジネス要件に合わせて調整- 定期的に削除件数を確認し、必要ならインデックスや分割テーブルでパフォーマンスを最適化
参考
- Laravel Sanctum Docs → “Prune expired tokens”
- Laravel 12.x Task Scheduler Docs
- GitHub Issue #384（
expires_atが無視される件）
これで、sanctum:prune-expired を実務で効果的に活用できるはずです。 Happy coding!
