档案储存

• Introduction
• Configuration
  • 本地司机
  • 公共磁盘
  • 驱动程序先决条件
  • 作用域和只读文件系统
  • Amazon S3 兼容文件系统
• 获取磁盘实例
  • 按需磁盘
• 检索文件
  • 下载文件
  • 文件网址
  • 临时网址
  • 文件元数据
• 存储文件
  • 前置和附加到文件
  • 复制和移动文件
  • 自动流媒体
  • 文件上传
  • 文件可见性
• 删除文件
• Directories
• Testing
• 自定义文件系统

#Introduction

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

#Configuration

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

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

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

#本地司机

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

use Illuminate\Support\Facades\Storage;

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

#公共磁盘

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

要使这些文件可以从 Web 访问，您应该创建一个符号链接public/storage 到storage/app/public.使用此文件夹约定会将您的可公开访问的文件保存在一个目录中，当使用零停机时间部署系统（如Envoyer.

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

php artisan storage:link

存储文件并创建符号链接后，您可以使用asset 帮手：

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

您可以在您的filesystems 配置文件。运行时将创建每个配置的链接storage:link 命令：

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

#驱动程序先决条件

S3 驱动程序配置

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

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

S3 驱动程序配置信息位于您的config/filesystems.php 配置文件。此文件包含 S3 驱动程序的示例配置数组。您可以使用自己的 S3 配置和凭据自由修改此数组。为方便起见，这些环境变量与 AWS CLI 使用的命名约定相匹配。

FTP 驱动程序配置

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

composer require league/flysystem-ftp "^3.0"

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

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

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

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

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

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

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

您可以通过定义一个利用scoped 司机。例如，您可以创建一个磁盘，将您现有的s3 disk 到一个特定的路径前缀，然后使用你的作用域磁盘的每个文件操作都将使用指定的前缀：

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

#Amazon S3 兼容文件系统

默认情况下，您的应用程序的filesystems 配置文件包含磁盘配置s3 磁盘。除了使用此磁盘与 Amazon S3 交互外，您还可以使用它与任何 S3 兼容的文件存储服务交互，例如MinIO 或者数字海洋空间.

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

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

MinIO

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

AWS_URL=http://localhost:9000/local

Warning
通过生成临时存储 URLtemporaryUrl 使用 MinIO 时不支持方法。

#获取磁盘实例

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

use Illuminate\Support\Facades\Storage;

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

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

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

这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。如果您正在使用local 驱动程序，这通常只是前置/storage 到给定路径并返回文件的相对 URL。如果您正在使用s3 驱动程序，将返回完全限定的远程 URL：

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 主机自定义

如果您想为使用生成的 URL 预定义主机Storage 门面，你可以添加一个url 磁盘配置阵列的选项：

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

#临时网址

使用temporaryUrl 方法，您可以为使用s3 司机。此方法接受一个路径和一个DateTime 指定 URL 何时过期的实例：

use Illuminate\Support\Facades\Storage;

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

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

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

如果您需要自定义为特定存储磁盘创建临时 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
{
    /**
     * 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])
                );
            }
        );
    }
}

临时上传网址

Warning 仅支持生成临时上传 URL 的功能s3 司机。

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

use Illuminate\Support\Facades\Storage;

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

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

#文件元数据

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

use Illuminate\Support\Facades\Storage;

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

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

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

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

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

文件路径

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

use Illuminate\Support\Facades\Storage;

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

#存储文件

这put 方法可用于将文件内容存储在磁盘上。您也可以通过 PHPresource 到put 方法，它将使用 Flysystem 的底层流支持。请记住，所有文件路径都应相对于为磁盘配置的“根”位置指定：

use Illuminate\Support\Facades\Storage;

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

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

写入失败

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

if (! Storage::put('file.jpg', $contents)) {
    // The file could not be written to disk...
}

如果你愿意，你可以定义throw 文件系统磁盘配置阵列中的选项。当此选项定义为true, "write" 方法如put 将抛出一个实例League\Flysystem\UnableToWriteFile 当写操作失败时：

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

#前置和附加到文件

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

#自动流媒体

将文件流式传输到存储可显着减少内存使用量。如果你希望 Laravel 自动管理将给定文件流式传输到你的存储位置，你可以使用putFile 或者putFileAs 方法。此方法接受Illuminate\Http\File 或者Illuminate\Http\UploadedFile 实例并将自动将文件流式传输到您想要的位置：

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 公开访问该文件，这将特别有用：

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

#文件上传

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

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
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 facade 执行与上面示例相同的文件存储操作：

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

指定文件名

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

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

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

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

Warning
不可打印和无效的 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(); // 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 驱动程序时，您可以检索 URLspublic 文件。

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

本地文件和可见性

当使用local 司机，public visibility 翻译成0755 目录权限和0644 文件的权限。您可以修改应用程序中的权限映射filesystems 配置文件：

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

#删除文件

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

#Directories

获取目录中的所有文件

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

#Testing

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

<?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 a given directory is empty...
        Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
    }
}

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

Warning 这image 方法需要GD扩展.

#自定义文件系统

Laravel 的 Flysystem 集成提供了对几个开箱即用的“驱动程序”的支持；然而，Flysystem 并不局限于这些，它还有适用于许多其他存储系统的适配器。如果你想在你的 Laravel 应用程序中使用这些额外的适配器之一，你可以创建一个自定义驱动程序。

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

composer require spatie/flysystem-dropbox

接下来，您可以在boot 您的应用程序之一的方法服务供应商.为此，您应该使用extend 的方法Storage 正面：

<?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 配置文件。