[ Laravel 5.3 文档 ] 综合话题 —— 文件存储

1、简介

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

2、配置

文件系统配置文件位于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包

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

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

S3驱动配置

S3驱动配置信息位于配置文件 config/filesystems.php ,该文件包含S3驱动的示例配置数组。你可以使用自己的S3配置和认证信息自由编辑该数组。

FTP驱动配置

Laravel的文件系统集成了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,
],

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

3、获取硬盘实例

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

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

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

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

4、获取文件

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

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

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

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

文件URL

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

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

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

文件元信息

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

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

lastModified方法以UNIX时间戳格式返回文件最后一次修改时间:

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

5、存储文件

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

use Illuminate\Support\Facades\Storage;

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

自动文件流

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

use Illuminate\Http\File;

// Automatically calculate MD5 hash for file name...
Storage::putFile('photos', new File('/path/to/photo'));

// Manually specify a file name...
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

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

putFileputFileAs方法还接收一个用于指定存储文件“能见度”的参数,这在你将文件存储到云存储(如S3)平台并期望文件可以被公开访问时很有用:

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

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

prependappend方法允许你轻松插入内容到文件开头/结尾:

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
{
    /**
     * Update the avatar for the user.
     *
     * @param  Request  $request
     * @return Response
     */
    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'));

注:如果你接收的上传文件尺寸很大,你可能需要手动指定文件名,因为计算大文件的MD5哈希值很耗内存。

指定文件名

如果你不想要自动生成文件名,可以使用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集成中,“能见度”是对不同平台上文件权限的抽象,文件可以被声明成publicprivate,当文件被声明为public,意味着文件可以被其他人访问。例如,使用S3时,可以获取public文件的URL。

使用put方法设置文件的时候可以顺便设置能见度:

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

如果文件已经被存储,能见度可以通过getVisibilitysetVisibility方法获取和设置:

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

6、删除文件

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

use Illuminate\Support\Facades\Storage;

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

7、目录

获取一个目录下的所有文件

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

8、自定义文件系统

Laravel 的Flysystem集成支持自定义驱动,为了设置自定义的文件系统,你需要创建一个服务提供者DropboxServiceProvider。在该提供者的boot方法中,你可以使用Storage门面的extend方法定义自定义驱动:

<?php

namespace App\Providers;

use Storage;
use League\Flysystem\Filesystem;
use Dropbox\Client as DropboxClient;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Dropbox\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['accessToken'], $config['clientIdentifier']
            );

            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驱动了。

学院君

学院君 has written 548 articles

资深PHP工程师,Laravel学院院长