Laravel – リファレンス
backup:list
- カテゴリ: artisan
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / コマンド:
php artisan backup:list - 関連: backup:run, backup:clean, backup:check, backup:verify
- 変更履歴: v5.0.0 追加（Spatie Laravel Backup 5.x）
要点（TL;DR）
- バックアップディスク上のすべてのバックアップファイルを一覧表示する
php artisan backup:list（オプションで--disk=）- ディスク設定や権限に注意
概要
backup:list は Spatie Laravel Backup パッケージが提供する Artisan コマンドで、設定済みのバックアップディスクに保存されている全バックアップファイルを一覧で表示します。デプロイ前のバックアップ確認や監査時に有効です。
構文 / シグネチャ
// src/Console/BackupListCommand.php
protected $signature = 'backup:list {--disk= : The disk name to list backups from.}';
引数（表）
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| disk | string | いいえ | null |
バックアップディスク名（複数指定可） |
戻り値
void（標準出力に一覧を表示）
例外/副作用
- 例外：
RuntimeException（ディスクが見つからない／アクセス不可） - 副作用：読み取り専用でファイル情報を取得するだけ、データ変更はない
使用例
最小例
php artisan backup:list
実務例
# すべてのディスクを一覧
php artisan backup:list
# 特定ディスク（local）のみ
php artisan backup:list --disk=local
実務では、定期ジョブでバックアップ状態を確認し、監査ログに出力するケースが多いです。
よくある落とし穴・注意
- ディスク設定忘れ：
config/backup.phpにdisksが無いとエラー - 権限不足：ディスク上のファイルに読み取り権限が無いと空リストになる
- パス不一致：
destinationが正しく設定されていないとファイルが見つからない - 大量ファイル：数千件あると表示に時間がかかる場合がある（
--quietで抑制可能）
代替・関連APIとの比較
| コマンド | 目的 | 主要な違い |
|---|---|---|
backup:run |
バックアップ生成 | 実際にデータを圧縮して保存 |
backup:clean |
古いバックアップ削除 | ファイルの削除のみ |
backup:check |
バックアップ整合性確認 | 生成済みバックアップの整合性をチェック |
backup:verify |
バックアップ検証 | データベースの内容を検証 |
backup:list は「見える化」を目的とし、他のコマンドは「実際の操作」を行います。
テスト例（Pest）
use Illuminate\Support\Facades\Artisan;
it('lists backups on all disks', function () {
// ダミーのディスク設定
config(['backup.dbs' => ['local']]);
// コマンド実行
$this->artisan('backup:list')
->expectsOutput('Backup files on disk "local":')
->assertSuccessful();
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
Could not find any backups |
バックアップディレクトリが空 | バックアップが作成済みか確認、ディレクトリパスをチェック |
Disk "s3" does not exist |
設定ファイルにディスクが無い | config/backup.php の disks に追加 |
Permission denied |
ファイル/ディレクトリの権限不足 | chmod, chown で読み取り権限を付与 |
