文件存储
介绍
Laravel 通过 Frank de Jonge 的 Flysystem PHP 包提供了强大的文件系统抽象。Laravel Flysystem集成提供了简单的驱动程序，用于处理本地文件系统、SFTP和Amazon S3。更好的是，在本地开发机器和生产服务器之间切换存储选项非常简单，因为每个系统的API保持相同。
配置
Laravel 的文件系统配置文件位于 config/filesystems.php。在此文件中，您可以配置所有文件系统的“磁盘”。每个磁盘都代表一个特定的存储驱动程序和存储位置。配置文件中包含了每个受支持驱动程序的示例配置，因此您可以根据自己的存储偏好和凭据修改配置。
本地驱动程序与在运行 Laravel 应用程序的服务器上存储的文件进行交互，而 s3 驱动程序用于向亚马逊的 S3 云存储服务写入。
您可以配置任意数量的磁盘，甚至可以拥有多个使用相同驱动程序的磁盘。
本地驱动
使用本地驱动程序时，所有文件操作都相对于文件系统配置文件中定义的根目录。默认情况下，此值设置为storage/app 目录。因此，以下方法将写入 storage/app/example.txt：
use Illuminate\Support\Facades\Storage;
Storage::disk('local')->put('example.txt', 'Contents');
公共磁盘
在应用程序的文件系统配置文件中包含的 public 磁盘用于存储将公开访问的文件。默认情况下，public磁盘使用本地驱动程序，并将文件存储在 storage/app/public 目录中。
要使这些文件可以从 Web 中访问，您应该在 public/storage 和 storage/app/public 之间创建一个符号链接。使用此文件夹约定，可以将公开访问的文件保存在一个目录中，在使用像 Envoyer 这样的零停机部署系统时可以轻松共享。
要创建符号链接，您可以使用 storage:link Artisan命令：
php artisan storage:link
存储文件并创建符号链接后，可以使用 asset 助手创建文件的 URL：
echo asset('storage/file.txt');
您可以在文件系统配置文件中配置其他符号链接。每次运行 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" --with-all-dependencies
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'),
// 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 软件包：
composer require league/flysystem-path-prefixing "^3.0"
您可以通过定义一个使用作用域驱动程序的磁盘来创建路径作用域的现有文件系统磁盘的实例。例如，您可以创建一个磁盘，将现有的s3磁盘范围限制为特定的路径前缀，然后使用您的作用域磁盘进行的每个文件操作都将使用指定的前缀：
's3-videos' => [
'driver' => 'scoped',
'disk' => 's3',
'prefix' => 'path/to/videos',
],
“只读”磁盘允许您创建不允许写操作的文件系统磁盘。在使用只读配置选项之前，您需要通过 Composer 软件包管理器安装另一个 Flysystem 软件包：
composer require league/flysystem-read-only "^3.0"
然后，您可以在一个或多个磁盘的配置数组中包含只读配置选项：
's3-videos' => [
'driver' => 's3',
// ...
'read-only' => true,
],
亚马逊 S3 兼容文件系统
默认情况下，应用程序的文件系统配置文件包含了 s3 磁盘的配置。除了使用此磁盘与 Amazon S3 交互之外，您还可以使用它与任何 S3 兼容的文件存储服务进行交互，如 MinIO 或 DigitalOcean Spaces。
通常，在更新磁盘的凭据以匹配您计划使用的服务的凭据之后，您只需更新 endpoint 配置选项的值即可。此选项的值通常可以通过 AWS_ENDPOINT 环境变量定义：
'endpoint' => env('AWS_ENDPOINT', 'https://minio:9000'),
MinIO
为了让 Laravel 的 Flysystem 集成在使用 MinIO 时生成正确的URL，您应该定义 AWS_URL 环境变量，以使其与应用程序的本地 URL 相匹配，并在 URL 路径中包含 Bucket 名称：
AWS_URL=http://localhost:9000/local
使用 MinIO 时，不支持通过
temporaryUrl方法生成临时存储 URL。
获取磁盘实例
Storage 门面可以用于与配置的任何磁盘进行交互。例如，您可以在门面上使用 put 方法将头像存储在默认磁盘上。如果在调用 Storage 门面上的方法之前没有调用 disk 方法，该方法将自动传递到默认磁盘：
use Illuminate\Support\Facades\Storage;
Storage::put('avatars/1', $content);
如果应用程序与多个磁盘交互，可以使用 Storage 门面上的 disk 方法来处理特定磁盘上的文件：
Storage::disk('s3')->put('avatars/1', $content);
按需磁盘
有时，您可能希望在运行时使用给定的配置创建一个磁盘，而不将该配置实际存在于应用程序的文件系统配置文件中。为此，可以将配置数组传递给 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。如果使用本地驱动程序，这通常只会将 /storage 前置到给定路径，并返回到文件的相对 URL。如果使用 s3 驱动程序，则会返回完全限定的远程 URL：
use Illuminate\Support\Facades\Storage;
$url = Storage::url('file.jpg');
使用本地驱动器时，所有应该公开访问的文件应放置在 storage/app/public 目录中。此外，您应在public/storage 下创建一个符号链接，指向 storage/app/public 目录。
使用本地驱动程序时，
url的返回值没有进行 URL 编码。出于这个原因，我们建议始终使用会创建有效 URL 的名称存储文件。
URL 主机自定义
如果要预定义使用 Storage 门面生成的 URL 的主机，可以将 url 选项添加到磁盘的配置数组中：
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL').'/storage',
'visibility' => 'public',
],
临时 URL
使用 temporaryUrl 方法，可以创建临时 URL，用于存储在 s3 驱动程序中的文件。此方法接受一个路径和指定 URL 何时过期的 DateTime 实例：
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])
);
}
);
}
}
临时上传URL
只支持
s3驱动程序生成临时上传 URL 的能力。
如果需要生成临时 URL，可用于直接从客户端应用程序上传文件，可以使用 temporaryUploadUrl 方法。此方法接受一个路径和指定 URL 何时过期的 DateTime 实例。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');
通过 mimeType 方法可以获取给定文件的 MIME 类型：
$mime = Storage::mimeType('file.jpg');
文件路径
可以使用 path 方法获取给定文件的路径。如果使用本地驱动程序，这将返回文件的绝对路径。如果使用 s3 驱动程序，此方法将返回 S3 存储桶中文件的相对路径：
use Illuminate\Support\Facades\Storage;
$path = Storage::path('file.jpg');
存储文件
put 方法可用于将文件内容存储到磁盘上。您还可以将 PHP 资源传递给 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 时，“写入”方法（如 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 应用程序中，存储文件最常见的用例之一就是存储用户上传的文件，如照片和文档。使用 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 方法将返回文件的路径，因此您可以将包括生成的文件名在内的路径存储在数据库中。
您还可以在 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(); // Generate a unique, random name...
$extension = $file->extension(); // Determine the file's extension based on the file's MIME type...
文件可见性
在 Laravel 的 Flysystem 集成中，"可见性" 是跨多个平台的文件权限的抽象。文件可以声明为公共或私有。当文件声明为公共时，您指示文件通常应对其他人可访问。例如，在使用 S3 驱动程序时，您可以检索公共文件的 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 方法以公开可见性存储上传的文件：
$path = $request->file('avatar')->storePublicly('avatars', 's3');
$path = $request->file('avatar')->storePubliclyAs(
'avatars',
$request->user()->id,
's3'
);
本地文件和可见性
使用本地驱动程序时，公共可见性相当于目录的 0755 权限和文件的 0644 权限。您可以在应用程序的文件系统配置文件中修改权限映射：
'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');
目录
获取目录中的所有文件
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
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 测试文档中有关文件上传的信息。
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 驱动程序。
No Comments