文件存储

简介

Laravel 提供了一个强大的文件系统抽象,这得益于 Frank de Jonge 强大的 Flysystem 扩展包。Laravel 文件系统集成为使用本地文件系统、Amazon S3 和 Rackspace 云存储提供了简单易用的驱动程序。更棒的是,由于每个系统的 API 保持不变,所以在这些存储选项之间切换是非常简单的。

配置

文件系统的配置文件位于 config/filesystems.php 。在这个文件中你可以配置所有「磁盘」。每个磁盘代表特定的存储驱动及存储位置。每种支持的驱动程序的示例配置都包含在配置文件中。因此,只需要修改配置即可反映你的存储偏好和凭据。

当然,你可以根据需要配置多个磁盘,甚至你还可以使多个磁盘共用同一个驱动。

公共磁盘

public 磁盘适用于要公开访问的文件。默认情况下, public 磁盘使用 local 驱动,并且将这些文件存储在 storage/app/public 目录下。为了使它们能通过网络访问,你需要创建 public/storagestorage/app/public 的符号链接。这种方式能把可公开访问文件都保留在同一个目录下,以便在使用零停机时间部署系统如 Envoyer 的时候,就可以轻松地在不同的部署之间共享这些文件。

你可以使用 Artisan 命令 storage:link 来创建符号链接:

  1. php artisan storage:link

当然,一旦一个文件被存储并且已经创建了符号链接,你就可以使用辅助函数 asset 来创建文件的 URL:

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

本地驱动

使用 local 驱动时,所有文件操作都与你在配置文件中定义的 root 目录相关。该目录的默认值是 storage/app 。因此,以下方法会把文件存储在 storage/app/file.txt 中:

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

驱动程序先决条件

Composer 包

在使用 S3 或 Rackspace 的驱动之前,你需要通过 Composer 安装相应的软件包:

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

S3 驱动配置

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

FTP 驱动配置

Laravel 的文件系统集成能很好的支持 FTP,不过 FTP 的配置示例并没有被包含在框架默认的 filesystems.php 文件中。需要的话可以使用下面的示例配置:

  1. 'ftp' => [
  2. 'driver' => 'ftp',
  3. 'host' => 'ftp.example.com',
  4. 'username' => 'your-username',
  5. 'password' => 'your-password',
  6. // Optional FTP Settings...
  7. // 'port' => 21,
  8. // 'root' => '',
  9. // 'passive' => true,
  10. // 'ssl' => true,
  11. // 'timeout' => 30,
  12. ],

SFTP 驱动器的配置

Laravel 的 Flysystem 集成包与 SFTP 协同得非常好;不过,在该框架的默认配置文件 filesystems.php 中并没有包含示范配置。如果要配置 SFTP 文件系统,可以使用如下示例配置:

  1. 'sftp' => [
  2. 'driver' => 'sftp',
  3. 'host' => 'example.com',
  4. 'username' => 'your-username',
  5. 'password' => 'your-password',
  6. // 基于认证的 SSH key 设置...
  7. // 'privateKey' => '/path/to/privateKey',
  8. // 'password' => 'encryption-password',
  9. // 可选的 SFTP 设置...
  10. // 'port' => 22,
  11. // 'root' => '',
  12. // 'timeout' => 30,
  13. ],

Rackspace 驱动器的配置

Laravel 的 Flysystem 集成包与 Rackspace 协同得非常好;不过,在该框架的默认配置文件 filesystems.php 中并没有包含示范配置。如果要配置 Rackspace 文件系统,可以使用如下示例配置:

  1. 'rackspace' => [
  2. 'driver' => 'rackspace',
  3. 'username' => 'your-username',
  4. 'key' => 'your-key',
  5. 'container' => 'your-container',
  6. 'endpoint' => 'https://identity.api.rackspacecloud.com/v2.0/',
  7. 'region' => 'IAD',
  8. 'url_type' => 'publicURL',
  9. ],

获取 Disk 实例

facade 方式 Storage 可以用于与任何已配置磁盘互操作。例如该 facade 方式可以使用 put 方法存储头像到默认磁盘。如果调用 facade 方式 Storage 方法,并且一开始没有调用 disk 方法,那么所调用的方法会自动传递给默认的磁盘:

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

如果应用程序要与多个磁盘进行互操作,可使用 facade 方式 Storage 中的 disk 方法,对特定磁盘上的多个文件进行操作:

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

检索文件

get 方法可以用于检索文件的内容,此方法返回该文件的原始字符串内容。 切记,所有文件路径的指定都应该相对于为磁盘配置的 root 目录:

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

exists 方法可以用来判断磁盘上是否存在指定的文件:

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

下载文件

download 方法可用于生成一个响应,强制用户的浏览器在给定路径下载文件。 download 方法接受一个文件名作为方法的第二个参数,它将确定用户下载文件时看到的文件名。 最后,你可以传递一个 HTTP 头数组作为该方法的第三个参数:

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

文件 URLs

当使用 local 或者 s3 驱动时,你可以使用 url 方法来获取给定文件的 URL。如果你使用的是 local 驱动,一般只是在给定的路径前面加上 /storage 并返回一个相对的 URL 到那个文件。如果使用的是 s3 驱动,会返回完整的远程 URL:

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

{note} 切记,如果使用的是 local 驱动,则所有想被公开访问的文件都应该放在 storage/app/public 目录下。此外,你应该在 public/storage 创建一个符号链接 来指向 storage/app/public 目录。

临时 URLs

对于使用 s3 驱动来存储的文件,可以使用 temporaryUrl 方法创建给定文件的临时 URL 。这个方法接收路径和 DateTime 实例来指定 URL 何时过期:

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

自定义本地 URL 主机

如果要使用 local 驱动为存储在磁盘上的文件预定义主机,可以向磁盘配置数组添加一个 url 选项:

  1. 'public' => [
  2. 'driver' => 'local',
  3. 'root' => storage_path('app/public'),
  4. 'url' => env('APP_URL').'/storage',
  5. 'visibility' => 'public',
  6. ],

文件元数据

除了读写文件,Laravel 还可以提供有关文件本身的信息。例如,size 方法可用来获取文件的大小(以字节为单位):

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

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

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

保存文件

put 方法可用于将原始文件内容保存到磁盘上。你也可以传递 PHP 的 resourceput 方法,它将使用文件系统下的底层流支持。强烈建议在处理大文件时使用流:

  1. use Illuminate\Support\Facades\Storage;
  2. Storage::put('file.jpg', $contents);
  3. Storage::put('file.jpg', $resource);

自动流式传输

如果你想 Laravel 自动管理将给定文件流式传输到你想要的存储位置,你可以使用 putFileputFileAs 方法。这个方法接受 Illuminate\HTTP\FileIlluminate\HTTP\UploadedFile 实例,并自动将文件流式传输到你想要的位置:

  1. use Illuminate\Http\File;
  2. use Illuminate\Support\Facades\Storage;
  3. // 自动为文件名生成唯一的 ID...
  4. Storage::putFile('photos', new File('/path/to/photo'));
  5. // 手动指定文件名...
  6. Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

关于 putFile 方法有些重要的事情要注意。请注意,我们只指定一个目录名,而不是文件名。默认情况下,putFile 方法将生成唯一的 ID 作为文件名。该文件的路径将被 putFile 方法返回,因此可以将路径(包括生成的文件名)存储在数据库中。

putFileputFileAs 方法也接受一个参数来指定存储文件的「可见性」。如果你将文件存储在诸如 S3 的云盘上,并且该文件可以公开访问,这是特别有用的:

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

文件数据写入

prependappend 方法可以在文件的头部或尾部写入数据:

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

复制 & 移动文件

copy 方法可以复制文件到新地址,move 方法可以重命名文件或移动文件到新地址:

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

文件上传

Web 应用中,常用到文件存储的地方也就是上传头像、照片、文件等。Lavarel 上传文件实例的 store 方法可以轻松处理文件上传存储的问题。store 方法接受一个目录:

  1. <?php
  2. namespace App\Http\Controllers;
  3. use Illuminate\Http\Request;
  4. use App\Http\Controllers\Controller;
  5. class UserAvatarController extends Controller
  6. {
  7. /**
  8. * 更新用户头像
  9. *
  10. * @param Request $request
  11. * @return Response
  12. */
  13. public function update(Request $request)
  14. {
  15. $path = $request->file('avatar')->store('avatars');
  16. return $path;
  17. }
  18. }

上例需要注意几个问题。这里指定的是目录名,而不是文件名。默认情况下,store 方法自动生成唯一的 ID 作为文件名。store 方法返回包含文件名的路径,以便后续的数据库存储。

Storage 门面的 putFile 方法可以达到上面同样的操作效果:

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

自定义文件名

不想自动生成文件名的话,可以使用 storeAs 方法,它接受路径、文件名和可选的磁盘三个参数:

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

Storage 门面的 putFileAs 方法也可以达到上面的操作效果:

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

自定义磁盘

默认情况下,store 方法使用默认磁盘,如果想使用其它磁盘,可以给它传入磁盘名作为第二个参数:

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

文件可见性

Laravel 集成的 Flysystem 系统,对多平台的文件权限进行了「可见性」抽象。文件可声明为 publicprivate。通常,一个声明成 public 的文件,意味着对其他人可访问。例如,使用 S3 驱动时,就可以检索声明为 public 文件的 URL。

put 方法可以设置文件的可见性:

  1. use Illuminate\Support\Facades\Storage;
  2. Storage::put('file.jpg', $contents, 'public');

getVisibilitysetVisibility 方法可以对现存文件进行可见性的检查和设置:

  1. $visibility = Storage::getVisibility('file.jpg');
  2. Storage::setVisibility('file.jpg', 'public')

删除文件

delete 方法接受单个文件名或数组形式的文件名来删除磁盘上的文件:

  1. use Illuminate\Support\Facades\Storage;
  2. Storage::delete('file.jpg');
  3. Storage::delete(['file.jpg', 'file2.jpg']);

必要的话,可以指定磁盘名来删除其下的文件:

  1. use Illuminate\Support\Facades\Storage;
  2. Storage::disk('s3')->delete('folder_path/file_name.jpg');

目录

获取目录下所有文件

files 方法返回指定目录下的所有文件的数组。allFiles 方法返回指定目录下包含子目录的所有文件的数组:

  1. use Illuminate\Support\Facades\Storage;
  2. $files = Storage::files($directory);
  3. $files = Storage::allFiles($directory);

获取目录下所有的目录

directories 方法返回给定目录下的所有目录的数组。allDirectories 方法返回指定目录下的包含子目录的所有目录的数组:

  1. $directories = Storage::directories($directory);
  2. // 递归
  3. $directories = Storage::allDirectories($directory);

创建目录

makeDirectory 方法会递归创建目录:

  1. Storage::makeDirectory($directory);

删除目录

deleteDirectory 方法会删除指定目录及其所有文件:

  1. Storage::deleteDirectory($directory);

自定义文件系统

虽然 Laravel 的 文件系统提供了一系列开箱即用的驱动,但是它不限于这些,还提供了其他存储系统的适配器。通过这些适配器,可以在 Lavarel 应用中创建自定义驱动。

为了配置自定义文件系统,现在把社区维护的 Dropbox 适配器添加到项目中:

  1. composer require spatie/flysystem-dropbox

接下来,创建一个名为 DropboxServiceProvider服务提供器。在它的 boot 方法里,用 Storage 门面的 extend 自定义驱动:

  1. <?php
  2. namespace App\Providers;
  3. use Storage;
  4. use League\Flysystem\Filesystem;
  5. use Illuminate\Support\ServiceProvider;
  6. use Spatie\Dropbox\Client as DropboxClient;
  7. use Spatie\FlysystemDropbox\DropboxAdapter;
  8. class DropboxServiceProvider extends ServiceProvider
  9. {
  10. /**
  11. * 执行注册后引导服务
  12. *
  13. * @return void
  14. */
  15. public function boot()
  16. {
  17. Storage::extend('dropbox', function ($app, $config) {
  18. $client = new DropboxClient(
  19. $config['authorizationToken']
  20. );
  21. return new Filesystem(new DropboxAdapter($client));
  22. });
  23. }
  24. /**
  25. * 在容器中注册绑定
  26. *
  27. * @return void
  28. */
  29. public function register()
  30. {
  31. //
  32. }
  33. }

extend 方法的第一个参数是驱动的名称,第二个参数是个闭包,接受 $app$config 两个变量。这个闭包必须返回 League\Flysystem\Filesystem 的实例。$config 变量包含了指定磁盘在 config/filesystems.php 中的配置。

注册好扩展后, 就可以通过配置 config/filesystems.php 使用dropbox 了。

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。