文件存储

Introduction
Configuration
Obtaining Disk Instances
- On-Demand Disks
Retrieving Files
Storing Files
Deleting Files
Directories
Testing
Custom Filesystems

介绍

Laravel 提供了强大的文件系统抽象，这得益于Frank de Jonge 开发的Flysystem PHP 包。Laravel Flysystem 集成提供了简单的驱动程序，可用于操作本地文件系统、SFTP 和 Amazon S3。更棒的是，由于 API 在每个系统上保持一致，因此在本地开发机器和生产服务器之间切换这些存储选项变得异常简单。

配置

Laravel 的文件系统配置文件位于config/filesystems.php。在此文件中，您可以配置所有文件系统“磁盘”。每个磁盘代表一个特定的存储驱动程序和存储位置。配置文件中包含每个受支持驱动程序的示例配置，您可以根据自己的存储偏好和凭据修改配置。

驱动local程序与运行 Laravel 应用程序的服务器上本地存储的文件进行交互，同时s3驱动程序用于写入亚马逊的 S3 云存储服务。

您可以根据需要配置任意数量的磁盘，甚至可以有多个使用相同驱动程序的磁盘。

本地司机

使用local驱动程序时，所有文件操作都相对于配置文件root中定义的目录filesystems。默认情况下，此值设置为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');

公共磁盘

public应用程序配置文件中包含的磁盘用于filesystems存放将要公开访问的文件。默认情况下，public磁盘使用local驱动程序并将其文件存储在中storage/app/public。

如果您的public磁盘使用local驱动程序，并且您希望从网络访问这些文件，则应该创建从源目录storage/app/public到目标目录的符号链接public/storage：

要创建符号链接，您可以使用storage:linkArtisan 命令：

1php artisan storage:link

php artisan storage:link

一旦文件被存储并且符号链接被创建，您就可以使用assetHelpers创建文件的 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 的文件系统集成与 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 的文件系统集成与 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交互之外，您还可以使用它与任何与 S3 兼容的文件存储服务进行交互，例如MinIO、DigitalOcean Spaces、Vultr Object Storage、Cloudflare R2或Hetzner Cloud Storage。

通常，在更新磁盘凭据以匹配您计划使用的服务的凭据后，您只需更新endpoint配置选项的值。此选项的值通常通过环境变量定义AWS_ENDPOINT：

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

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

MinIO

为了使 Laravel 的 Flysystem 集成在使用 MinIO 时生成正确的 URL，您应该定义AWS_URL环境变量，使其与应用程序的本地 URL 匹配，并在 URL 路径中包含存储桶名称：

1AWS_URL=http://localhost:9000/local

AWS_URL=http://localhost:9000/local

如果客户端无法访问，则使用 MinIO 时通过该方法生成临时存储 URLtemporaryUrl可能无法工作。endpoint

获取磁盘实例

外观Storage层可用于与任何已配置的磁盘进行交互。例如，您可以使用put外观层上的方法将头像存储在默认磁盘上。如果您Storage在未先调用外观层disk方法的情况下调用外观层上的方法，则该方法将自动传递给默认磁盘：

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

use Illuminate\Support\Facades\Storage;

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

如果您的应用程序与多个磁盘交互，您可以使用外观disk上的方法Storage来处理特定磁盘上的文件：

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，并返回文件的相对 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目录中。此外，还应创建指向该目录的符号链接。public/storagestorage/app/public

使用local驱动程序时，的返回值url未经过 URL 编码。因此，我们建议始终使用能够创建有效 URL 的名称来存储文件。

URL 主机自定义

如果您想修改使用外观生成的 URL 的主机，您可以在磁盘的配置数组中Storage添加或更改选项：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。此方法接受一个路径和一个DateTime指定 URL 过期时间的实例：

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。为此，请在配置文件中将此serve选项添加到local磁盘的配置数组中config/filesystems.php：

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方法。此方法接受一个路径和一个DateTime指定 URL 过期时间的实例。该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方法，这将使用文件系统底层的流支持。请记住，所有文件路径都应相对于磁盘配置的“根”位置指定：

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 自动管理将指定文件流式传输到存储位置，可以使用putFileorputFileAs方法。此方法接受Illuminate\Http\FileorIlluminate\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以便您可以将路径（包括生成的文件名）存储在数据库中。

和方法还接受一个参数来指定存储文件的“可见性”。如果您将文件存储在 Amazon S3 等云盘上putFile，putFileAs并且希望通过生成的 URL 公开访问该文件，则此功能特别有用：

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

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

文件上传

在 Web 应用程序中，存储文件最常见的用例之一是存储用户上传的文件，例如照片和文档。Laravel 使用store上传文件实例上的方法来轻松存储上传的文件。调用该store方法并传入您希望存储上传文件的路径：

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

<?php

namespace App\Http\Controllers;

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以便您可以将路径（包括生成的文件名）存储在数据库中。

您也可以调用外观putFile上的方法Storage来执行与上述示例相同的文件存储操作：

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
);

您也可以使用外观putFileAs上的方法Storage，它将执行与上面示例相同的文件存储操作：

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

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

不可打印和无效的 Unicode 字符将自动从文件路径中删除。因此，在将文件路径传递给 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方法被认为是不安全的，因为文件名和扩展名可能被恶意用户篡改。因此，通常应该优先使用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 的文件系统集成中，“可见性”是对跨平台文件权限的抽象。文件可以声明为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'local' => [
 2    'driver' => 'local',
 3    'root' => storage_path('app'),
 4    'permissions' => [
 5        'file' => [
 6            'public' => 0644,
 7            'private' => 0600,
 8        ],
 9        'dir' => [
10            'public' => 0755,
11            'private' => 0700,
12        ],
13    ],
14    'throw' => false,
15],

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

删除文件

该delete方法接受要删除的单个文件名或文件数组：

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

use Illuminate\Support\Facades\Storage;

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

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

如果需要，您可以指定要从中删除文件的磁盘：

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

use Illuminate\Support\Facades\Storage;

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

测试

StorageFacade 的方法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 的文件系统集成提供了对多种“驱动程序”的开箱即用支持；然而，文件系统并不局限于这些，它还提供了许多其他存储系统的适配器。如果您想在 Laravel 应用程序中使用这些附加适配器之一，可以创建自定义驱动程序。

为了定义自定义文件系统，您需要一个文件系统适配器。让我们将一个由社区维护的 Dropbox 适配器添加到我们的项目中：

1composer require spatie/flysystem-dropbox

composer require spatie/flysystem-dropbox

boot接下来，你可以在应用程序的某个服务提供者的方法中注册驱动程序。为此，你应该使用外观组件extend的方法Storage：

 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

一旦您创建并注册了扩展的服务提供商，您就可以在配置文件dropbox中使用该驱动程序config/filesystems.php。

序幕

入门

架构概念

基础知识

深入挖掘

安全

数据库

Eloquent ORM

Testing

Packages

文件存储

本页内容