文件存储 · laravel 5.4

<article><h1>Laravel 的文件系统和云存储功能集成</h1><ul><li><a href="#introduction">简介</a></li><li><a href="#configuration">配置</a><ul><li><a href="#the-public-disk">公开磁盘</a></li><li><a href="#the-local-driver">本地驱动</a></li><li><a href="#driver-prerequisites">驱动的前置条件</a></li></ul></li><li><a href="#obtaining-disk-instances">获取磁盘实例</a></li><li><a href="#retrieving-files">提取文件</a><ul><li><a href="#file-urls">文件 URLs</a></li><li><a href="#file-metadata">文件元数据</a></li></ul></li><li><a href="#storing-files">保存文件</a><ul><li><a href="#file-uploads">文件上传</a></li><li><a href="#file-visibility">文件可见性</a></li></ul></li><li><a href="#deleting-files">删除文件</a></li><li><a href="#directories">目录</a></li><li><a href="#custom-filesystems">自定义文件系统</a></li></ul><a name="introduction"></a><h2><a href="#introduction">简介</a></h2>Laravel 提供强大文件抽象能力，这得益于 Frank de Jonge 的 <a href="https://github.com/thephpleague/flysystem">Flysystem</a> 扩展包。Laravel 集成的 flysystem 提供了可支持本地文件系统、Amazon S3及 Rackspace 云存储的简单易用的驱动程序。更棒的是，由于每个系统的API保持不变，所以在这些存储项之间切换是非常轻松的。<a name="configuration"></a><h2><a href="#configuration">配置</a></h2>文件系统配置文件位于 <code class=" language-php">config/filesystems.php</code>。该文件能让你设置所有的「磁盘（disk）」。每个磁盘代表一个特定的存储驱动及存储位置。各种支持驱动的配置示例已包含其中，仅需要简单的根据你的偏好配置及凭证设置进行修改即可。当然，你可随意配置多组磁盘，即使多个磁盘使用相同的驱动。<a name="the-public-disk"></a><h3>公开磁盘</h3>「公开磁盘」就是指你的文件将可被公开访问，默认下， <code class=" language-php">public</code> 磁盘使用 <code class=" language-php">local</code> 驱动且将文件存放在 <code class=" language-php">storage/app/public</code> 目录下。为了能通过网络访问，你需要创建 <code class=" language-php">public/storage</code> 到 <code class=" language-php">storage/app/public</code> 的符号链接。这个约定能让你的可公开访问文件保持在同一个目录下，这样在不同的部署系统间就可以轻松共享，如 <a href="https://envoyer.io">Envoyer</a> 的“不停服”部署系统。你可以使用 <code class=" language-php">storage:link</code> Artisan 命令创建符号链接：<pre class=" language-php"><code class=" language-php">php artisan storage:link</code></pre>当然了，当文件放好且符号链接创建完毕后，你就可以用 <code class=" language-php">asset</code> 辅助函数创建 URL 了：<pre class=" language-php"><code class=" language-php">echo asset('storage/file.txt');</code></pre><a name="the-local-driver"></a><h3>本地驱动</h3>当使用 <code class=" language-php">local</code> 驱动时，所有的操作都是相对于你在配置文件中定义的 <code class=" language-php">root</code> 目录进行的。该目录默认是 <code class=" language-php">storage/app</code>。所以，下面方法会把文件保存在 <code class=" language-php">storage/app/file.txt</code>：<pre class=" language-php"><code class=" language-php">Storage::disk('local')->put('file.txt', 'Contents');</code></pre><a name="driver-prerequisites"></a><h3>驱动的预先需求</h3><h4>Composer 包</h4>在使用 S3 或 Rackspace 驱动之前，你需要通过 Composer 安装适当扩展包：<ul><li>Amazon S3: <code class=" language-php">league/flysystem-aws-s3-v3 ~1.0</code></li><li>Rackspace: <code class=" language-php">league/flysystem-rackspace ~1.0</code></li></ul><h4>S3 驱动配置</h4>S3 驱动配置信息位于 <code class=" language-php">config/filesystems.php</code> 配置文件中。此文件有个关于S3 驱动的配置数组例子。你可根据自己的 S3 配置和凭证修改该数组。<h4>FTP 驱动配置</h4>Laravel 集成的 Flysystem 能很好的支持 FTP，不过 FTP 的配置示例没被包含在框架默认的 <code class=" language-php">filesystems.php</code> 文件中，需要的话照着下面的例子配置：<pre class=" language-php"><code class=" language-php">'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, ],</code></pre><h4>Rackspace 驱动配置</h4>Laravel 集成的 Flysystem 能很好的支持 Rackspace，不过 Rackspace 的配置示例没被包含在框架默认的 <code class=" language-php">filesystems.php</code> 文件中，需要的话照着下面的例子配置：<pre class=" language-php"><code class=" language-php">'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', ],</code></pre><a name="obtaining-disk-instances"></a><h2><a href="#obtaining-disk-instances">获得磁盘实例</a></h2><code class=" language-php">Storage</code> facade 用于和所有已设置的磁盘交互。例如，你可以调 facade 的 <code class=" language-php">put</code> 方法将一张头像保存到默认磁盘上。调 <code class=" language-php">Storage</code> facade 的方法前若未先调用 <code class=" language-php">disk</code> 方法，此方法会被自动传递给默认磁盘。<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; Storage::put('avatars/1', $fileContents);</code></pre>要是你的应用和多个磁盘交互，你可以通过 <code class=" language-php">Storage</code> facade 的 <code class=" language-php">disk</code> 方法访问特定的磁盘：<pre class=" language-php"><code class=" language-php">Storage::disk('s3')->put('avatars/1', $fileContents);</code></pre><a name="retrieving-files"></a><h2><a href="#retrieving-files">提取文件</a></h2><code class=" language-php">get</code> 方法被用作提取文件内容，此方法返回该文件的原始字符串内容。切记，所有文件路径都是基于配置文件中 <code class=" language-php">root</code> 目录的相对路径。<pre class=" language-php"><code class=" language-php">$contents = Storage::get('file.jpg');</code></pre><code class=" language-php">exists</code> 方法可以被用于判断一个文件是否存在于磁盘：<pre class=" language-php"><code class=" language-php">$exists = Storage::disk('s3')->exists('file.jpg');</code></pre><a name="file-urls"></a><h3>文件 URLs</h3>当使用 <code class=" language-php">local</code> 或者 <code class=" language-php">s3</code> 驱动的时候，你可以使用 <code class=" language-php">url</code> 方法来获取给定文件的 URL。如果你使用 <code class=" language-php">local</code> 驱动，一般会在传参的路径前面加上 <code class=" language-php">/storage</code> 且返回相对路径。如果是 <code class=" language-php">s3</code> 的话，返回的是完整的 S3 文件系统的 URL：<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; $url = Storage::url('file1.jpg');</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 切记，如果使用 <code class=" language-php">local</code> 驱动，所有想被公开访问的文件都应该放在 <code class=" language-php">storage/app/public</code> 目录下。此外，你应该在<code class=" language-php">public/storage</code> [创建符号链接 ] (#the-public-disk) 来指向 <code class=" language-php">storage/app/public</code> 文件夹。</blockquote><h4>定制本地 URL 主机</h4>如果你想给使用 <code class=" language-php">local</code> 驱动的存储文件预定义主机的话，你可以在磁盘配置数组中添加 <code class=" language-php">url</code> 键：<pre class=" language-php"><code class=" language-php">'public' => [ 'driver' => 'local', 'root' => storage_path('app/public'), 'url' => env('APP_URL').'/storage', 'visibility' => 'public', ],</code></pre><a name="file-metadata"></a><h3>文件元数据</h3>除了读写文件，Laravel 还可以提供有关文件本身的信息。例如，<code class=" language-php">size</code> 方法可用来获取以字节为单位的文件大小：<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; $size = Storage::size('file1.jpg');</code></pre><code class=" language-php">lastModified</code> 方法返回的最后一次文件被修改的 UNIX 时间戳：<pre class=" language-php"><code class=" language-php">$time = Storage::lastModified('file1.jpg');</code></pre><a name="storing-files"></a><h2><a href="#storing-files">保存文件</a></h2><code class=" language-php">put</code> 方法用于保存文件原始内容到一个磁盘上。你也可以传递 PHP 的 <code class=" language-php">resource</code> 给 <code class=" language-php">put</code> 方法，它将使用 Flysystem 下的 stream 支持。强烈建议使用 streams 处理大型文件：<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; Storage::put('file.jpg', $contents); Storage::put('file.jpg', $resource);</code></pre><h4>自动流</h4>如果您想 Laravel 自动管理指定文件流传输到您想要的存储位置，你可以使用 <code class=" language-php">putFile</code> 或 <code class=" language-php">putFileAs</code> 方法。这个方法可以接受一个 <code class=" language-php">Illuminate\HTTP\File</code> 或 <code class=" language-php">Illuminate\HTTP\UploadedFile</code> 实例，并自动将文件传输到你想要的位置：<pre class=" language-php"><code class=" language-php">use Illuminate\Http\File; // 自动生成唯一文件名... Storage::putFile('photos', new File('/path/to/photo')); // 手动指定一个文件名... Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');</code></pre>关于 <code class=" language-php">putFile</code> 方法有些重要的提醒。我们只指定一个目录名，而非文件名。默认情况下，该 <code class=" language-php">putFile</code> 方法将生成以为唯一ID作为文件名。文件的路径将被 <code class=" language-php">putFile</code> 方法返回，因此您可以在数据库中存储路径及文件名。<code class=" language-php">putFile</code> 和 <code class=" language-php">putFileAs</code> 方法也接受一个参数指定被存储文件的「可见性」。在使用如 S3 的云存储时，若希望该文件可被公开访问，这将非常有用：<pre class=" language-php"><code class=" language-php">Storage::putFile('photos', new File('/path/to/photo'), 'public');</code></pre><h4>插入到文件</h4><code class=" language-php">prepend</code> 及 <code class=" language-php">append</code> 方法允许你将内容写入到一个文件的开头或结尾：<pre class=" language-php"><code class=" language-php">Storage::prepend('file.log', 'Prepended Text'); Storage::append('file.log', 'Appended Text');</code></pre><h4>复制 & 移动文件</h4><code class=" language-php">copy</code> 方法用于复制一个已存在的文件到磁盘的新位置。<code class=" language-php">move</code> 方法用于重命名或是移动一个已存在的文件到新位置：<pre class=" language-php"><code class=" language-php">Storage::copy('old/file1.jpg', 'new/file1.jpg'); Storage::move('old/file1.jpg', 'new/file1.jpg');</code></pre><a name="file-uploads"></a><h3>文件上传</h3>在 Web 应用中，存储文件最常见的例子之一就是存储用户上传的文件，如个人资料图片，照片和文档。 Laravel 通过使用文件上传实例的 <code class=" language-php">store</code> 方法，使其可以非常容易的存储上传的文件。只需使用你想存储的路径来调用 <code class=" language-php">store</code> 方法即可：<pre class=" language-php"><code class=" language-php"><?php 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; } }</code></pre>关于此例有些注意事项。我们只指定一个目录名，而不是文件名。默认情况下，<code class=" language-php">store</code> 方法将生成唯一ID来作为文件名。此文件路径将被 <code class=" language-php">store</code> 方法返回，因此你可以在数据库中存储路径及文件名。你也可以调用<code class=" language-php">Storage</code> facade 的 <code class=" language-php">putFile</code> 方法来执行和上面例子相同的文件操作：<pre class=" language-php"><code class=" language-php">$path = Storage::putFile('avatars', $request->file('avatar'));</code></pre><h4>指定文件名</h4>如果你不喜欢自动生成的文件名，你可以使用 <code class=" language-php">storeAs</code> 方法，它接收的路径、文件名、磁盘（可选的）作为它的参数：<pre class=" language-php"><code class=" language-php">$path = $request->file('avatar')->storeAs( 'avatars', $request->user()->id );</code></pre>当然，你也可以使用 <code class=" language-php">Storage</code> facade 的 <code class=" language-php">putFileAs</code> 方法，可以和上面例子的文件操作有相同效果：<pre class=" language-php"><code class=" language-php">$path = Storage::putFileAs( 'avatars', $request->file('avatar'), $request->user()->id );</code></pre><h4>指定磁盘</h4>默认情况下，此方法将使用默认的磁盘。如果你想指定其他磁盘，给<code class=" language-php">store</code> 方法的第二个参数传磁盘名：<pre class=" language-php"><code class=" language-php">$path = $request->file('avatar')->store( 'avatars/'.$request->user()->id, 's3' );</code></pre><a name="file-visibility"></a><h3>文件可见性</h3>在 Laravel 的 Flysystem 集成里，「可见性」是跨多平台的文件权限抽象。文件可以被设定为 <code class=" language-php">public</code> 或 <code class=" language-php">private</code> 。当一个文件声明为 <code class=" language-php">public</code> 时，就意味着文件一般可供他人访问。例如，使用S3驱动时，你可检索 <code class=" language-php">public</code> 文件的URL。你可通过 <code class=" language-php">put</code> 方法设定文件可见性：<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; Storage::put('file.jpg', $contents, 'public');</code></pre>如果文件已经被保存，其可见性可以通过 <code class=" language-php">getVisibility</code> 来获取和 <code class=" language-php">setVisibility</code> 方法来设置。<pre class=" language-php"><code class=" language-php">$visibility = Storage::getVisibility('file.jpg'); Storage::setVisibility('file.jpg', 'public')</code></pre><a name="deleting-files"></a><h2><a href="#deleting-files">删除文件</a></h2><code class=" language-php">delete</code> 方法接受一个文件名称或文件数组，用于从磁盘移除文件：<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; Storage::delete('file.jpg'); Storage::delete(['file1.jpg', 'file2.jpg']);</code></pre><a name="directories"></a><h2><a href="#directories">目录</a></h2><h4>获取某目录内的所有文件</h4><code class=" language-php">files</code> 方法返回指定目录下的所有文件数组。如果你还想获取指定目录下子目录的文件，可以使用 <code class=" language-php">allFiles</code> 方法。<pre class=" language-php"><code class=" language-php">use Illuminate\Support\Facades\Storage; $files = Storage::files($directory); $files = Storage::allFiles($directory);</code></pre><h4>获取单个目录内所有目录</h4><code class=" language-php">directories</code> 方法返回指定目录下的目录数组。另外，你也可以使用 <code class=" language-php">allDirectories</code> 方法获取指定目录下的子目录以及子目录所包含的目录。<pre class=" language-php"><code class=" language-php">$directories = Storage::directories($directory); // 递归... $directories = Storage::allDirectories($directory);</code></pre><h4>创建目录</h4><code class=" language-php">makeDirectory</code> 方法将创建指定的目录，包括任何所需的子目录。<pre class=" language-php"><code class=" language-php">Storage::makeDirectory($directory);</code></pre><h4>删除目录</h4>最后，<code class=" language-php">deleteDirectory</code> 方法删除目录及所包含的全部文件。<pre class=" language-php"><code class=" language-php">Storage::deleteDirectory($directory);</code></pre><a name="custom-filesystems"></a><h2><a href="#custom-filesystems">自定义文件系统</a></h2>Laravel 的 Flysystem 集成提供一系列开箱即用的驱动支持；然而 Flysystem 不仅限于此，还拥有其它存储系统适配器。如果在你的 Laravel 的应用中想使用额外的存储适配器，你可以创建自定义驱动。为了建构一个自定义的文件系统，你需要创建一个如 <code class=" language-php">DropboxServiceProvider</code> 的 <a href="/docs/5.4/providers">服务提供者</a>。并在该提供者的 <code class=" language-php">boot</code> 方法使用 <code class=" language-php">Storage</code> facade 的 <code class=" language-php">extend</code> 方法自定义你的驱动。<pre class=" language-php"><code class=" language-php"><?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 { /** * 运行服务注册后的启动进程。 * * @return void */ public function boot() { Storage::extend('dropbox', function($app, $config) { $client = new DropboxClient( $config['accessToken'], $config['clientIdentifier'] ); return new Filesystem(new DropboxAdapter($client)); }); } /** * 在容器注册绑定。 * * @return void */ public function register() { // } }</code></pre><code class=" language-php">extend</code> 方法的第一个参数是驱动名，第二个参数则是一个接受 <code class=" language-php">$app</code> 及 <code class=" language-php">$config</code> 变量的闭包。该闭包必须返回 <code class=" language-php">League\Flysystem\Filesystem</code> 的实例。<code class=" language-php">$config</code> 变量包含了在 <code class=" language-php">config/filesystems.php</code> 定义的特定磁盘配置。一旦通过创建服务提供者注册此扩展后，你就可以在 <code class=" language-php">config/filesystem.php</code> 配置文件中使用 <code class=" language-php">dropbox</code> 驱动。<h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="https://github.com/zuoRambo">@Rambone</a></td><td><img class="avatar-66 rm-style" src="http://tva1.sinaimg.cn/crop.0.0.1002.1002.180/92d03bcdjw8f0asasf3m1j20ru0rvaeo.jpg"></td><td>译者</td><td>php,go求职简历请发zuoxiaojie@lianjia.com</td></tr></tbody></table></article>