文件存儲 · 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>