ファイルストレージ - Knowledge of Laravel

ファイルストレージとは

Laravelは Flysystem というPHPパッケージをベースにした、強力なファイルシステム抽象化レイヤーを提供しています。ローカルディスク・SFTP・Amazon S3など、異なるストレージバックエンドを同じAPIで操作できるため、環境に応じて切り替えてもコードの変更が不要です。

ドライバーを切り替えてもコードは変わりません。開発環境ではローカル、本番環境ではS3、という構成が簡単に実現できます。

設定

ファイルシステムの設定は config/filesystems.php にまとめられています。ここで「ディスク」を定義します。ディスクとは、特定のドライバーとストレージ場所の組み合わせです。主なドライバーは次のとおりです。

ドライバー	用途
`local`	サーバーのローカルファイルシステム
`public`	Web公開用のローカルディスク
`s3`	Amazon S3（またはS3互換サービス）
`sftp`	SFTPサーバー
`ftp`	FTPサーバー
`read-through`	移行中のプライマリ・フォールバックディスク

localドライバー

local ドライバーを使うと、filesystems 設定の root ディレクトリを基準にファイルを操作します。デフォルトでは storage/app/private が root です。

use Illuminate\Support\Facades\Storage;

Storage::disk('local')->put('example.txt', 'Contents');
// storage/app/private/example.txt に書き込まれる

デフォルトディスクの変更

FILESYSTEM_DISK 環境変数でデフォルトのディスクを切り替えられます。

FILESYSTEM_DISK=s3

publicディスクとシンボリックリンク

public ディスクはWebからアクセスできるファイルを置くためのものです。デフォルトでは storage/app/public ディレクトリに保存されます。 Webサーバーからアクセスできるようにするには、public/storage から storage/app/public へのシンボリックリンクを作成します。

シンボリックリンクの作成

php artisan storage:link

ファイルのURLを取得

シンボリックリンク作成後、asset ヘルパーでURLを生成できます。

echo asset('storage/file.txt');

追加のシンボリックリンクが必要な場合、config/filesystems.php の links 配列で設定できます。

'links' => [
    public_path('storage') => storage_path('app/public'),
    public_path('images') => storage_path('app/images'),
],

シンボリックリンクを削除するには storage:unlink を使います。

php artisan storage:unlink

Storageファサードの基本操作

ファイルの読み込み

use Illuminate\Support\Facades\Storage;

// ファイルの内容を文字列で取得
$contents = Storage::get('file.jpg');

// JSONファイルを取得してデコード
$data = Storage::json('orders.json');

// ファイルの存在確認
if (Storage::exists('file.jpg')) {
    // ファイルが存在する
}

// ファイルが存在しないことを確認
if (Storage::missing('file.jpg')) {
    // ファイルが存在しない
}

ファイルの書き込み

// ファイルに書き込む
Storage::put('file.jpg', $contents);

// リソースをストリームとして書き込む
Storage::put('file.jpg', $resource);

// 先頭・末尾に追記する
Storage::prepend('file.log', 'Prepended Text');
Storage::append('file.log', 'Appended Text');

// ファイルのコピーと移動
Storage::copy('old/file.jpg', 'new/file.jpg');
Storage::move('old/file.jpg', 'new/file.jpg');

put が失敗した場合、デフォルトでは false を返します。ディスク設定で 'throw' => true とすることで、例外をスローさせることもできます。

ファイルの削除

// 単一ファイルの削除
Storage::delete('file.jpg');

// 複数ファイルの削除
Storage::delete(['file.jpg', 'file2.jpg']);

// 特定ディスクのファイルを削除
Storage::disk('s3')->delete('path/file.jpg');

ファイルのダウンロードレスポンス

// ブラウザにダウンロードを促すレスポンスを返す
return Storage::download('file.jpg');

// ファイル名とヘッダーを指定する場合
return Storage::download('file.jpg', 'my-file.jpg', $headers);

URLの生成

通常のURL

use Illuminate\Support\Facades\Storage;

$url = Storage::url('file.jpg');

local ドライバーでは /storage/file.jpg のような相対URLを返します。 s3 ドライバーでは完全なリモートURLを返します。

一時URL（Temporary URL）

期限付きのURLを生成したい場合は temporaryUrl メソッドを使います。 local と s3 ドライバーで利用できます。

use Illuminate\Support\Facades\Storage;

$url = Storage::temporaryUrl(
    'file.jpg',
    now()->plus(minutes: 5)
);

S3では追加のリクエストパラメータも指定できます。

$url = Storage::temporaryUrl(
    'file.jpg',
    now()->plus(minutes: 5),
    [
        'ResponseContentType' => 'application/octet-stream',
        'ResponseContentDisposition' => 'attachment; filename=file.jpg',
    ]
);

一時アップロードURLが必要な場合は temporaryUploadUrl メソッドを使います。クライアントサイドから直接S3へアップロードするようなサーバーレス構成で活用できます。

['url' => $url, 'headers' => $headers] = Storage::temporaryUploadUrl(
    'file.jpg', now()->plus(minutes: 5)
);

ファイルのアップロード

ユーザーがフォームからアップロードしたファイルを保存する一般的なパターンです。

storeメソッド（ファイル名を自動生成）

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserAvatarController extends Controller
{
    public function update(Request $request): string
    {
        // ファイル名はMIMEタイプから拡張子を判定して自動生成される
        $path = $request->file('avatar')->store('avatars');

        return $path;
    }
}

storeAsメソッド（ファイル名を指定）

$path = $request->file('avatar')->storeAs(
    'avatars',
    $request->user()->id
);

ディスクを指定してアップロード

// s3ディスクに保存
$path = $request->file('avatar')->store(
    'avatars/' . $request->user()->id,
    's3'
);

Storageファサード経由でアップロード

use Illuminate\Support\Facades\Storage;

// ファイル名を自動生成
$path = Storage::putFile('avatars', $request->file('avatar'));

// ファイル名を指定
$path = Storage::putFileAs(
    'avatars',
    $request->file('avatar'),
    $request->user()->id
);

getClientOriginalName() や getClientOriginalExtension() はユーザーが改ざんできるため安全ではありません。ファイル名には hashName()、拡張子には extension() を使ってください。

$file = $request->file('avatar');

$name = $file->hashName();   // ユニークなランダム名を生成
$extension = $file->extension(); // MIMEタイプから拡張子を判定

ファイルの可視性（Visibility）

Flysystemでは、ファイルの公開・非公開を visibility で管理します。

use Illuminate\Support\Facades\Storage;

// 書き込み時に可視性を指定
Storage::put('file.jpg', $contents, 'public');

// 可視性の取得と変更
$visibility = Storage::getVisibility('file.jpg');
Storage::setVisibility('file.jpg', 'public');

アップロードしたファイルを公開状態で保存する場合は storePublicly を使います。

$path = $request->file('avatar')->storePublicly('avatars', 's3');

複数ディスクの使い分け

disk メソッドで操作するディスクを切り替えられます。

// デフォルトディスクに保存
Storage::put('avatars/1', $content);

// s3ディスクに保存
Storage::disk('s3')->put('avatars/1', $content);

// オンデマンドでディスクを作成
$disk = Storage::build([
    'driver' => 'local',
    'root' => '/path/to/root',
]);
$disk->put('image.jpg', $content);

Read-throughディスク

read-through ディスクを使うと、ダウンタイムなしでファイルを別のディスクへ移行できます。ファイルの読み込み時にまずプライマリディスクを確認し、そこに存在しない場合はフォールバックディスクから読み込んで、以降のリクエストに備えてプライマリディスクへコピーします。

'assets' => [
    'driver' => 'read-through',
    'primary' => 's3',
    'fallback' => 'legacy-s3',
],

書き込みとディレクトリ一覧の取得はプライマリディスクを対象にします。ファイルの存在確認とメタデータの取得は両方のディスクを確認しますが、ファイルをプライマリディスクへコピーしません。フォールバックディスクからプライマリディスクへのコピーに失敗しても、デフォルトでは読み込み自体は成功します。コピーの失敗時に例外をスローするには、throw_on_promotion_failure を true に設定してください。

クラウドストレージ（S3）の設定

パッケージのインストール

composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies

環境変数の設定

.env ファイルにS3の認証情報を設定します。

AWS_ACCESS_KEY_ID=your-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name
AWS_USE_PATH_STYLE_ENDPOINT=false

DigitalOcean Spaces、Cloudflare R2、Vultr Object StorageなどのS3互換サービスも s3 ドライバーで利用できます。 endpoint オプションにサービスのエンドポイントURLを指定してください。

'endpoint' => env('AWS_ENDPOINT', 'https://your-endpoint.example.com'),

ファイルメタデータの取得

use Illuminate\Support\Facades\Storage;

// ファイルサイズ（バイト）
$size = Storage::size('file.jpg');

// 最終更新日時（UNIXタイムスタンプ）
$time = Storage::lastModified('file.jpg');

// MIMEタイプ
$mime = Storage::mimeType('file.jpg');

// ファイルの絶対パス（localドライバー）
$path = Storage::path('file.jpg');

ディレクトリ操作

use Illuminate\Support\Facades\Storage;

// ディレクトリ内のファイル一覧
$files = Storage::files($directory);

// サブディレクトリを含むファイル一覧
$files = Storage::allFiles($directory);

// ディレクトリ一覧
$directories = Storage::directories($directory);

// ディレクトリの作成
Storage::makeDirectory($directory);

// ディレクトリとその中のファイルをまとめて削除
Storage::deleteDirectory($directory);

テスト

Storage::fake() を使うと、実際のディスクに触れることなくファイル操作のテストが書けます。

use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;

test('アバターをアップロードできる', function () {
    Storage::fake('avatars');

    $file = UploadedFile::fake()->image('avatar.jpg');

    $this->post('/user/avatar', ['avatar' => $file]);

    // ファイルが保存されたことを確認
    Storage::disk('avatars')->assertExists('avatar.jpg');

    // ファイルが保存されていないことを確認
    Storage::disk('avatars')->assertMissing('other.jpg');
});

UploadedFile::fake()->image() を使うには、PHPの GD拡張が必要です。

実践的なユースケース: プロフィール画像のアップロード

バリデーション・保存・DBへのパス記録を組み合わせた実践的なコントローラーの例です。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Storage;

class ProfileController extends Controller
{
    public function updateAvatar(Request $request): RedirectResponse
    {
        $request->validate([
            'avatar' => ['required', 'image', 'max:2048'],
        ]);

        $user = $request->user();

        // 既存のアバターを削除
        if ($user->avatar_path) {
            Storage::disk('public')->delete($user->avatar_path);
        }

        // 新しいアバターを保存
        $path = $request->file('avatar')->store('avatars', 'public');

        // パスをDBに保存
        $user->update(['avatar_path' => $path]);

        return back()->with('status', 'avatar-updated');
    }
}

テンプレートでは Storage::url() を使ってURLを取得します。

<img src="{{ Storage::disk('public')->url($user->avatar_path) }}" alt="アバター">

​ファイルストレージとは

​設定

​localドライバー

​デフォルトディスクの変更

​publicディスクとシンボリックリンク

​Storageファサードの基本操作

​ファイルの読み込み

​ファイルの書き込み

​ファイルの削除

​ファイルのダウンロードレスポンス

​URLの生成

​通常のURL

​一時URL（Temporary URL）

​ファイルのアップロード

​storeメソッド（ファイル名を自動生成）

​storeAsメソッド（ファイル名を指定）

​ディスクを指定してアップロード

​Storageファサード経由でアップロード

​ファイルの可視性（Visibility）

​複数ディスクの使い分け

​Read-throughディスク

​クラウドストレージ（S3）の設定

​パッケージのインストール

​環境変数の設定

​ファイルメタデータの取得

​ディレクトリ操作

​テスト

​実践的なユースケース: プロフィール画像のアップロード

ファイルストレージとは

設定

localドライバー

デフォルトディスクの変更

publicディスクとシンボリックリンク

Storageファサードの基本操作

ファイルの読み込み

ファイルの書き込み

ファイルの削除

ファイルのダウンロードレスポンス

URLの生成

通常のURL

一時URL（Temporary URL）

ファイルのアップロード

storeメソッド（ファイル名を自動生成）

storeAsメソッド（ファイル名を指定）

ディスクを指定してアップロード

Storageファサード経由でアップロード

ファイルの可視性（Visibility）

複数ディスクの使い分け

Read-throughディスク

クラウドストレージ（S3）の設定

パッケージのインストール

環境変数の設定

ファイルメタデータの取得

ディレクトリ操作

テスト

実践的なユースケース: プロフィール画像のアップロード