文件存储

介绍
配置
获取磁盘实例
检索文件
存储文件
- 文件上传
- 文件可见性
删除文件
目录
自定义文件系统

介绍

Laravel 提供了一个强大的文件系统抽象，这要归功于 Frank de Jonge 的优秀 PHP 包 Flysystem。Laravel 的 Flysystem 集成提供了简单易用的驱动程序，用于处理本地文件系统和 Amazon S3。更好的是，切换这些存储选项非常简单，因为每个系统的 API 都保持不变。

配置

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

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

公共磁盘

public 磁盘用于将要公开访问的文件。默认情况下，public 磁盘使用 local 驱动程序，并将这些文件存储在 storage/app/public 中。为了使它们可以从网络访问，您应该创建一个从 public/storage 到 storage/app/public 的符号链接。当使用零停机时间部署系统（如 Envoyer）时，这种约定将使您的公开访问文件保存在一个目录中，便于跨部署共享。

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

php

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

本地驱动

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

php

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

权限

public 可见性对目录转换为 0755，对文件转换为 0644。您可以在 filesystems 配置文件中修改权限映射：

php

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

驱动程序先决条件

Composer 包

在使用 SFTP 或 S3 驱动程序之前，您需要通过 Composer 安装相应的包：

SFTP: league/flysystem-sftp ~1.0
Amazon S3: league/flysystem-aws-s3-v3 ~1.0

为了性能，绝对必须使用缓存适配器。您将需要一个额外的包：

CachedAdapter: league/flysystem-cached-adapter ~1.0

S3 驱动程序配置

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

FTP 驱动程序配置

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

php

'ftp' => [
    'driver' => 'ftp',
    'host' => 'ftp.example.com',
    'username' => 'your-username',
    'password' => 'your-password',

    // 可选的 FTP 设置...
    // 'port' => 21,
    // 'root' => '',
    // 'passive' => true,
    // 'ssl' => true,
    // 'timeout' => 30,
],

SFTP 驱动程序配置

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

php

'sftp' => [
    'driver' => 'sftp',
    'host' => 'example.com',
    'username' => 'your-username',
    'password' => 'your-password',

    // SSH 密钥认证的设置...
    // 'privateKey' => '/path/to/privateKey',
    // 'password' => 'encryption-password',

    // 可选的 SFTP 设置...
    // 'port' => 22,
    // 'root' => '',
    // 'timeout' => 30,
],

缓存

要为给定磁盘启用缓存，您可以在磁盘的配置选项中添加 cache 指令。cache 选项应为包含 disk 名称、以秒为单位的 expire 时间和缓存 prefix 的数组：

php

's3' => [
    'driver' => 's3',

    // 其他磁盘选项...

    'cache' => [
        'store' => 'memcached',
        'expire' => 600,
        'prefix' => 'cache-prefix',
    ],
],

获取磁盘实例

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

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

检索文件

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

php

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

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

php

$exists = Storage::disk('s3')->exists('file.jpg');

可以使用 missing 方法确定磁盘上是否缺少文件：

php

$missing = 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 目录。

临时URL

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

php

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

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

php

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

URL 主机自定义

如果您希望预定义使用 Storage facade 生成的文件 URL 的主机，可以在磁盘的配置数组中添加 url 选项：

php

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

文件元数据

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

php

use Illuminate\Support\Facades\Storage;

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

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

php

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

存储文件

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

php

use Illuminate\Support\Facades\Storage;

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

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

自动流

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

php

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

// 自动为文件名生成唯一 ID...
Storage::putFile('photos', new File('/path/to/photo'));

// 手动指定文件名...
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

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

putFile 和 putFileAs 方法还接受一个参数来指定存储文件的“可见性”。如果您将文件存储在云磁盘（如 S3）上，并希望文件可以公开访问，这特别有用：

php

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

在文件中添加和附加

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

文件上传

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

php

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class UserAvatarController extends Controller
{
    /**
     * 更新用户的头像。
     *
     * @param  Request  $request
     * @return Response
     */
    public function update(Request $request)
    {
        $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\Util::normalizePath 方法进行规范化。

指定磁盘

默认情况下，此方法将使用您的默认磁盘。如果您希望指定其他磁盘，请将磁盘名称作为 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 方法：

php

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

extension 方法可用于获取上传文件的文件扩展名：

php

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

文件可见性

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

删除文件

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('folder_path/file_name.jpg');

自定义文件系统

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

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

php

composer require spatie/flysystem-dropbox

接下来，您应该创建一个服务提供者，例如 DropboxServiceProvider。在提供者的 boot 方法中，您可以使用 Storage facade 的 extend 方法定义自定义驱动程序：

php

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Storage;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Filesystem;
use Spatie\Dropbox\Client as DropboxClient;
use Spatie\FlysystemDropbox\DropboxAdapter;

class DropboxServiceProvider extends ServiceProvider
{
    /**
     * 注册任何应用程序服务。
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * 启动任何应用程序服务。
     *
     * @return void
     */
    public function boot()
    {
        Storage::extend('dropbox', function ($app, $config) {
            $client = new DropboxClient(
                $config['authorization_token']
            );

            return new Filesystem(new DropboxAdapter($client));
        });
    }
}

extend 方法的第一个参数是驱动程序的名称，第二个参数是接收 $app 和 $config 变量的闭包。解析器闭包必须返回 League\Flysystem\Filesystem 的实例。$config 变量包含在 config/filesystems.php 中为指定磁盘定义的值。

接下来，在 config/app.php 配置文件中注册服务提供者：

php

'providers' => [
    // ...
    App\Providers\DropboxServiceProvider::class,
];

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

文件存储

介绍

配置

公共磁盘

本地驱动

权限

驱动程序先决条件

Composer 包

S3 驱动程序配置

FTP 驱动程序配置

SFTP 驱动程序配置

缓存

获取磁盘实例

检索文件

下载文件

文件URL

临时URL

URL 主机自定义

文件元数据

存储文件

自动流

在文件中添加和附加

复制和移动文件

文件上传

指定文件名

指定磁盘

其他文件信息

文件可见性

删除文件

目录

获取目录中的所有文件

获取目录中的所有目录

创建目录

删除目录

自定义文件系统

文件存储 ​

介绍 ​

配置 ​

公共磁盘 ​

本地驱动 ​

权限 ​

驱动程序先决条件 ​

Composer 包 ​

S3 驱动程序配置 ​

FTP 驱动程序配置 ​

SFTP 驱动程序配置 ​

缓存 ​

获取磁盘实例 ​

检索文件 ​

下载文件 ​

文件URL ​

临时URL ​

URL 主机自定义 ​

文件元数据 ​

存储文件 ​

自动流 ​

在文件中添加和附加 ​

复制和移动文件 ​

文件上传 ​

指定文件名 ​

指定磁盘 ​

其他文件信息 ​

文件可见性 ​

删除文件 ​

目录 ​

获取目录中的所有文件 ​

获取目录中的所有目录 ​

创建目录 ​

删除目录 ​

自定义文件系统 ​

文件存储

介绍

配置

公共磁盘

本地驱动

权限

驱动程序先决条件

Composer 包

S3 驱动程序配置

FTP 驱动程序配置

SFTP 驱动程序配置

缓存

获取磁盘实例

检索文件

下载文件

文件URL

临时URL

URL 主机自定义

文件元数据

存储文件

自动流

在文件中添加和附加

复制和移动文件

文件上传

指定文件名

指定磁盘

其他文件信息

文件可见性

删除文件

目录

获取目录中的所有文件

获取目录中的所有目录

创建目录

删除目录

自定义文件系统