[ Laravel 5.7 文档 ] 进阶系列 —— 文件存储

简介

Laravel 基于 Frank de Jonge 开发的 PHP 包 Flysystem 提供了强大的文件系统抽象层。Laravel 集成 Flysystem 以便使用不同驱动简化对文件系统的操作，这些驱动包括本地文件系统、Amazon S3 以及 Rackspace 云存储。此外，在这些存储选项之间切换非常简单，因为对不同系统而言，API 是一致的。

配置

文件系统配置文件位于 config/filesystems.php 。在该文件中可以配置所有“磁盘”，每个磁盘描述了特定的存储驱动和存储路径。该配置文件为每种支持的驱动提供了示例配置，所以，简单编辑该配置来应用你的存储参数和认证信息即可：

当然，你想配置多少磁盘就配置多少，多个磁盘也可以共用同一个驱动。

公共磁盘

public 磁盘用于存储可以被公开访问的文件，默认情况下， public 磁盘使用 local 驱动并将文件存储在 storage/app/public 目录下，要让这些文件可以通过 Web 浏览器访问到，还需要创建一个软链 public/storage 指向 storage/app/public ，这种方式可以将公开访问的文件保存在一个可以很容易被不同部署环境共享的目录，在使用零停机时间部署系统如 Envoyer 的时候尤其方便。

要创建这个软链，可以使用 Artisan 命令 storage:link ：

php artisan storage:link

文件被存储并且软链已经被创建的情况下，就可以使用辅助函数 asset 创建一个指向该文件的 URL：

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

本地驱动

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

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

驱动预备知识

Composer包

在使用 SFTP、Amazon S3 或 Rackspace 驱动之前，需要通过Composer 安装相应的包：

league/flysystem-sftp ~1.0
league/flysystem-aws-s3-v3 ~1.0
league/flysystem-rackspace ~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文件系统，可以使用以下示例配置：

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

    // Optional FTP Settings...
    // 'port'     => 21,
    // 'root'     => '',
    // 'passive'  => true,
    // 'ssl'      => true,
    // 'timeout'  => 30,
],

SFTP 驱动配置

Laravel 的 Flysystem 集成支持 SFTP 操作，不过，框架默认的 filesystems.php 配置文件并没有为此提供一个示例配置。如果你需要配置针对 SFTP 的文件系统配置，可以使用下面的示例配置：

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

    // Settings for SSH key based authentication...
    // 'privateKey' => '/path/to/privateKey',
    // 'password' => 'encryption-password',

    // Optional SFTP Settings...
    // 'port' => 22,
    // 'root' => '',
    // 'timeout' => 30,
],

Rackspace 驱动配置

Laravel 的 Flysystem 集成还支持 Rackspace 操作，同样，默认配置文件 filesystems.php 也没有提供对应的示例配置，如果你需要配置 Rackspace 文件系统，可以使用以下示例配置：

'rackspace' => [
    'driver'    => 'rackspace',
    'username'  => 'your-username',
    'key'       => 'your-key',
    'container' => 'your-container',
    'endpoint'  => 'https://identity.api.rackspacecloud.com/v2.0/',
    'region'    => 'IAD',
    'url_type'  => 'publicURL',
],

缓存

要为给定磁盘启用缓存，需要添加 cache 指令到磁盘的配置选项， cache 配置项应该是一个包含 disk 名称、 expire 时间（以秒为单位）以及缓存前缀 prefix 的数组：

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

    // Other Disk Options...

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

获取硬盘实例

我们可以使用 Storage 门面和上面配置的任意磁盘进行交互，例如，可以使用该门面上的 put 方法来存储头像到默认磁盘，如果调用 Storage 门面上的方法而没有调用 disk 方法，则调用的方法会自动被传递到默认磁盘：

use Illuminate\Support\Facades\Storage;
Storage::put('avatars/1', $fileContents);

与多个磁盘进行交互时，可以使用 Storage 门面上的 disk 方法访问特定磁盘：

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

获取文件

get 方法用于获取给定文件的内容，该方法将会返回该文件的原生字符串内容。需要注意的是，所有文件路径都是相对于配置文件中指定的磁盘默认根目录：

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

exists 方法用于判断给定文件是否存在于磁盘上：

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

下载文件

download 方法可用于生成强制用户浏览器下载给定路径文件的响应。 download 方法接收一个文件名作为第二个参数用于决定用户下载时看到的文件名。最后，你可以传递一个 HTTP 请求头数组作为该方法的第三个参数：

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

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

文件 URL

使用 local 或 s3 驱动时，可以使用 url 方法获取给定文件的 URI。如果你使用的是 local 驱动，通常会在给定路径前加上 /storage ，并返回该文件的相对 URL；如果使用的是 s3 或 rackspace 驱动，则会返回完整的远程 URL：

use Illuminate\Support\Facades\Storage;
$url = Storage::url('file1.jpg');

注：记住，如果你在使用 local 驱动，所有需要公开访问的文件都应该存放在 storage/app/public 目录下，此外，你还需要创建一个指向 storage/app/public 目录的软链接 public/storage 。

临时 URL

对于使用 s3 或 rackspace 驱动存储文件的系统，可以使用 temporaryUrl 方法创建临时 URL 到给定文件，该方法接收一个路径参数和指定 URL 何时过期的 DateTime 实例：

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

自定义本地主机 URL

如果你想要预定义使用 local 驱动磁盘存放文件的主机，可以添加 url 选项到磁盘配置数组：

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

文件元信息

除了读写文件之外，Laravel 还可以提供文件本身的信息。例如， size 方法可用于以字节方式返回文件大小：

use Illuminate\Support\Facades\Storage;
$size = Storage::size('file1.jpg');

lastModified 方法以 UNIX 时间戳

格式返回文件最后一次修改时间：

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

存储文件

put 方法可用于存储原生文件内容到磁盘。此外，还可以传递一个 PHP 资源到 put 方法，该方法将会使用 Flysystem 底层的流支持。在处理大文件的时候推荐使用文件流：

use Illuminate\Support\Facades\Storage;

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

自动文件流

如果你想要 Laravel 自动将给定文件流输出到对应存储路径，可以使用 putFile 或 putFileAs 方法，该方法接收 Illuminate\Http\File 或 Illuminate\Http\UploadedFile 实例，然后自动将文件流保存到期望的路径：

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

// 自动计算文件名的MD5值...
Storage::putFile('photos', new File('/path/to/photo'));

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

这里有一些关于 putFile 方法的重要注意点，注意到我们只指定了目录名，默认情况下， putFile 方法会基于文件内容自动生成文件名。实现原理是对文件内容进行 MD5 哈希运算。 putFile 方法会返回文件路径，包括文件名，以便于在数据库中进行存储。

putFile 和 putFileAs 方法还接收一个用于指定存储文件“可见度”的参数，这在你将文件存储到云存储（如S3）平台并期望文件可以被公开访问时很有用：

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

添加内容到文件开头/结尾

prepend 和 append 方法允许你轻松插入内容到文件开头/结尾：

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

拷贝 & 移动文件

copy 方法将磁盘中已存在的文件从一个地方拷贝到另一个地方，而 move 方法将磁盘中已存在的文件从一定地方移到到另一个地方：

Storage::copy('old/file1.jpg', 'new/file1.jpg');
Storage::move('old/file1.jpg', 'new/file1.jpg');

文件上传

在 Web 应用中，最常见的存储文件案例就是存储用户上传的文件，如用户头像、照片和文档等。Laravel 通过上传文件实例上提供的 store 方法让存储上传文件变得简单。你只需要传入上传文件保存的路径并调用 store 方法即可：

<?php

namespace App\Http\Controllers;

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

class UserAvatarController extends Controller
{
    /**
     * 更新用户头像.
     *
     * @param  Request  $request
     * @return Response
     * @translator laravelacademy.org
     */
    public function update(Request $request)
    {
        $path = $request->file('avatar')->store('avatars');

        return $path;
    }
}

这里有一些需要注意的重要事项，在这里我们只指定了目录名，而不是文件名。默认情况下， store 方法会基于文件内容自动生成文件名，这通过对文件内容进行 MD5 实现。 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
);

指定磁盘

默认情况下， store 方法会使用默认的磁盘，如果你想要指定其它磁盘，传递磁盘名称作为 store 方法的第二个参数即可：

$path = $request->file('avatar')->store(
    'avatars/'.$request->user()->id, 's3'
);

文件可见度

在 Laravel 的 Flysystem 集成中，“可见度”是对不同平台上文件权限的抽象，文件可以被声明成 public 或 private ，当文件被声明为 public ，意味着文件可以被其他人访问。例如，使用S3时，可以获取 public 文件的 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');

删除文件

delete 方法接收单个文件名或多个文件数组并将其从磁盘移除：

use Illuminate\Support\Facades\Storage;

Storage::delete('file.jpg');
Storage::delete(['file1.jpg', 'file2.jpg']);

如果需要的话你可以指定从哪个磁盘删除文件：

use Illuminate\Support\Facades\Storage;

Storage::disk('s3')->delete('folder_path/file_name.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);

自定义文件系统

Laravel 的 Flysystem 集成开箱提供了多个“驱动”，不过，Flysystem 的功能并不止步于此，还为许多其他存储系统提供了适配器。通过使用这些额外的适配器你可以在自己的 Laravel 应用创建自定义的驱动。

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

composer require spatie/flysystem-dropbox

接下来，需要创建一个服务提供者如 DropboxServiceProvider 。在该提供者的 boot 方法中，你可以使用 Storage 门面的 extend 方法定义自定义驱动：

<?php

namespace App\Providers;

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

class DropboxServiceProvider extends ServiceProvider
{
    /**
     * Perform post-registration booting of services.
     *
     * @return void
     */
    public function boot()
    {
        Storage::extend('dropbox', function ($app, $config) {
            $client = new DropboxClient(
                $config['authorizationToken']
            );

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

    /**
     * Register bindings in the container.
     *
     * @return void
     */
    public function register()
    {
        //
    }
}

extend 方法的第一个参数是驱动名称，第二个参数是获取 $app 和 $config 变量的闭包。该解析器闭包必须返回一个 League\Flysystem\Filesystem 实例。 $config 变量包含了定义在配置文件 config/filesystems.php 中为特定磁盘定义的选项。

创建好注册扩展的服务提供者后，就可以使用配置文件 config/filesystem.php 中的 dropbox 驱动了。