文件存储

简介

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

配置

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

local 驱动程序与存储在运行 Laravel 应用程序的服务器本地的文件进行交互，而 sftp 存储驱动程序用于基于 SSH 密钥的 FTP。s3 驱动程序用于写入 Amazon 的 S3 云存储服务。

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

本地驱动程序

使用 local 驱动程序时，所有文件操作都相对于你在 filesystems 配置文件中定义的 root 目录。默认情况下，该值设置为 storage/app/private 目录。因此，以下方法会将内容写入 storage/app/private/example.txt：

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 命令：

php artisan storage:link

一旦文件已存储且符号链接已创建，你就可以使用 asset 辅助函数创建指向这些文件的 URL：

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

你可以在 filesystems 配置文件中配置其他符号链接。运行 storage:link 命令时，将创建所有已配置的链接：

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

可以使用 storage:unlink 命令删除已配置的符号链接：

php artisan storage:unlink

驱动程序前提条件

S3 驱动程序配置

在使用 S3 驱动程序之前，你需要通过 Composer 包管理器安装 Flysystem S3 包：

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

在 config/filesystems.php 配置文件中有一个 S3 磁盘配置数组。通常，你应该使用以下环境变量来配置你的 S3 信息和凭据，这些环境变量由 config/filesystems.php 配置文件引用：

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 包：

composer require league/flysystem-ftp "^3.0"

Laravel 的 Flysystem 集成与 FTP 配合良好；然而，框架默认的 config/filesystems.php 配置文件中不包含示例配置。如果你需要配置 FTP 文件系统，可以使用以下配置示例：

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

    // 可选的 FTP 设置...
    // 'port' => env('FTP_PORT', 21),
    // 'root' => env('FTP_ROOT'),
    // 'passive' => true,
    // 'ssl' => true,
    // 'timeout' => 30,
],

SFTP 驱动程序配置

在使用 SFTP 驱动程序之前，你需要通过 Composer 包管理器安装 Flysystem SFTP 包：

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

Laravel 的 Flysystem 集成与 SFTP 配合良好；然而，框架默认的 config/filesystems.php 配置文件中不包含示例配置。如果你需要配置 SFTP 文件系统，可以使用以下配置示例：

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

    // 基本认证设置...
    'username' => env('SFTP_USERNAME'),
    'password' => env('SFTP_PASSWORD'),

    // 带加密密码的基于 SSH 密钥的认证设置...
    'privateKey' => env('SFTP_PRIVATE_KEY'),
    'passphrase' => env('SFTP_PASSPHRASE'),

    // 文件/目录权限设置...
    'visibility' => 'private', // `private` = 0600, `public` = 0644
    'directory_visibility' => 'private', // `private` = 0700, `public` = 0755

    // 可选的 SFTP 设置...
    // '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 包：

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

你可以通过定义一个使用 scoped 驱动程序的磁盘，来创建任何现有文件系统磁盘的路径范围限定实例。例如，你可以创建一个磁盘，将你现有的 s3 磁盘限定到特定的路径前缀，然后使用该范围限定磁盘的每次文件操作都将使用指定的前缀：

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

“只读”磁盘允许你创建不允许写操作的文件系统磁盘。在使用 read-only 配置选项之前，你需要通过 Composer 包管理器安装额外的 Flysystem 包：

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

接下来，你可以在一个或多个磁盘的配置数组中包含 read-only 配置选项：

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

读透磁盘允许你在磁盘之间迁移文件而无需停机。读取文件时，Laravel 首先检查主磁盘。如果文件仅存在于备用磁盘上，Laravel 会从备用磁盘读取该文件，并将其复制到主磁盘以供后续请求使用：

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

写入操作和目录列表针对主磁盘。文件存在性和元数据检查会使用任一磁盘，而不会将文件复制到主磁盘。如果将备用文件复制到主磁盘失败，默认情况下读取操作仍会成功。若要改为抛出异常，可将 throw_on_promotion_failure 配置选项设置为 true。

兼容 Amazon S3 的文件系统

默认情况下，应用程序的 filesystems 配置文件中包含一个 s3 磁盘的配置。除了使用此磁盘与 Amazon S3 进行交互外，你还可以使用它与任何兼容 S3 的文件存储服务进行交互，例如 RustFS、DigitalOcean Spaces、Vultr Object Storage、Cloudflare R2 或 Hetzner Cloud Storage。

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

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

获取磁盘实例

可以使用 Storage 门面与您配置的任何磁盘进行交互。例如，您可以在门面上使用 put 方法，将头像存储到默认磁盘。如果您在未先调用 disk 方法的情况下对 Storage 门面调用方法，该方法将自动作用于默认磁盘：

use Illuminate\Support\Facades\Storage;

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

如果您的应用与多个磁盘进行交互，您可以在 Storage 门面上使用 disk 方法来操作特定磁盘上的文件：

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

按需创建磁盘

有时，您可能希望在运行时使用给定的配置来创建磁盘，而该配置实际上并不需要存在于应用的 filesystems 配置文件中。要实现这一点，您可以将配置数组传递给 Storage 门面的 build 方法：

use Illuminate\Support\Facades\Storage;

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

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

读取文件

可以使用 get 方法来读取文件的内容。该方法会返回文件的原始字符串内容。请记住，所有文件路径都应相对于磁盘的“根”位置来指定：

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

如果您要读取的文件包含 JSON 数据，您可以使用 json 方法来读取文件并解码其内容：

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

可以使用 exists 方法来判断磁盘上是否存在某个文件：

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

可以使用 missing 方法来判断磁盘上是否缺失某个文件：

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

下载文件

可以使用 download 方法来生成一个响应，该响应会强制用户的浏览器下载指定路径下的文件。download 方法接受一个文件名作为该方法的第二个参数，该参数将决定下载文件的用户所看到的文件名。最后，您可以将一个 HTTP 头数组作为该方法的第三个参数传入：

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

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

文件 URL

您可以使用 url 方法来获取指定文件的 URL。如果您使用的是 local 驱动，该方法通常只是在给定路径前添加 /storage，并返回文件的相对 URL。如果您使用的是 s3 驱动，则会返回完整的远程 URL：

use Illuminate\Support\Facades\Storage;

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

当使用 local 驱动时，所有应公开访问的文件都应放置在 storage/app/public 目录下。此外，您应该在 public/storage 处创建一个指向 storage/app/public 目录的符号链接。

当使用 local 驱动时，url 的返回值未进行 URL 编码。因此，我们建议始终使用能生成有效 URL 的文件名来存储文件。

自定义 URL 主机

如果您想修改使用 Storage 门面生成的 URL 的主机，您可以在磁盘的配置数组中添加或更改 url 选项：

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

临时 URL

使用 temporaryUrl 方法，您可以为使用 local 和 s3 驱动存储的文件创建临时 URL。该方法接受一个路径和一个 DateTime 实例，用于指定该 URL 的过期时间：

use Illuminate\Support\Facades\Storage;

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

启用本地临时 URL

如果您在 local 驱动支持临时 URL 之前就开始开发应用，您可能需要启用本地临时 URL。为此，请在 config/filesystems.php 配置文件中，为 local 磁盘的配置数组添加 serve 选项：

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

S3 请求参数

如果您需要指定额外的S3 请求参数，您可以将请求参数数组作为第三个参数传递给 temporaryUrl 方法：

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

自定义临时 URL

如果您需要自定义特定存储磁盘创建临时 URL 的方式，可以使用 buildTemporaryUrlsUsing 方法。例如，如果您有一个控制器，允许您下载存储在通常不支持临时 URL 的磁盘上的文件，这会很有用。通常，该方法应在服务提供者的 boot 方法中调用：

<?php

namespace App\Providers;

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

class AppServiceProvider extends ServiceProvider
{
    /**
     * 初始化应用服务。
     */
    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

仅 s3 和 local 驱动支持生成临时上传 URL。

如果您需要生成一个临时 URL，以便客户端应用可以直接上传文件，可以使用 temporaryUploadUrl 方法。该方法接受一个路径和一个 DateTime 实例，用于指定该 URL 的过期时间。temporaryUploadUrl 方法返回一个关联数组，可解构为上传 URL 和上传请求中应包含的头部信息：

use Illuminate\Support\Facades\Storage;

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

该方法主要适用于需要客户端应用直接上传文件到 Amazon S3 等云存储系统的无服务器环境。

文件元数据

除了读写文件，Laravel 还能提供关于文件本身的信息。例如，可以使用 size 方法获取文件的大小（以字节为单位）：

use Illuminate\Support\Facades\Storage;

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

lastModified 方法返回文件最后一次修改的 UNIX 时间戳：

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

可以通过 mimeType 方法获取指定文件的 MIME 类型：

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

文件路径

您可以使用 path 方法获取指定文件的路径。如果您使用的是 local 驱动，该方法会返回文件的绝对路径。如果您使用的是 s3 驱动，该方法会返回文件在 S3 存储桶中的相对路径：

use Illuminate\Support\Facades\Storage;

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

存储文件

put 方法可用于将文件内容存储到磁盘上。你也可以向 put 方法传入一个 PHP resource，该方法会利用 Flysystem 底层的流支持。请记住，所有文件路径都应相对于为磁盘配置的“根”位置来指定：

use Illuminate\Support\Facades\Storage;

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

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

写入失败

如果 put 方法（或其他“写入”操作）无法将文件写入磁盘，则会返回 false：

if (! Storage::put('file.jpg', $contents)) {
    // 文件无法写入磁盘……
}

如有需要，你可以在文件系统磁盘的配置数组中定义 throw 选项。当该选项被设置为 true 时，诸如 put 等“写入”方法在写入操作失败时，会抛出 League\Flysystem\UnableToWriteFile 的实例：

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

或者，你可以在文件系统磁盘的配置数组中定义 report 选项。当该选项被设置为 true 时，当“写入”操作失败，Laravel 会使用应用程序的异常处理器记录底层异常，而不会抛出异常，也不会中断写入操作的返回值：

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

如果既没有定义 throw 选项，也没有定义 report 选项，那么磁盘在操作失败时会静默返回 false，且底层异常不会被抛出或记录。

在文件开头和结尾追加内容

prepend 和 append 方法可用于向文件开头或结尾写入内容：

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

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

复制和移动文件

copy 方法可用于将现有文件复制到磁盘上的新位置，而 move 方法可用于重命名现有文件，或将其移动到新位置：

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

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

你可以使用 copyToDisk 和 moveToDisk 方法，将文件复制或移动到其他磁盘。除非提供第三个参数，否则源文件的路径会用于目标磁盘：

Storage::disk('local')->copyToDisk('s3', 'reports/report.csv');

Storage::disk('local')->moveToDisk(
    's3', 'reports/report.csv', 'archive/report.csv'
);

自动流式传输

将文件流式传输到存储中可显著减少内存占用。如果你希望 Laravel 自动管理将指定文件流式传输到你的存储位置，可以使用 putFile 或 putFileAs 方法。该方法接收 Illuminate\Http\File 或 Illuminate\Http\UploadedFile 实例，并会自动将文件流式传输到你指定的目标位置：

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

// 自动为文件名生成唯一 ID……
$path = Storage::putFile('photos', new File('/path/to/photo'));

// 手动指定文件名……
$path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

关于 putFile 方法，有几点重要事项需要注意。请注意，我们仅指定了目录名，而未指定文件名。默认情况下，putFile 方法会生成一个唯一 ID 作为文件名。文件的扩展名将通过检查文件的 MIME 类型来确定。putFile 方法会返回文件的路径，以便你将包含生成文件名的路径存储到数据库中。

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

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

文件上传

在 Web 应用中，存储文件的最常见用例之一是存储用户上传的文件，例如照片和文档。Laravel 让使用上传文件实例上的 store 方法来存储上传文件变得非常简单。调用 store 方法，并传入希望存储上传文件的路径：

<?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 方法会返回文件的路径，以便你将包含生成文件名的路径存储到数据库中。

你也可以在 Storage 门面上调用 putFile 方法，以执行与上述示例相同的文件存储操作：

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

指定文件名

如果你不希望为存储的文件自动分配文件名，可以使用 storeAs 方法，该方法接收路径、文件名以及（可选的）磁盘作为参数：

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

你也可以在 Storage 门面上使用 putFileAs 方法，该方法将执行与上述示例相同的文件存储操作：

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

不可打印和无效的 Unicode 字符会被自动从文件路径中移除。因此，你可能需要在将文件路径传递给 Laravel 的文件存储方法之前对其进行清理。文件路径会使用 League\Flysystem\WhitespacePathNormalizer::normalizePath 方法进行规范化。

指定磁盘

默认情况下，此上传文件的 store 方法会使用默认磁盘。如果你想指定其他磁盘，可将磁盘名称作为第二个参数传递给 store 方法：

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

如果你使用的是 storeAs 方法，可将磁盘名称作为该方法的第三个参数传递：

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

其他上传文件信息

如果你希望获取上传文件的原始名称和扩展名，可以使用 getClientOriginalName 和 getClientOriginalExtension 方法来实现：

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

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

不过，请记住 getClientOriginalName 和 getClientOriginalExtension 方法被认为是不安全的，因为文件名和扩展名可能会被恶意用户篡改。因此，通常建议优先使用 hashName 和 extension 方法，以获取给定上传文件的名称和扩展名：

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

$name = $file->hashName(); // 生成唯一、随机的名称……
$extension = $file->extension(); // 根据文件的 MIME 类型确定文件扩展名……

文件可见性

在 Laravel 的 Flysystem 集成中，“可见性”是跨多个平台的文件权限的抽象。文件可被声明为 public 或 private。当文件被声明为 public 时，意味着该文件通常应可被他人访问。例如，在使用 S3 驱动时，你可以获取 public 文件的 URL。

你可以在通过 put 方法写入文件时设置可见性：

use Illuminate\Support\Facades\Storage;

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

如果文件已存储，可以通过 getVisibility 和 setVisibility 方法获取和设置其可见性：

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

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

与上传的文件进行交互时，您可以使用 storePublicly 和 storePubliclyAs 方法，以 public 可见性存储上传的文件：

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

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

图像处理

如果您需要在存储上传的图像之前对其进行缩放、裁剪或转换，您可以使用 Laravel 的图像处理功能：

$path = $request->image('avatar')
    ->cover(400, 400)
    ->toWebp()
    ->storePublicly('avatars', 'public');

您还可以从已存储在其中一个文件系统磁盘上的文件创建图像实例：

$image = Storage::disk('public')->image('avatars/photo.jpg');

本地文件与可见性

使用 local 驱动时，public 可见性会转换为目录的 0755 权限和文件的 0644 权限。您可以在应用程序的 filesystems 配置文件中修改权限映射：

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

删除文件

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

use Illuminate\Support\Facades\Storage;

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

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

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

use Illuminate\Support\Facades\Storage;

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

目录

获取目录内的所有文件

files 方法返回给定目录内所有文件的数组。如果您想获取包含子目录的给定目录内所有文件的列表，可以使用 allFiles 方法：

use Illuminate\Support\Facades\Storage;

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

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

获取目录内的所有子目录

directories 方法返回给定目录内所有目录的数组。如果您想获取包含子目录的给定目录内所有目录的列表，可以使用 allDirectories 方法：

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

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

创建目录

makeDirectory 方法将创建给定目录，包括任何需要的子目录：

Storage::makeDirectory($directory);

删除目录

最后，可以使用 deleteDirectory 方法删除一个目录及其所有文件：

Storage::deleteDirectory($directory);

测试

Storage 门面的 fake 方法允许您轻松生成一个虚拟磁盘，将其与 Illuminate\Http\UploadedFile 类的文件生成工具结合使用，可大幅简化文件上传的测试。例如：

<?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')
    ]);

    // 断言已存储一个或多个文件……
    Storage::disk('photos')->assertExists('photo1.jpg');
    Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);

    // 断言一个或多个文件未被存储……
    Storage::disk('photos')->assertMissing('missing.jpg');
    Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);

    // 断言给定目录中的文件数量与预期数量一致……
    Storage::disk('photos')->assertCount('/wallpapers', 2);

    // 断言给定目录为空……
    Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');

    // 断言磁盘中没有文件……
    Storage::disk('photos')->assertEmpty();
});

<?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')
        ]);

        // 断言已存储一个或多个文件……
        Storage::disk('photos')->assertExists('photo1.jpg');
        Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);

        // 断言一个或多个文件未被存储……
        Storage::disk('photos')->assertMissing('missing.jpg');
        Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);

        // 断言给定目录中的文件数量与预期数量一致……
        Storage::disk('photos')->assertCount('/wallpapers', 2);

        // 断言给定目录为空……
        Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');

        // 断言磁盘中没有文件……
        Storage::disk('photos')->assertEmpty();
    }
}

默认情况下，fake 方法会删除其临时目录中的所有文件。如果您想保留这些文件，可以改用 “persistentFake” 方法。有关测试文件上传的更多信息，您可以查阅HTTP 测试文档中关于文件上传的内容。

image 方法需要 GD 扩展。

自定义文件系统

Laravel 的 Flysystem 集成开箱即用地支持多种“驱动”；不过，Flysystem 并不局限于这些驱动，还为许多其他存储系统提供了适配器。如果您想在 Laravel 应用中使用这些额外适配器中的某一个，可以创建一个自定义驱动。

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

composer require spatie/flysystem-dropbox

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

<?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 驱动了。