文件存储

简介
配置
获取磁盘实例
- 按需磁盘
检索文件
存储文件
删除文件
目录
测试
自定义文件系统

简介

Laravel 提供了一个强大的文件系统抽象，这要归功于 Frank de Jonge 出色的 Flysystem PHP 包。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：

php

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

shell

php artisan storage:link

一旦文件被存储并且符号链接已创建，您可以使用 asset 辅助函数为文件生成 URL：

php

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

您可以在 filesystems 配置文件中配置其他符号链接。当您运行 storage:link 命令时，每个配置的链接都会被创建：

php

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

storage:unlink 命令可用于销毁您配置的符号链接：

shell

php artisan storage:unlink

驱动前提条件

S3 驱动配置

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

shell

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

S3 磁盘配置数组位于您的 config/filesystems.php 配置文件中。通常，您应使用 config/filesystems.php 配置文件引用的以下环境变量来配置您的 S3 信息和凭证：

ini

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

shell

composer require league/flysystem-ftp "^3.0"

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

php

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

shell

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

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

php

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

shell

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

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

php

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

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

shell

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

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

php

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

读穿透磁盘允许你在不中断服务的情况下在磁盘之间迁移文件。读取文件时，Laravel 首先检查主磁盘。如果文件仅存在于回退磁盘上，Laravel 会从回退磁盘读取该文件，并将其复制到主磁盘以供后续请求使用：

php

'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 环境变量定义：

php

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

获取磁盘实例

可以使用 Storage Facade 与您配置的任何磁盘进行交互。例如，您可以在 Facade 上使用 put 方法将头像存储在默认磁盘上。如果您在 Storage Facade 上调用方法而不先调用 disk 方法，该方法将自动传递给默认磁盘：

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

按需磁盘

有时您可能希望使用给定的配置在运行时创建一个磁盘，而该配置实际上并不存在于应用程序的 filesystems 配置文件中。为此，您可以将配置数组传递给 Storage Facade 的 build 方法：

php

use Illuminate\Support\Facades\Storage;

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

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

检索文件

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

php

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

如果您检索的文件包含 JSON，您可以使用 json 方法来检索文件并解码其内容：

php

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

exists 方法可用于确定文件是否存在于磁盘上：

php

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

missing 方法可用于确定文件是否从磁盘中丢失：

php

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

下载文件

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

php

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

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

文件 URL

您可以使用 url 方法获取给定文件的 URL。如果您使用 local 驱动，这通常只会将 /storage 前置到给定路径，并返回文件的相对 URL。如果您使用 s3 驱动，将返回完整的远程 URL：

php

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 Facade 生成的 URL 的主机，可以在磁盘的配置数组中添加或更改 url 选项：

php

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

临时 URL

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

php

use Illuminate\Support\Facades\Storage;

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

启用本地临时 URL

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

php

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

S3 请求参数

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

php

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

自定义临时 URL

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

php

<?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

警告

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

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

php

use Illuminate\Support\Facades\Storage;

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

此方法主要适用于无服务器环境，这些环境需要客户端应用程序直接上传文件到云存储系统（如 Amazon S3）。

文件元数据

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

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

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

php

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

文件路径

您可以使用 path 方法获取给定文件的路径。如果您使用 local 驱动，这将返回文件的绝对路径。如果您使用 s3 驱动，此方法将返回 S3 存储桶中文件的相对路径：

php

use Illuminate\Support\Facades\Storage;

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

存储文件

put 方法可用于将文件内容存储到磁盘上。您还可以将 PHP resource 传递给 put 方法，该方法将使用 Flysystem 的底层流支持。请记住，所有文件路径都应指定相对于为磁盘配置的“根”位置：

php

use Illuminate\Support\Facades\Storage;

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

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

写入失败

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

php

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

如果您愿意，可以在文件系统磁盘的配置数组中定义 throw 选项。当此选项定义为 true 时，诸如 put 之类的“写入”方法将在写入操作失败时抛出 League\Flysystem\UnableToWriteFile 的实例：

php

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

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

php

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

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

文件内容追加与前置

prepend 和 append 方法允许您在文件的开头或结尾写入内容：

php

Storage::prepend('file.log', '前置文本');

Storage::append('file.log', '追加文本');

复制与移动文件

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

php

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

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

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

php

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 实例，并将自动将文件流式传输到您想要的位置：

php

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 公开访问，这尤其有用：

php

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

文件上传

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

php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserAvatarController extends Controller
{
    /**
     * 更新用户的头像。
     */
    public function update(Request $request): string
    {
        $path = $request->file('avatar')->store('avatars');

        return $path;
    }
}

关于此示例，有几点需要注意。请注意，我们只指定了目录名称，而没有指定文件名。默认情况下，store 方法将生成一个唯一 ID 作为文件名。文件的扩展名将通过检查文件的 MIME 类型来确定。store 方法将返回文件的路径，因此您可以将路径（包括生成的文件名）存储在数据库中。

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

php

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

指定文件名

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

php

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

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

php

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

警告

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

指定磁盘

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

php

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

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

php

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

其他上传文件信息

如果您想获取上传文件的原始名称和扩展名，可以使用 getClientOriginalName 和 getClientOriginalExtension 方法：

php

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

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

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

php

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

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

文件可见性

在 Laravel 的 Flysystem 集成中，“可见性”是跨多个平台的文件权限的抽象。文件可以声明为 public 或 private。当文件声明为 public 时，您表明该文件通常应对其他人可访问。例如，使用 S3 驱动时，您可以为 public 文件检索 URL。

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

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

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

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

php

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

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

图像处理

如果你需要在存储之前调整上传图片的大小、裁剪或转换格式，可以使用 Laravel 的图像处理功能：

php

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

你也可以从已存储在某个文件系统磁盘上的文件创建一个图像实例：

php

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

本地文件和可见性

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

php

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

删除文件

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

php

use Illuminate\Support\Facades\Storage;

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

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

如有必要，您可以指定应从中删除文件的磁盘：

php

use Illuminate\Support\Facades\Storage;

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

测试

Storage Facade 的 fake 方法允许您轻松生成一个假磁盘，与 Illuminate\Http\UploadedFile 类的文件生成实用程序相结合，大大简化了文件上传的测试。例如：

PestPHPUnit

php

<?php

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

test('可以上传相册', 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

<?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 适配器添加到我们的项目中：

shell

composer require spatie/flysystem-dropbox

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

php

<?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
{
    /**
     * 注册任何应用程序服务。
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 引导任何应用程序服务。
     */
    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 驱动。

文件存储 ​

简介 ​

配置 ​

本地驱动 ​

公共磁盘 ​

驱动前提条件 ​

S3 驱动配置 ​

FTP 驱动配置 ​

SFTP 驱动配置 ​

作用域、只读和读穿透文件系统 ​

Amazon S3 兼容文件系统 ​

获取磁盘实例 ​

按需磁盘 ​

检索文件 ​

下载文件 ​

文件 URL ​

URL 主机自定义 ​

临时 URL ​

启用本地临时 URL ​

S3 请求参数 ​

自定义临时 URL ​

临时上传 URL ​

文件元数据 ​

文件路径 ​

存储文件 ​

写入失败 ​

文件内容追加与前置 ​

复制与移动文件 ​

自动流式传输 ​

文件上传 ​

指定文件名 ​

指定磁盘 ​

其他上传文件信息 ​

文件可见性 ​

图像处理 ​

本地文件和可见性 ​

删除文件 ​

目录 ​

获取目录中的所有文件 ​

获取目录中的所有目录 ​

创建目录 ​

删除目录 ​

测试 ​

自定义文件系统 ​

文件存储

简介

配置

本地驱动

公共磁盘

驱动前提条件

S3 驱动配置

FTP 驱动配置

SFTP 驱动配置

作用域、只读和读穿透文件系统

Amazon S3 兼容文件系统

获取磁盘实例

按需磁盘

检索文件

下载文件

文件 URL

URL 主机自定义

临时 URL

启用本地临时 URL

S3 请求参数

自定义临时 URL

临时上传 URL

文件元数据

文件路径

存储文件

写入失败

文件内容追加与前置

复制与移动文件

自动流式传输

文件上传

指定文件名

指定磁盘

其他上传文件信息

文件可见性

图像处理

本地文件和可见性

删除文件

目录

获取目录中的所有文件

获取目录中的所有目录

创建目录

删除目录

测试

自定义文件系统