文件存储

• 简介
• 配置
  • 公共磁盘
  • 本地驱动
  • 驱动前提
  • 缓存
• 获取磁盘实例
• 获取文件
  • 下载文件
  • 文件 URL
  • 文件元数据
• 存储文件
  • 文件上传
  • 文件可见性
• 删除文件
• 目录
• 自定义文件系统

简介

Laravel 提供了强大的文件系统抽象功能，这得益于 Frank de Jonge 强大的 Flysystem PHP 扩展包。Laravel Flysystem 整合为使用本地文件系统、 Amazon S3 和 Rackspace 云存储提供了简单易用的驱动。更棒的是，由于每个系统的 API 保持相同，在这些存储选项之间切换非常简单。

配置

文件系统的配置文件位于 config/filesystems.php。在此文件中可以配置所有「磁盘」。每个磁盘代表了特定的驱动和存储位置。每种支持的驱动的示例配置都包含在配置文件中。因此，可以根据个人存储喜好和凭证修改配置。

当然，可以根据个人喜好配置任意数量的磁盘，甚至可以有多个使用相同驱动的磁盘。

公共磁盘

public 磁盘适用于要公开访问的文件。默认情况下，public 磁盘使用 local 驱动并将这些文件存储在 storage/app/public 目录。要让它们可以通过网络访问，应该创建一个从 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，S3 或 Rackspace 驱动之前，需要通过 Composer 安装合适的扩展包：

• SFTP: league/flysystem-sftp ~1.0
• Amazon S3: league/flysystem-aws-s3-v3 ~1.0
• Rackspace: 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',

    // 可选的 FTP 设置
    // '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',

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

    // 可选的 SFTP 设置
    // '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 应该是一个包含磁盘名，过期的秒数和缓存前缀等缓存选项的数组：

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

    // 其它磁盘选项

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

获取磁盘实例

Storage Facade 可用于和任何配置的磁盘进行交互。例如，可以使用此 Facade 的 put 方法存储头像到默认磁盘上。如果在 Storage Facade 调用方法前没有先调用 disk 方法，则此方法会自动传递给默认磁盘：

use Illuminate\Support\Facades\Storage;

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

如果应用要和多个磁盘进行交互，可以在 Storage Facade 上使用 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

可以使用 url 方法获取给定文件的 URL。如果使用 local 驱动，通常只会将 /storage 添加到给定路径的前面，然后返回该文件的相对 URL。如果使用 s3 或 rackspace 驱动，会返回完整路径的远程 URL：

use Illuminate\Support\Facades\Storage;

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

注意，如果使用 local 驱动，所有要公开访问的文件都应放在 storage/app/public 目录。此外，还应该创建一个从 public/storage 到 storage/app/public 的 软链接。

临时 URL

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

$url = Storage::temporaryUrl(
    'file.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('file.jpg');

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

$time = Storage::lastModified('file.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;

// 自动生成唯一 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）时，如果想要文件是可公开访问的，这会很有用。

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/file.jpg', 'new/file.jpg');

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

文件上传

在 Web 应用中，一个最常见的存储文件的用例是上传文件，例如用户图片、照片和文档。Laravel 中可以在上传文件实例上使用 store 方法轻松存储上传文件。带上希望存储上传文件的路径调用 store 方法：

namespace App\Http\Controllers;

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

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 方法来完成同样的操作：

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

指定文件名

如果不想存储的文件自动指定文件名，可以使用 storeAs 方法，它接收路径、文件名、磁盘（可选）作为其参数：

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

当然，也可以使用 Storage Facade 的 putFileAs 方法来完成同样的操作：

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

指定磁盘

默认情况下，此方法会使用默认磁盘。如果要指定其它磁盘，将磁盘名作为第二个参数传递给 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(['file.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);

// Recursive...
$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 Facade 的 extend 方法定义自定义驱动：

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
{
    /**
     * 注册后启动服务
     *
     * @return void
     */
    public function boot()
    {
        Storage::extend('dropbox', function ($app, $config) {
            $client = new DropboxClient(
                $config['authorization_token']
            );

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

    /**
     * 注册容器绑定
     *
     * @return void
     */
    public function register()
    {
        //
    }
}

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

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