文件系统与云存储

简介

Laravel 强大的文件抽象层得力于 Frank de Jonge 的 Flysystem 扩展包。Laravel 的 flysystem 集成提供了可给本地端磁盘系统、Amazon S3、以及 Rackspace 云存储使用的各种驱动(driver)。并且能像使用 API 一样,轻易的切换这些存储方式来应对各式系统。

设置

文件系统配置文件位于 config/filesystems.php。该文件能让你设置所有的「磁盘(disk)」。每个磁盘代表一个唯一的存储驱动以及存储位置。各种支持驱动的例子已包含其中,仅需要简单的根据你的偏好配置及凭证设置进行修改即可。

当然,你也可以设置多组磁盘,甚至在多个磁盘使用相同的驱动。

公开磁盘

公开磁盘意味着你的所有文件将可以公开访问,默认的 public 磁盘使用 local 驱动,并且存储文件至 storage/app/public 文件夹中。为了能公开访问,你需要创建 public/storage 文件夹,然后作为符号链接到 storage/app/public 文件夹。这个约定能使你在使用 Envoyer 类似的部署器的时候保证文件夹配置的统一。

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

  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 安装适当扩展包:

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

S3 驱动配置

S3 驱动配置信息存储在 config/filesystems.php 配置文件里。 这个文件有S3 驱动的配置数组的例子。你可以随意编辑

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. ],

Rackspace 驱动配置

Laravel 强大的文件系统能很好的支持 Rackspace,不过 Rackspace 的配置信息并没有被包含在 filesystems.php 文件中,你可以使用以下样本代码进行配置:

  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. ],

获得磁盘实例

Storage facade 用于对任何已设置的磁盘进行交互。举例来说,你可以使用 facade 的 put 方法将一张头像保存到默认磁盘上。当使用 Storage facade 调用了方法却未先调用 disk 方法时,默认磁盘将被自动传递给该方法。

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

当使用多个磁盘时,你可以通过 Storage facade 的 disk 方法访问指定磁盘。当然,你也可以使用链式调用(chain methods)对磁盘使用各种执行方法。

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

文件 URLs

当使用 local 或者 s3 驱动的时候,你可以使用 url 方法来获取文件的 URL。如果你使用 local 驱动,一般会在传参的路径前面加上 /storage。如果是 s3 的话,会返回完整的 S3 文件系统的 URL:

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

{note} 当使用 local 驱动的时候,请确定 创建符号链接到 public/storage 来指向 storage/app/public 文件夹。

文件元数据

除了读取和写入文件,Laravel还可以提供有关文件本身的信息。例如,size 方法可被用于获得以字节的文件的大小:

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

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

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

保存文件

put 方法保存单个文件于磁盘上。你能同时传递 PHP 的 resourceput 方法,它将使用文件系统底层的 stream 支持。强烈建议使用 stream 处理大型文件:

  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. // Automatically calculate MD5 hash for file name...
  3. Storage::putFile('photos', new File('/path/to/photo'));
  4. // 手动指定一个文件名...
  5. Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

还有要注意的有关 putFile 方法的一些重要的事情。请注意,我们只指定一个目录名,而不是文件名。默认情况下,该 putFile 方法将自动基于该文件的内容而生成。这是通过的文件内容的 MD5 哈希来完成的。该文件的路径将被 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/file1.jpg', 'new/file1.jpg');
  2. Storage::move('old/file1.jpg', 'new/file1.jpg');

文件上传

在 Web 应用程序中,最常见的例子之一就是存储文件是存储用户上传的文件,如个人资料图片,照片和文档。 Laravel 通过使用 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. * 上传 avatar 给用户.
  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 方法将基于文件的内容自动生成文件名。这是通过获取该文件内容的 MD5 散列来实现的。该文件的路径将被 store 方法被退回,因此您可以在数据库中存储路径和包括生成的文件名。

您也可以调用在Storage facade putFile 方法来执行和上面例子相同的文件操作:

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

{note} 如果您要上传非常大的文件,你不妨手动指定文件名。计算大的文件文件的MD5哈希需要占用大量内存。

指定文件名

如果你不喜欢的文件名被自动分配给您的存储的文件,你可以使用 storeAs 方法,它接收的路径,文件名。选择的磁盘作为它的参数:

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

当然,你也可以在 putFileAs 方法里使用 Storage ,将执行上面的例子中相同的文件操作:

  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整合,“可见性”是多平台上的文件权限的抽象层。你也可以选择在使用 put 创建文件时设置可见性,可见性的值为 public 或者是 private 。当一个文件为 public ,要表示文件一般应给他人使用。例如,使用S3驱动程序时,您可以检索 public 文件的URL。

使用 put 在创建文件时设置可见性:

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

如果文件已经被保存,那么可见性可以通过 getVisibility 来获取和 setVisibility 方法来设置。

  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(['file1.jpg', 'file2.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 集成的 Flysystem 提供许多默认驱动;然而 Flysystem 本身不仅仅提供了这些,还包括其它保存系统的接口(adapter)。你能在 Laravel 的应用当中通过创建新的驱动使用这些额外的接口。

为了建构一个自定义的磁盘系统,你将需要创建一个像是 DropboxServiceProvider服务提供者。并在该提供者的 boot 方法使用 Storage facade 的 extend 方法自定义你的驱动。

  1. <?php
  2. namespace App\Providers;
  3. use Storage;
  4. use League\Flysystem\Filesystem;
  5. use Dropbox\Client as DropboxClient;
  6. use Illuminate\Support\ServiceProvider;
  7. use League\Flysystem\Dropbox\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['accessToken'], $config['clientIdentifier']
  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/filesystem.php 配置文件中使用 dropbox 驱动。

译者署名

用户名 头像 职能 签名
@LXY 文件存储 - 图1 翻译 PHP 小学生。

{note} 欢迎任何形式的转载,但请务必注明出处,尊重他人劳动共创开源社区。

转载请注明:本文档由 Laravel China 社区 [laravel-china.org] 组织翻译,详见 翻译召集帖

文档永久地址: http://d.laravel-china.org