# 文件存储

-   [介绍](#introduction)
-   [配置](#configuration)
    -   [本地驱动](#the-local-driver)
    -   [公共磁盘](#the-public-disk)
    -   [驱动前置条件](#driver-prerequisites)
    -   [限定范围和只读文件系统](#scoped-and-read-only-filesystems)
    -   [兼容 Amazon S3 的文件系统](#amazon-s3-compatible-filesystems)
-   [获取磁盘实例](#obtaining-disk-instances)
    -   [按需磁盘](#on-demand-disks)
-   [获取文件](#retrieving-files)
    -   [下载文件](#downloading-files)
    -   [文件 URL](#file-urls)
    -   [临时 URL](#temporary-urls)
    -   [文件元数据](#file-metadata)
-   [存储文件](#storing-files)
    -   [向文件前面和后面追加内容](#prepending-appending-to-files)
    -   [复制和移动文件](#copying-moving-files)
    -   [自动流式传输](#automatic-streaming)
    -   [文件上传](#file-uploads)
    -   [文件可见性](#file-visibility)
-   [删除文件](#deleting-files)
-   [目录](#directories)
-   [测试](#testing)
-   [自定义文件系统](#custom-filesystems)

## 介绍

Laravel 借助 Frank de Jonge 开发的优秀 PHP 包 [Flysystem](https://github.com/thephpleague/flysystem)，提供了一套强大的文件系统抽象层。
Laravel 对 Flysystem 的集成，为本地文件系统、SFTP 和 Amazon S3 提供了简单易用的驱动。
更方便的是，你可以非常轻松地在本地开发环境和生产服务器之间切换不同的存储方式，因为每种存储系统使用的 API 都是相同的。

## 配置

Laravel 的文件系统配置文件位于 `config/filesystems.php`。
在这个文件中，你可以配置应用程序使用的所有文件系统“磁盘（disk）”。每个磁盘都代表一种特定的存储驱动和存储位置。
配置文件中已经包含了每种受支持驱动的示例配置，你可以根据自己的存储需求和认证凭据修改这些配置。
`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` 配置文件中。
通常，你应该使用以下环境变量来配置 S3 相关信息和凭据，这些环境变量会被 `config/filesystems.php` 配置文件引用：

```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 的示例配置。如果你需要配置 FTP 文件系统，可以参考下面的配置示例：


```php
'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 扩展包：

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

Laravel 的 Flysystem 集成可以很好地支持 SFTP。不过，框架默认的 `config/filesystems.php` 配置文件中并没有包含 SFTP 的示例配置。如果你需要配置 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,
],
```

### 兼容 Amazon S3 的文件系统

默认情况下，应用程序的 `filesystems` 配置文件中已经包含了 `s3` 磁盘的配置。
除了可以使用该磁盘与 [Amazon S3](https://aws.amazon.com/s3/) 交互之外，你还可以使用它来连接任何兼容 S3 的文件存储服务，例如 [RustFS](https://github.com/rustfs/rustfs)、[DigitalOcean Spaces](https://www.digitalocean.com/products/spaces/)、[Vultr Object Storage](https://www.vultr.com/products/object-storage/)、[Cloudflare R2](https://www.cloudflare.com/developer-platform/products/r2/) 或 [Hetzner Cloud Storage](https://www.hetzner.com/storage/object-storage/)。



通常，在将磁盘的访问凭据更新为你计划使用的存储服务所对应的凭据后，你只需要修改 `endpoint` 配置项的值。
该配置项通常通过 `AWS_ENDPOINT` 环境变量来定义：

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

## 获取磁盘实例

你可以使用 `Storage` facade 与任何已配置的磁盘进行交互。
例如，你可以调用 facade 的 `put` 方法，将头像文件存储到默认磁盘中。
如果你没有先调用 `disk` 方法，而是直接调用 `Storage` facade 上的方法，那么该方法会自动作用于默认磁盘：

```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` 方法获取文件内容。该方法会返回文件的原始字符串内容。
请记住，所有文件路径都应该相对于磁盘的“根目录（root）”来指定：

```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` 驱动，Laravel 通常会在给定路径前添加 `/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

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

```php
'local' => [
    'driver' => 'local',
    'root' => storage_path('app/private'),
    'serve' => true, // [tl! add]
    'throw' => false,
],
```

#### S3 请求参数

如果你需要指定额外的 [S3 请求参数](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html#RESTObjectGET-requests)，可以将请求参数数组作为 `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)
);
```

这个方法主要适用于 Serverless 环境，在这类环境中，通常需要客户端应用直接将文件上传到 Amazon S3 等云存储系统。

### 文件元数据

除了读取和写入文件之外，Laravel 还可以提供文件本身的相关信息。例如，可以使用 `size` 方法获取文件大小，单位为字节：

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

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

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

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

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

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

#### 文件路径

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

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

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



## 存储文件

可以使用 `put` 方法将文件内容存储到磁盘中。你也可以将 PHP `resource` 传递给 `put` 方法，此时会使用 Flysystem 底层的流式处理支持。请记住，所有文件路径都应该相对于磁盘配置中的 `root` 目录来指定：

```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,
],
```

### 在文件前面和后面追加内容

`prepend` 和 `append` 方法允许你分别向文件的开头或末尾写入内容：

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

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

### 复制和移动文件

可以使用 `copy` 方法将现有文件复制到磁盘中的新位置。可以使用 `move` 方法对现有文件进行重命名，或者将其移动到新的位置：

```php
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` 实例，并自动以流的方式将文件写入指定位置：

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

// 自动生成唯一文件名...
$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` 门面上的 `putFile` 方法，执行与上述示例相同的文件存储操作：

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

#### 指定文件名

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

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

你也可以使用 `Storage` 门面上的 `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'
);
```

#### 本地文件和可见性

使用 `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');
```

## 目录

#### 获取目录中的所有文件

`files` 方法返回指定目录中所有文件的数组。如果你想获取指定目录及其子目录中的所有文件列表，可以使用 `allFiles` 方法：

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

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

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

#### 获取目录中的所有子目录

`directories` 方法返回指定目录中所有子目录的数组。如果你想获取指定目录及其所有层级子目录的列表，可以使用 `allDirectories` 方法：

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

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



#### 创建目录

`makeDirectory` 方法将创建指定目录，包括所需的所有子目录：

```php
Storage::makeDirectory($directory);
```

#### 删除目录

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

```php
Storage::deleteDirectory($directory);
```

## 测试

`Storage` 门面的 `fake` 方法允许你轻松创建一个模拟磁盘，结合 `Illuminate\Http\UploadedFile` 类的文件生成工具，可以大大简化文件上传的测试。例如：

```php tab=Pest
<?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');
});
```

```php tab=PHPUnit
<?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');
    }
}
```



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

> [!WARNING]
> `image` 方法需要安装 GD 扩展。

## 自定义文件系统

Laravel 的 Flysystem 集成默认支持多种“驱动”，但 Flysystem 并不局限于这些驱动，它还为许多其他存储系统提供了适配器。如果你想在 Laravel 应用程序中使用这些额外的适配器，可以创建自定义驱动。

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

```shell
composer require spatie/flysystem-dropbox
```

接下来，你可以在应用程序的某个服务提供者的 `boot` 方法中注册该驱动。为此，你应该使用 `Storage` 门面的 `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` 驱动。