文件存储

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

引言

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

配置

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

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

[!NOTE]
您可以配置任意数量的磁盘，甚至可以拥有使用相同驱动程序的多个磁盘。

本地驱动程序

当使用 local 驱动器时，所有文件操作都相对于 root 目录，该目录在您的 filesystems 配置文件中定义。默认情况下，此值设置为 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 命令：

bash

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 命令可用于销毁您配置的符号链接：

bash

php artisan storage:unlink

驱动程序先决条件

S3 驱动配置

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

bash

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

bash

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'),

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

SFTP 驱动配置

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

bash

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

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

php

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

bash

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

bash

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

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

php

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

亚马逊 S3 兼容文件系统

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

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

php

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

MinIO

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

ini

AWS_URL=http://localhost:9000/local

[!警告]
通过 temporaryUrl 方法生成临时存储 URL 在使用 MinIO 时可能无法正常工作如果客户端无法访问 endpoint。

获取磁盘实例

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

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

按需磁盘

有时您可能希望在运行时使用给定的配置创建一个磁盘，而该配置并未实际存在于您应用程序的 filesystems 配置文件中。为此，您可以将一个配置数组传递给 Storage 门面的 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 目录。

[!WARNING]
当使用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。此方法接受一个路径和一个 DateTime 实例，用于指定 URL 何时过期：

php

use Illuminate\Support\Facades\Storage;

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

启用本地临时 URL

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

php

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

S3 请求参数

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

php

$url = Storage::temporaryUrl(
    'file.jpg',
    now()->addMinutes(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
{
    /**
     * 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

[!WARNING]
生成临时上传 URL 的能力仅由 s3 驱动支持。

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

php

use Illuminate\Support\Facades\Storage;

['url' => $url, 'headers' => $headers] = Storage::temporaryUploadUrl(
    'file.jpg', now()->addMinutes(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 底层的流支持。请记住，所有文件路径都应指定为相对于磁盘配置的"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)) {
    // The file could not be written to disk...
}

如果您愿意，您可以在您的文件系统磁盘的配置数组中定义 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;

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

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
{
    /**
     * 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 facade 上的 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(); // 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 方法设置可见性：

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

测试

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

php

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

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

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

bash

composer require spatie/flysystem-dropbox

接下来，你可以在你的应用程序的某个 [服务提供者](/docs/laravel/12.x/zh-cn/providers) 的 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
{
    /**
     * 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 驱动了。

文件存储

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

引言

配置

[!NOTE]
您可以配置任意数量的磁盘，甚至可以拥有使用相同驱动程序的多个磁盘。

本地驱动程序

php

use Illuminate\Support\Facades\Storage;

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

公共磁盘

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

bash

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 命令可用于销毁您配置的符号链接：

bash

php artisan storage:unlink

驱动程序先决条件

S3 驱动配置

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

bash

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

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

bash

composer require league/flysystem-ftp "^3.0"

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

bash

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

php

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

作用域限定的只读文件系统

bash

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

php

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

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

bash

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

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

php

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

亚马逊 S3 兼容文件系统

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

php

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

MinIO

ini

AWS_URL=http://localhost:9000/local

[!警告]
通过 temporaryUrl 方法生成临时存储 URL 在使用 MinIO 时可能无法正常工作如果客户端无法访问 endpoint。

获取磁盘实例

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

按需磁盘

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')) {
    // ...
}

下载文件

php

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

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

文件 URL

php

use Illuminate\Support\Facades\Storage;

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

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

[!WARNING]
当使用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。此方法接受一个路径和一个 DateTime 实例，用于指定 URL 何时过期：

php

use Illuminate\Support\Facades\Storage;

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

启用本地临时 URL

php

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

S3 请求参数

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

php

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

自定义临时URL

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
{
    /**
     * 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

[!WARNING]
生成临时上传 URL 的能力仅由 s3 驱动支持。

php

use Illuminate\Support\Facades\Storage;

['url' => $url, 'headers' => $headers] = Storage::temporaryUploadUrl(
    'file.jpg', now()->addMinutes(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');

文件路径

php

use Illuminate\Support\Facades\Storage;

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

存储文件

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)) {
    // The file could not be written to disk...
}

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

自动流式传输

php

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

php

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

文件上传

php

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

你也可以调用 Storage facade 上的 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();

php

$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...

文件可见性

您可以在写入文件时通过 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');

测试

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

php

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

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

        // 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');
    }
}

[!警告]
此 image 方法需要 GD 扩展。

自定义文件系统

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

bash

composer require spatie/flysystem-dropbox

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
{
    /**
     * 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
            );
        });
    }
}

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

文档导航

文件存储

引言

配置

本地驱动程序

公共磁盘

驱动程序先决条件

S3 驱动配置

FTP 驱动程序配置

SFTP 驱动配置

作用域限定的只读文件系统

亚马逊 S3 兼容文件系统

MinIO

获取磁盘实例

按需磁盘

检索文件

下载文件

文件 URL

URL 主机自定义

临时 URL

启用本地临时 URL

S3 请求参数

自定义临时URL

临时上传URL

文件元数据

文件路径

存储文件

写入失败

文件的前置与追加

复制和移动文件

自动流式传输

文件上传

指定文件名

指定磁盘

其他上传文件信息

文件可见性

本地文件和可见性

删除文件

目录

获取目录中的所有文件

获取一个目录下的所有目录

创建目录

删除目录

测试

自定义文件系统

文件存储

引言

配置

本地驱动程序

公共磁盘

驱动程序先决条件

S3 驱动配置

FTP 驱动程序配置

SFTP 驱动配置

作用域限定的只读文件系统

亚马逊 S3 兼容文件系统

MinIO

获取磁盘实例

按需磁盘

检索文件

下载文件

文件 URL

URL 主机自定义

临时 URL

启用本地临时 URL

S3 请求参数

自定义临时URL

临时上传URL

文件元数据

文件路径

存储文件

写入失败

文件的前置与追加

复制和移动文件

自动流式传输

文件上传

指定文件名

指定磁盘

其他上传文件信息

文件可见性