ファイルストレージ

イントロダクション
設定
ディスクインスタンスの取得
- オンデマンドディスク
ファイルの取得
ファイルの保存
ファイルの削除
ディレクトリ
テスト
カスタムファイルシステム

イントロダクション

Laravelは、Frank de Jonge氏による素晴らしいFlysystem PHPパッケージのおかげで、強力なファイルシステムの抽象化を提供しています。Laravel Flysystemの統合は、ローカルファイルシステム、SFTP、Amazon S3を操作するためのシンプルなドライバを提供します。さらに良いことに、各システムでAPIは同じままであるため、ローカルの開発マシンと本番サーバ間でこれらのストレージオプションを切り替えるのは驚くほど簡単です。

設定

Laravelのファイルシステム設定ファイルは、config/filesystems.phpにあります。このファイル内で、ファイルシステムの「ディスク」をすべて設定できます。各ディスクは、特定のストレージドライバとストレージの場所を表します。サポートされている各ドライバの設定例が設定ファイルに含まれているため、ストレージの好みと認証情報に合わせて設定を変更できます。

localドライバはLaravelアプリケーションを実行しているサーバ上にローカルで保存されているファイルを操作し、s3ドライバはAmazonのS3クラウドストレージサービスへ書き込むために使用します。

好きなだけディスクを設定でき、同じドライバを使用する複数のディスクを持つことも可能です。

ローカルドライバ

localドライバを使用する場合、すべてのファイル操作はfilesystems設定ファイルで定義されているrootディレクトリからの相対パスになります。デフォルトでこの値は、storage/app/privateディレクトリに設定されています。したがって、以下のメソッドはstorage/app/private/example.txtに書き込みます。

1use Illuminate\Support\Facades\Storage;
2 
3Storage::disk('local')->put('example.txt', 'Contents');

use Illuminate\Support\Facades\Storage;

Storage::disk('local')->put('example.txt', 'Contents');

公開ディスク

アプリケーションのfilesystems設定ファイルに含まれているpublicディスクは、公開するファイルを対象としています。デフォルトでpublicディスクはlocalドライバを使用し、そのファイルをstorage/app/publicに保存します。

publicディスクでlocalドライバを使用していて、これらのファイルをWebからアクセスできるようにしたい場合は、ソースディレクトリstorage/app/publicからターゲットディレクトリpublic/storageへのシンボリックリンクを作成する必要があります。

シンボリックリンクを作成するには、storage:link Artisanコマンドを使用します。

1php artisan storage:link

php artisan storage:link

ファイルが保存され、シンボリックリンクが作成されると、assetヘルパを使用してファイルへのURLを作成できます。

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

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

filesystems設定ファイルで、追加のシンボリックリンクを設定できます。storage:linkコマンドを実行すると、設定した各リンクが作成されます。

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

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

storage:unlinkコマンドは、設定したシンボリックリンクを破棄するために使用します。

1php artisan storage:unlink

php artisan storage:unlink

ドライバの前提条件

S3ドライバの設定

S3ドライバを使用する前に、Composerパッケージマネージャを介してFlysystem S3パッケージをインストールする必要があります。

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

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

S3ディスクの設定配列は、config/filesystems.php設定ファイルにあります。通常、S3情報と認証情報は、config/filesystems.php設定ファイルで参照されている以下の環境変数を使用して設定します。

1AWS_ACCESS_KEY_ID=<your-key-id>
2AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
3AWS_DEFAULT_REGION=us-east-1
4AWS_BUCKET=<your-bucket-name>
5AWS_USE_PATH_STYLE_ENDPOINT=false

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

便宜上、これらの環境変数はAWS CLIが使用する命名規則と一致しています。

FTPドライバの設定

FTPドライバを使用する前に、Composerパッケージマネージャを介してFlysystem FTPパッケージをインストールする必要があります。

1composer require league/flysystem-ftp "^3.0"

composer require league/flysystem-ftp "^3.0"

LaravelのFlysystem統合はFTPでうまく機能します。しかし、フレームワークのデフォルトのconfig/filesystems.php設定ファイルには、サンプル設定が含まれていません。FTPファイルシステムを設定する必要がある場合は、以下の設定例を使用できます。

 1'ftp' => [
 2    'driver' => 'ftp',
 3    'host' => env('FTP_HOST'),
 4    'username' => env('FTP_USERNAME'),
 5    'password' => env('FTP_PASSWORD'),
 6 
 7    // Optional FTP Settings...
 8    // 'port' => env('FTP_PORT', 21),
 9    // 'root' => env('FTP_ROOT'),
10    // 'passive' => true,
11    // 'ssl' => true,
12    // 'timeout' => 30,
13],

'ftp' => [
    'driver' => 'ftp',
    'host' => env('FTP_HOST'),
    'username' => env('FTP_USERNAME'),
    'password' => env('FTP_PASSWORD'),

    // Optional FTP Settings...
    // 'port' => env('FTP_PORT', 21),
    // 'root' => env('FTP_ROOT'),
    // 'passive' => true,
    // 'ssl' => true,
    // 'timeout' => 30,
],

SFTPドライバの設定

SFTPドライバを使用する前に、Composerパッケージマネージャを介してFlysystem SFTPパッケージをインストールする必要があります。

1composer require league/flysystem-sftp-v3 "^3.0"

composer require league/flysystem-sftp-v3 "^3.0"

LaravelのFlysystem統合はSFTPでうまく機能します。しかし、フレームワークのデフォルトのconfig/filesystems.php設定ファイルには、サンプル設定が含まれていません。SFTPファイルシステムを設定する必要がある場合は、以下の設定例を使用できます。

 1'sftp' => [
 2    'driver' => 'sftp',
 3    'host' => env('SFTP_HOST'),
 4 
 5    // Settings for basic authentication...
 6    'username' => env('SFTP_USERNAME'),
 7    'password' => env('SFTP_PASSWORD'),
 8 
 9    // Settings for SSH key based authentication with encryption password...
10    'privateKey' => env('SFTP_PRIVATE_KEY'),
11    'passphrase' => env('SFTP_PASSPHRASE'),
12 
13    // Settings for file / directory permissions...
14    'visibility' => 'private', // `private` = 0600, `public` = 0644
15    'directory_visibility' => 'private', // `private` = 0700, `public` = 0755
16 
17    // Optional SFTP Settings...
18    // 'hostFingerprint' => env('SFTP_HOST_FINGERPRINT'),
19    // 'maxTries' => 4,
20    // 'passphrase' => env('SFTP_PASSPHRASE'),
21    // 'port' => env('SFTP_PORT', 22),
22    // 'root' => env('SFTP_ROOT', ''),
23    // 'timeout' => 30,
24    // 'useAgent' => true,
25],

'sftp' => [
    'driver' => 'sftp',
    'host' => env('SFTP_HOST'),

    // Settings for basic authentication...
    'username' => env('SFTP_USERNAME'),
    'password' => env('SFTP_PASSWORD'),

    // Settings for SSH key based authentication with encryption password...
    'privateKey' => env('SFTP_PRIVATE_KEY'),
    'passphrase' => env('SFTP_PASSPHRASE'),

    // Settings for file / directory permissions...
    'visibility' => 'private', // `private` = 0600, `public` = 0644
    'directory_visibility' => 'private', // `private` = 0700, `public` = 0755

    // Optional SFTP Settings...
    // 'hostFingerprint' => env('SFTP_HOST_FINGERPRINT'),
    // 'maxTries' => 4,
    // 'passphrase' => env('SFTP_PASSPHRASE'),
    // 'port' => env('SFTP_PORT', 22),
    // 'root' => env('SFTP_ROOT', ''),
    // 'timeout' => 30,
    // 'useAgent' => true,
],

スコープ付き読み取り専用ファイルシステム

スコープ付きディスクを使用すると、すべてのパスに特定のパスプレフィックスが自動的に付加されるファイルシステムを定義できます。スコープ付きファイルシステムディスクを作成する前に、Composerパッケージマネージャを介して追加のFlysystemパッケージをインストールする必要があります。

1composer require league/flysystem-path-prefixing "^3.0"

composer require league/flysystem-path-prefixing "^3.0"

scopedドライバを利用するディスクを定義することにより、既存のファイルシステムディスクのパススコープ付きインスタンスを作成できます。たとえば、既存のs3ディスクを特定のパスプレフィックスにスコープするディスクを作成し、その後、スコープ付きディスクを使用したすべてのファイル操作で指定のプレフィックスが使用されます。

1's3-videos' => [
2    'driver' => 'scoped',
3    'disk' => 's3',
4    'prefix' => 'path/to/videos',
5],

's3-videos' => [
    'driver' => 'scoped',
    'disk' => 's3',
    'prefix' => 'path/to/videos',
],

「読み取り専用」ディスクを使用すると、書き込み操作を許可しないファイルシステムディスクを作成できます。read-only設定オプションを使用する前に、Composerパッケージマネージャを介して追加のFlysystemパッケージをインストールする必要があります。

1composer require league/flysystem-read-only "^3.0"

composer require league/flysystem-read-only "^3.0"

次に、１つ以上のディスク設定配列にread-only設定オプションを含めることができます。

1's3-videos' => [
2    'driver' => 's3',
3    // ...
4    'read-only' => true,
5],

's3-videos' => [
    'driver' => 's3',
    // ...
    'read-only' => true,
],

Amazon S3互換ファイルシステム

デフォルトでは、アプリケーションのfilesystems設定ファイルにs3ディスクの設定が含まれています。このディスクをAmazon S3との対話に使用するだけでなく、MinIO、DigitalOcean Spaces、Vultr Object Storage、Cloudflare R2、Hetzner Cloud StorageなどのS3互換のファイルストレージサービスと対話するためにも使用できます。

通常、ディスクの認証情報を利用予定のサービスの認証情報と一致するように更新した後、endpoint設定オプションの値を更新するだけで済みます。このオプションの値は、通常、AWS_ENDPOINT環境変数を介して定義します。

1'endpoint' => env('AWS_ENDPOINT', 'https://minio:9000'),

'endpoint' => env('AWS_ENDPOINT', 'https://minio:9000'),

MinIO

MinIOを使用する際に、LaravelのFlysystem統合が適切なURLを生成するためには、AWS_URL環境変数をアプリケーションのローカルURLと一致させ、URLパスにバケット名を含めるように定義する必要があります。

1AWS_URL=https://:9000/local

AWS_URL=https://:9000/local

クライアントからendpointにアクセスできない場合、temporaryUrlメソッドを介して一時ストレージURLを生成すると、MinIO使用時に機能しない可能性があります。

ディスクインスタンスの取得

Storageファサードを使用して、設定済みのディスクとやり取りできます。たとえば、ファサードのputメソッドを使用して、デフォルトのディスクにアバターを保存できます。diskメソッドを最初に呼び出さずにStorageファサードでメソッドを呼び出すと、メソッドは自動的にデフォルトのディスクに渡されます。

1use Illuminate\Support\Facades\Storage;
2 
3Storage::put('avatars/1', $content);

use Illuminate\Support\Facades\Storage;

Storage::put('avatars/1', $content);

アプリケーションが複数のディスクと対話する場合は、Storageファサードでdiskメソッドを使用して、特定のディスク上のファイルを操作できます。

1Storage::disk('s3')->put('avatars/1', $content);

Storage::disk('s3')->put('avatars/1', $content);

オンデマンドディスク

アプリケーションのfilesystems設定ファイルに実際には存在しない設定を使用して、実行時にディスクを作成したい場合があるでしょう。これを実現するには、Storageファサードのbuildメソッドに設定配列を渡します。

1use Illuminate\Support\Facades\Storage;
2 
3$disk = Storage::build([
4    'driver' => 'local',
5    'root' => '/path/to/root',
6]);
7 
8$disk->put('image.jpg', $content);

use Illuminate\Support\Facades\Storage;

$disk = Storage::build([
    'driver' => 'local',
    'root' => '/path/to/root',
]);

$disk->put('image.jpg', $content);

ファイルの取得

getメソッドは、ファイルの内容を取得するために使用します。メソッドはファイルの素の文字列コンテンツを返します。すべてのファイルパスは、ディスクの「ルート」の場所からの相対パスで指定する必要があることに注意してください。

1$contents = Storage::get('file.jpg');

$contents = Storage::get('file.jpg');

取得するファイルにJSONが含まれている場合は、jsonメソッドを使用してファイルを取得し、その内容をデコードできます。

1$orders = Storage::json('orders.json');

$orders = Storage::json('orders.json');

existsメソッドは、ディスク上にファイルが存在するかどうかを判断するために使用します。

1if (Storage::disk('s3')->exists('file.jpg')) {
2    // ...
3}

if (Storage::disk('s3')->exists('file.jpg')) {
    // ...
}

missingメソッドは、ディスクにファイルが存在しないことを判断するために使用します。

1if (Storage::disk('s3')->missing('file.jpg')) {
2    // ...
3}

if (Storage::disk('s3')->missing('file.jpg')) {
    // ...
}

ファイルのダウンロード

downloadメソッドは、ユーザーのブラウザに指定パスのファイルをダウンロードさせるレスポンスを生成するために使用します。downloadメソッドは、メソッドの第２引数にファイル名を受け取ります。これにより、ファイルをダウンロードするユーザーに表示されるファイル名が決まります。最後に、メソッドの第３引数としてHTTPヘッダの配列を渡すことができます。

1return Storage::download('file.jpg');
2 
3return Storage::download('file.jpg', $name, $headers);

return Storage::download('file.jpg');

return Storage::download('file.jpg', $name, $headers);

ファイルURL

urlメソッドを使用して、指定ファイルのURLを取得できます。localドライバを使用している場合、これは通常、指定パスに/storageを付け、ファイルへの相対URLを返します。s3ドライバを使用している場合は、完全修飾リモートURLが返されます。

1use Illuminate\Support\Facades\Storage;
2 
3$url = Storage::url('file.jpg');

use Illuminate\Support\Facades\Storage;

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

localドライバを使用する場合、公開する必要のあるすべてのファイルはstorage/app/publicディレクトリに配置する必要があります。さらに、storage/app/publicディレクトリを指すpublic/storageにシンボリックリンクを作成する必要があります。

localドライバを使用する場合、urlの戻り値はURLエンコードされません。このため、常に有効なURLを作成する名前を使用してファイルを保存することをお勧めします。

URLホストのカスタマイズ

Storageファサードを使用して生成されるURLのホストを変更したい場合は、ディスクの設定配列にurlオプションを追加または変更します。

1'public' => [
2    'driver' => 'local',
3    'root' => storage_path('app/public'),
4    'url' => env('APP_URL').'/storage',
5    'visibility' => 'public',
6    'throw' => false,
7],

'public' => [
    'driver' => 'local',
    'root' => storage_path('app/public'),
    'url' => env('APP_URL').'/storage',
    'visibility' => 'public',
    'throw' => false,
],

一時URL

temporaryUrlメソッドを使用して、localおよびs3ドライバを使用して保存されているファイルへ一時的なURLを作成できます。このメソッドは、パスとURLの有効期限を指定するDateTimeインスタンスを引数に取ります。

1use Illuminate\Support\Facades\Storage;
2 
3$url = Storage::temporaryUrl(
4    'file.jpg', now()->addMinutes(5)
5);

use Illuminate\Support\Facades\Storage;

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

ローカル一時URLの有効化

一時URLのサポートがlocalドライバに導入される前にアプリケーションの開発を開始した場合、ローカル一時URLを有効にする必要がある場合があります。そのためには、config/filesystems.php設定ファイル内のlocalディスクの設定配列にserveオプションを追加してください。

1'local' => [
2    'driver' => 'local',
3    'root' => storage_path('app/private'),
4    'serve' => true, 
5    'throw' => false,
6],

'local' => [
    'driver' => 'local',
    'root' => storage_path('app/private'),
    'serve' => true,
    'throw' => false,
],

S3リクエストパラメータ

追加のS3リクエストパラメータを指定する必要がある場合は、リクエストパラメータの配列をtemporaryUrlメソッドの第３引数として渡してください。

1$url = Storage::temporaryUrl(
2    'file.jpg',
3    now()->addMinutes(5),
4    [
5        'ResponseContentType' => 'application/octet-stream',
6        'ResponseContentDisposition' => 'attachment; filename=file2.jpg',
7    ]
8);

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

一時URLのカスタマイズ

特定のストレージディスクで一時URLがどのように作成されるかをカスタマイズする必要がある場合は、buildTemporaryUrlsUsingメソッドを使用できます。たとえば、これは通常、一時URLをサポートしていないディスクを介して保存されたファイルをダウンロードできるコントローラがある場合に役立ちます。通常、このメソッドはサービスプロバイダのbootメソッドから呼び出す必要があります。

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use DateTime;
 6use Illuminate\Support\Facades\Storage;
 7use Illuminate\Support\Facades\URL;
 8use Illuminate\Support\ServiceProvider;
 9 
10class AppServiceProvider extends ServiceProvider
11{
12    /**
13     * Bootstrap any application services.
14     */
15    public function boot(): void
16    {
17        Storage::disk('local')->buildTemporaryUrlsUsing(
18            function (string $path, DateTime $expiration, array $options) {
19                return URL::temporarySignedRoute(
20                    'files.download',
21                    $expiration,
22                    array_merge($options, ['path' => $path])
23                );
24            }
25        );
26    }
27}

<?php

namespace App\Providers;

use DateTime;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Facades\URL;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Storage::disk('local')->buildTemporaryUrlsUsing(
            function (string $path, DateTime $expiration, array $options) {
                return URL::temporarySignedRoute(
                    'files.download',
                    $expiration,
                    array_merge($options, ['path' => $path])
                );
            }
        );
    }
}

一時アップロードURL

一時アップロードURLを生成する機能は、s3ドライバでのみサポートされています。

クライアントサイドのアプリケーションからファイルを直接アップロードするために使用できる一時的なURLを生成する必要がある場合は、temporaryUploadUrlメソッドを使用できます。このメソッドは、パスとURLの有効期限を指定するDateTimeインスタンスを受け入れます。temporaryUploadUrlメソッドは連想配列を返し、これをアップロードURLとアップロードリクエストに含めるべきヘッダに分解できます。

1use Illuminate\Support\Facades\Storage;
2 
3['url' => $url, 'headers' => $headers] = Storage::temporaryUploadUrl(
4    'file.jpg', now()->addMinutes(5)
5);

use Illuminate\Support\Facades\Storage;

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

このメソッドは主に、クライアントサイドのアプリケーションがAmazon S3などのクラウドストレージシステムにファイルを直接アップロードする必要があるサーバレス環境で役立ちます。

ファイルメタデータ

Laravelはファイルの読み書きに加えて、ファイル自体の情報も提供します。たとえば、sizeメソッドを使用して、ファイルのサイズをバイト単位で取得できます。

1use Illuminate\Support\Facades\Storage;
2 
3$size = Storage::size('file.jpg');

use Illuminate\Support\Facades\Storage;

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

lastModifiedメソッドは、ファイルが最後に変更されたときのUNIXタイムスタンプを返します。

1$time = Storage::lastModified('file.jpg');

$time = Storage::lastModified('file.jpg');

指定されたファイルのMIMEタイプは、mimeTypeメソッドを介して取得できます。

1$mime = Storage::mimeType('file.jpg');

$mime = Storage::mimeType('file.jpg');

ファイルパス

pathメソッドを使用して、指定ファイルのパスを取得できます。localドライバを使用している場合、これはファイルへの絶対パスを返します。s3ドライバを使用している場合、このメソッドはS3バケット内のファイルへの相対パスを返します。

1use Illuminate\Support\Facades\Storage;
2 
3$path = Storage::path('file.jpg');

use Illuminate\Support\Facades\Storage;

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

ファイルの保存

putメソッドは、ディスクにファイルの内容を保存するために使用できます。PHPのresourceをputメソッドに渡すこともでき、これはFlysystemの基盤となるストリームサポートを使用します。すべてのファイルパスは、ディスクに設定された「ルート」の場所からの相対パスで指定する必要があることに注意してください。

1use Illuminate\Support\Facades\Storage;
2 
3Storage::put('file.jpg', $contents);
4 
5Storage::put('file.jpg', $resource);

use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents);

Storage::put('file.jpg', $resource);

書き込みの失敗

putメソッド（または他の「書き込み」操作）がディスクにファイルを書き込めなかった場合、falseが返されます。

1if (! Storage::put('file.jpg', $contents)) {
2    // The file could not be written to disk...
3}

if (! Storage::put('file.jpg', $contents)) {
    // The file could not be written to disk...
}

必要であれば、ファイルシステムディスクの設定配列内でthrowオプションを定義できます。このオプションをtrueとして定義すると、putなどの「書き込み」メソッドは、書き込み操作が失敗したときにLeague\Flysystem\UnableToWriteFileのインスタンスを投げます。

1'public' => [
2    'driver' => 'local',
3    // ...
4    'throw' => true,
5],

'public' => [
    'driver' => 'local',
    // ...
    'throw' => true,
],

ファイルへの追記と前置

prependメソッドとappendメソッドを使用すると、ファイルの先頭または末尾に書き込むことができます。

1Storage::prepend('file.log', 'Prepended Text');
2 
3Storage::append('file.log', 'Appended Text');

Storage::prepend('file.log', 'Prepended Text');

Storage::append('file.log', 'Appended Text');

ファイルのコピーと移動

copyメソッドは、既存のファイルをディスク上の新しい場所にコピーするために使用し、moveメソッドは既存のファイルの名前を変更したり、新しい場所に移動したりするために使用します。

1Storage::copy('old/file.jpg', 'new/file.jpg');
2 
3Storage::move('old/file.jpg', 'new/file.jpg');

Storage::copy('old/file.jpg', 'new/file.jpg');

Storage::move('old/file.jpg', 'new/file.jpg');

自動ストリーミング

ファイルをストレージにストリーミングすると、メモリ使用量を大幅に削減できます。Laravelが特定のファイルをストレージの場所に自動的にストリーミング管理するようにしたい場合は、putFileまたはputFileAsメソッドを使用できます。このメソッドは、Illuminate\Http\FileまたはIlluminate\Http\UploadedFileインスタンスのいずれかを受け入れ、ファイルを目的の場所に自動的にストリーミングします。

1use Illuminate\Http\File;
2use Illuminate\Support\Facades\Storage;
3 
4// Automatically generate a unique ID for filename...
5$path = Storage::putFile('photos', new File('/path/to/photo'));
6 
7// Manually specify a filename...
8$path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

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

// Automatically generate a unique ID for filename...
$path = Storage::putFile('photos', new File('/path/to/photo'));

// Manually specify a filename...
$path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

putFileメソッドについて注意すべき重要な点がいくつかあります。ファイル名ではなく、ディレクトリ名のみを指定したことに注意してください。デフォルトで、putFileメソッドはファイル名として機能する一意のIDを生成します。ファイルの拡張子は、ファイルのMIMEタイプを調べることによって決定されます。ファイルのパスはputFileメソッドによって返されるので、生成されたファイル名を含むパスをデータベースに保存できます。

putFileメソッドとputFileAsメソッドは、保存するファイルの「可視性」を指定する引数も受け入れます。これは、Amazon S3などのクラウドディスクにファイルを保存していて、生成されたURLを介してファイルを公開したい場合に特に便利です。

1Storage::putFile('photos', new File('/path/to/photo'), 'public');

Storage::putFile('photos', new File('/path/to/photo'), 'public');

ファイルアップロード

Webアプリケーションでは、ファイルを保存する最も一般的なユースケースの1つは、写真やドキュメントなどのユーザーがアップロードしたファイルを保存することです。Laravelでは、アップロードされたファイルインスタンスでstoreメソッドを使用して、アップロードされたファイルを非常に簡単に保存できます。アップロードしたファイルを保存したいパスを指定してstoreメソッドを呼び出してください。

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use Illuminate\Http\Request;
 7 
 8class UserAvatarController extends Controller
 9{
10    /**
11     * Update the avatar for the user.
12     */
13    public function update(Request $request): string
14    {
15        $path = $request->file('avatar')->store('avatars');
16 
17        return $path;
18    }
19}

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class UserAvatarController extends Controller
{
    /**
     * Update the avatar for the user.
     */
    public function update(Request $request): string
    {
        $path = $request->file('avatar')->store('avatars');

        return $path;
    }
}

この例には、注意すべき重要な点がいくつかあります。ファイル名ではなく、ディレクトリ名のみを指定したことに注意してください。デフォルトでは、storeメソッドはファイル名として機能する一意のIDを生成します。ファイルの拡張子は、ファイルのMIMEタイプを調べることによって決定されます。ファイルのパスはstoreメソッドによって返されるため、生成されたファイル名を含むパスをデータベースに保存できます。

StorageファサードのputFileメソッドを呼び出して、上記の例と同じファイル保存操作を実行することもできます。

1$path = Storage::putFile('avatars', $request->file('avatar'));

$path = Storage::putFile('avatars', $request->file('avatar'));

ファイル名の指定

保存したファイルにファイル名を自動的に割り当てたくない場合は、storeAsメソッドを使用できます。これは、パス、ファイル名、および（オプションの）ディスクを引数として受け取ります。

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

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

StorageファサードのputFileAsメソッドを使用することもできます。これは、上記の例と同じファイル保存操作を実行します。

1$path = Storage::putFileAs(
2    'avatars', $request->file('avatar'), $request->user()->id
3);

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

印字不能で無効なユニコード文字は、ファイルパスから自動的に削除されます。したがって、Laravelのファイル保存メソッドに渡す前にファイルパスをサニタイズすることをお勧めします。ファイルパスは、League\Flysystem\WhitespacePathNormalizer::normalizePathメソッドを使用して正規化されます。

ディスクの指定

デフォルトでは、このアップロード済みファイルのstoreメソッドはデフォルトのディスクを使用します。別のディスクを指定したい場合は、storeメソッドの第２引数にディスク名を渡してください。

1$path = $request->file('avatar')->store(
2    'avatars/'.$request->user()->id, 's3'
3);

$path = $request->file('avatar')->store(
    'avatars/'.$request->user()->id, 's3'
);

storeAsメソッドを使用している場合は、メソッドの第３引数としてディスク名を渡すことができます。

1$path = $request->file('avatar')->storeAs(
2    'avatars',
3    $request->user()->id,
4    's3'
5);

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

その他のアップロードファイル情報

アップロードしたファイルの元の名前と拡張子を取得したい場合は、getClientOriginalNameメソッドとgetClientOriginalExtensionメソッドを使用して行うことができます。

1$file = $request->file('avatar');
2 
3$name = $file->getClientOriginalName();
4$extension = $file->getClientOriginalExtension();

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

$name = $file->getClientOriginalName();
$extension = $file->getClientOriginalExtension();

しかし、getClientOriginalNameメソッドとgetClientOriginalExtensionメソッドは、ファイル名と拡張子が malicious なユーザーによって改ざんされる可能性があるため、安全ではないと考えられていることに留意してください。このため、通常はhashNameメソッドとextensionメソッドを使用して、指定されたファイルアップロードの名前と拡張子を取得することを推奨します。

1$file = $request->file('avatar');
2 
3$name = $file->hashName(); // Generate a unique, random name...
4$extension = $file->extension(); // Determine the file's extension based on the file's MIME type...

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

$name = $file->hashName(); // Generate a unique, random name...
$extension = $file->extension(); // Determine the file's extension based on the file's MIME type...

ファイルの可視性

LaravelのFlysystem統合では、「可視性」は複数のプラットフォームにわたるファイルパーミッションの抽象化です。ファイルはpublicまたはprivateのいずれかとして宣言できます。ファイルをpublicと宣言すると、そのファイルが通常、他のユーザーがアクセスできるべきであることを示しています。たとえば、S3ドライバを使用している場合、publicファイルのURLを取得できます。

putメソッドを介してファイルを書き込むときに、可視性を設定できます。

1use Illuminate\Support\Facades\Storage;
2 
3Storage::put('file.jpg', $contents, 'public');

use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents, 'public');

ファイルがすでに保存されている場合、その可視性はgetVisibilityメソッドとsetVisibilityメソッドを介して取得および設定できます。

1$visibility = Storage::getVisibility('file.jpg');
2 
3Storage::setVisibility('file.jpg', 'public');

$visibility = Storage::getVisibility('file.jpg');

Storage::setVisibility('file.jpg', 'public');

アップロードされたファイルを操作するときは、storePubliclyメソッドとstorePubliclyAsメソッドを使用して、publicの可視性でアップロードされたファイルを保存できます。

1$path = $request->file('avatar')->storePublicly('avatars', 's3');
2 
3$path = $request->file('avatar')->storePubliclyAs(
4    'avatars',
5    $request->user()->id,
6    's3'
7);

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

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

ローカルファイルと可視性

localドライバを使用する場合、publicの可視性は、ディレクトリの場合は0755、ファイルの場合は0644のパーミッションに変換されます。アプリケーションのfilesystems設定ファイルでパーミッションマッピングを変更できます。

 1 
 2``````php
 3'local' => [
 4    'driver' => 'local',
 5    'root' => storage_path('app'),
 6    'permissions' => [
 7        'file' => [
 8            'public' => 0644,
 9            'private' => 0600,
10        ],
11        'dir' => [
12            'public' => 0755,
13            'private' => 0700,
14        ],
15    ],
16    'throw' => false,
17],


``````php
'local' => [
    'driver' => 'local',
    'root' => storage_path('app'),
    'permissions' => [
        'file' => [
            'public' => 0644,
            'private' => 0600,
        ],
        'dir' => [
            'public' => 0755,
            'private' => 0700,
        ],
    ],
    'throw' => false,
],

ファイルの削除

deleteメソッドは、単一のファイル名または削除するファイルの配列を受け入れます。

1 
2``````php
3use Illuminate\Support\Facades\Storage;
4 
5Storage::delete('file.jpg');
6 
7Storage::delete(['file.jpg', 'file2.jpg']);


``````php
use Illuminate\Support\Facades\Storage;

Storage::delete('file.jpg');

Storage::delete(['file.jpg', 'file2.jpg']);

必要に応じて、ファイルを削除するディスクを指定できます。

1 
2``````php
3use Illuminate\Support\Facades\Storage;
4 
5Storage::disk('s3')->delete('path/file.jpg');


``````php
use Illuminate\Support\Facades\Storage;

Storage::disk('s3')->delete('path/file.jpg');

ディレクトリ

ディレクトリ内のすべてのファイルを取得

filesメソッドは、指定されたディレクトリ内のすべてのファイルの配列を返します。すべてのサブディレクトリを含む、指定されたディレクトリ内のすべてのファイルのリストを取得したい場合は、allFilesメソッドを使用できます。

1use Illuminate\Support\Facades\Storage;
2 
3$files = Storage::files($directory);
4 
5$files = Storage::allFiles($directory);

use Illuminate\Support\Facades\Storage;

$files = Storage::files($directory);

$files = Storage::allFiles($directory);

ディレクトリ内のすべてのディレクトリを取得

directoriesメソッドは、特定のディレクトリ内のすべてのディレクトリの配列を返します。さらに、allDirectoriesメソッドを使用して、特定のディレクトリとそのすべてのサブディレクトリ内にあるすべてのディレクトリのリストを取得できます。

1$directories = Storage::directories($directory);
2 
3$directories = Storage::allDirectories($directory);

$directories = Storage::directories($directory);

$directories = Storage::allDirectories($directory);

ディレクトリの作成

makeDirectoryメソッドは、必要なサブディレクトリを含め、指定されたディレクトリを作成します。

1Storage::makeDirectory($directory);

Storage::makeDirectory($directory);

ディレクトリの削除

最後に、deleteDirectoryメソッドを使用して、ディレクトリとそのすべてのファイルを削除できます。

1Storage::deleteDirectory($directory);

Storage::deleteDirectory($directory);

テスト

Storageファサードのfakeメソッドを使用すると、偽のディスクを簡単に生成でき、Illuminate\Http\UploadedFileクラスのファイル生成ユーティリティと組み合わせることで、ファイルアップロードのテストを大幅に簡素化できます。例：

 1<?php
 2 
 3use Illuminate\Http\UploadedFile;
 4use Illuminate\Support\Facades\Storage;
 5 
 6test('albums can be uploaded', function () {
 7    Storage::fake('photos');
 8 
 9    $response = $this->json('POST', '/photos', [
10        UploadedFile::fake()->image('photo1.jpg'),
11        UploadedFile::fake()->image('photo2.jpg')
12    ]);
13 
14    // Assert one or more files were stored...
15    Storage::disk('photos')->assertExists('photo1.jpg');
16    Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
17 
18    // Assert one or more files were not stored...
19    Storage::disk('photos')->assertMissing('missing.jpg');
20    Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
21 
22    // Assert that the number of files in a given directory matches the expected count...
23    Storage::disk('photos')->assertCount('/wallpapers', 2);
24 
25    // Assert that a given directory is empty...
26    Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
27});

<?php

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

test('albums can be uploaded', function () {
    Storage::fake('photos');

    $response = $this->json('POST', '/photos', [
        UploadedFile::fake()->image('photo1.jpg'),
        UploadedFile::fake()->image('photo2.jpg')
    ]);

    // Assert one or more files were stored...
    Storage::disk('photos')->assertExists('photo1.jpg');
    Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);

    // Assert one or more files were not stored...
    Storage::disk('photos')->assertMissing('missing.jpg');
    Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);

    // Assert that the number of files in a given directory matches the expected count...
    Storage::disk('photos')->assertCount('/wallpapers', 2);

    // Assert that a given directory is empty...
    Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Illuminate\Http\UploadedFile;
 6use Illuminate\Support\Facades\Storage;
 7use Tests\TestCase;
 8 
 9class ExampleTest extends TestCase
10{
11    public function test_albums_can_be_uploaded(): void
12    {
13        Storage::fake('photos');
14 
15        $response = $this->json('POST', '/photos', [
16            UploadedFile::fake()->image('photo1.jpg'),
17            UploadedFile::fake()->image('photo2.jpg')
18        ]);
19 
20        // Assert one or more files were stored...
21        Storage::disk('photos')->assertExists('photo1.jpg');
22        Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
23 
24        // Assert one or more files were not stored...
25        Storage::disk('photos')->assertMissing('missing.jpg');
26        Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
27 
28        // Assert that the number of files in a given directory matches the expected count...
29        Storage::disk('photos')->assertCount('/wallpapers', 2);
30 
31        // Assert that a given directory is empty...
32        Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
33    }
34}

<?php

namespace Tests\Feature;

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

class ExampleTest extends TestCase
{
    public function test_albums_can_be_uploaded(): void
    {
        Storage::fake('photos');

        $response = $this->json('POST', '/photos', [
            UploadedFile::fake()->image('photo1.jpg'),
            UploadedFile::fake()->image('photo2.jpg')
        ]);

        // Assert one or more files were stored...
        Storage::disk('photos')->assertExists('photo1.jpg');
        Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);

        // Assert one or more files were not stored...
        Storage::disk('photos')->assertMissing('missing.jpg');
        Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);

        // Assert that the number of files in a given directory matches the expected count...
        Storage::disk('photos')->assertCount('/wallpapers', 2);

        // Assert that a given directory is empty...
        Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
    }
}

デフォルトでは、fakeメソッドは一時ディレクトリ内のすべてのファイルを削除します。これらのファイルを保持したい場合は、代わりに「persistentFake」メソッドを使用できます。ファイルアップロードのテストの詳細については、HTTPテストのドキュメントのファイルアップロードに関する情報を参照してください。

imageメソッドにはGD拡張が必要です。

カスタムファイルシステム

LaravelのFlysystem統合は、すぐに使えるいくつかの「ドライバ」をサポートしています。しかし、Flysystemはこれらに限定されておらず、他の多くのストレージシステム用のアダプタがあります。Laravelアプリケーションでこれらの追加アダプタのいずれかを使用したい場合は、カスタムドライバを作成できます。

カスタムファイルシステムを定義するには、Flysystemアダプタが必要です。コミュニティでメンテナンスされているDropboxアダプタをプロジェクトに追加してみましょう。

1composer require spatie/flysystem-dropbox

composer require spatie/flysystem-dropbox

次に、アプリケーションのサービスプロバイダの1つのbootメソッド内でドライバを登録できます。これを実現するには、Storageファサードのextendメソッドを使用する必要があります。

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Contracts\Foundation\Application;
 6use Illuminate\Filesystem\FilesystemAdapter;
 7use Illuminate\Support\Facades\Storage;
 8use Illuminate\Support\ServiceProvider;
 9use League\Flysystem\Filesystem;
10use Spatie\Dropbox\Client as DropboxClient;
11use Spatie\FlysystemDropbox\DropboxAdapter;
12 
13class AppServiceProvider extends ServiceProvider
14{
15    /**
16     * Register any application services.
17     */
18    public function register(): void
19    {
20        // ...
21    }
22 
23    /**
24     * Bootstrap any application services.
25     */
26    public function boot(): void
27    {
28        Storage::extend('dropbox', function (Application $app, array $config) {
29            $adapter = new DropboxAdapter(new DropboxClient(
30                $config['authorization_token']
31            ));
32 
33            return new FilesystemAdapter(
34                new Filesystem($adapter, $config),
35                $adapter,
36                $config
37            );
38        });
39    }
40}

<?php

namespace App\Providers;

use Illuminate\Contracts\Foundation\Application;
use Illuminate\Filesystem\FilesystemAdapter;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Filesystem;
use Spatie\Dropbox\Client as DropboxClient;
use Spatie\FlysystemDropbox\DropboxAdapter;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        // ...
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Storage::extend('dropbox', function (Application $app, array $config) {
            $adapter = new DropboxAdapter(new DropboxClient(
                $config['authorization_token']
            ));

            return new FilesystemAdapter(
                new Filesystem($adapter, $config),
                $adapter,
                $config
            );
        });
    }
}

extendメソッドの第１引数はドライバの名前で、第２引数は$appと$config変数を受け取るクロージャです。クロージャはIlluminate\Filesystem\FilesystemAdapterのインスタンスを返す必要があります。$config変数は、指定されたディスクに対してconfig/filesystems.phpで定義された値を含みます。

拡張機能のサービスプロバイダを作成して登録したら、config/filesystems.php設定ファイルでdropboxドライバを使用できます。

序文

はじめに

アーキテクチャのコンセプト

基本

より深く知る

セキュリティ

データベース

Eloquent ORM

テスト

パッケージ

ファイルストレージ

製品

パッケージ

リソース