文件存儲 · laravel 5.5 中文文檔

# 文件存儲 - [簡介](#introduction) - [配置](#configuration) - [公共磁盤](#the-public-disk) - [本地驅動](#the-local-driver) - [驅動之前](#driver-prerequisites) - [獲取磁盤實例](#obtaining-disk-instances) - [檢索文件](#retrieving-files) - [文件 URLs](#file-urls) - [文件元數據](#file-metadata) - [保存文件](#storing-files) - [文件上傳](#file-uploads) - [文件可見性](#file-visibility) - [刪除文件](#deleting-files) - [目錄](#directories) - [自定義文件系統](#custom-filesystems) <a name="introduction"></a> ## 簡介 Laravel 提供了一個強大的文件系統抽象，這得益于 Frank de Jonge 強大的 [Flysystem](https://github.com/thephpleague/flysystem) 擴展包。Laravel 文件系統集成為使用本地文件系統、Amazon S3 和 Rackspace 云存儲提供了簡單易用的驅動程序。更棒的是，由于每個系統的 API 保持不變，所以在這些存儲選項之間切換是非常簡單的。 <a name="configuration"></a> ## 配置文件系統的配置文件位于 `config/filesystems.php`。在這個文件中你可以配置所有「磁盤」。每個磁盤代表特定的存儲驅動及存儲位置。每種支持的驅動程序的示例配置都包含在配置文件中。因此，只需要修改配置即可反映你的存儲偏好和憑據。當然，你可以根據需要配置多個磁盤，甚至你還可以使多個磁盤共用同一個驅動。 <a name="the-public-disk"></a> ### 公共磁盤 `public` 磁盤適用于要公開訪問的文件。默認情況下， `public` 磁盤使用 `local` 驅動，并且將這些文件存儲在 `storage/app/public` 目錄下。為了使它們能通過網絡訪問，你需要創建 `public/storage` 到 `storage/app/public` 的符號鏈接。這種方式能把可公開訪問文件都保留在同一個目錄下，以便在使用零停機時間部署系統如[Envoyer](https://envoyer.io/) 的時候，就可以輕松地在不同的部署之間共享這些文件。你可以使用 Artisan 命令 `storage:link` 來創建符號鏈接： php artisan storage:link 當然，一旦一個文件被存儲并且已經創建了符號鏈接，你就可以使用輔助函數 `asset` 來創建文件的 URL： echo asset('storage/file.txt'); <a name="the-local-driver"></a> ### 本地驅動使用 `local` 驅動時，所有文件操作都你在配置文件中定義的 `root` 目錄相關。該目錄的默認值是 `storage/app`。因此，以下方法會把文件存儲在 `storage/app/file.txt` 中： Storage::disk('local')->put('file.txt', 'Contents'); <a name="driver-prerequisites"></a> ### 驅動之前 #### 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 驅動程序的配置數組示例。你可根據自己的 S3 配置和憑證自由修改該數組。 #### FTP 驅動配置 Laravel 的文件系統集成能很好的支持 FTP，不過 FTP 的配置示例并沒有被包含在框架默認的 `filesystems.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, ], #### Rackspace 驅動配置 Laravel 的文件系統集成也能很好的支持 Rackspace，不過 Rackspace 的配置示例也沒被包含在框架默認的 `filesystems.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', ], <a name="obtaining-disk-instances"></a> ## 獲取磁盤實例 `Storage` facade 用于和所有已配置的磁盤進行交互。例如，你可以使用 facade 的 `put` 方法將頭像保存到默認磁盤上。調 `Storage` facade 的方法前若未先調用 `disk` 方法，此方法會被自動傳遞給默認磁盤。如果沒有先調用 `disk` 方法就調用了 `Storage` facade 上的方法，那調用的方法會自動被傳遞到默認磁盤： use Illuminate\Support\Facades\Storage; Storage::put('avatars/1', $fileContents); 如果應用程序和多個磁盤交互，則可以使用 `Storage` facade 上的 `disk` 方法來處理特定磁盤上的文件： Storage::disk('s3')->put('avatars/1', $fileContents); <a name="retrieving-files"></a> ## 檢索文件 `get` 方法可以用于檢索文件的內容，此方法返回該文件的原始字符串內容。切記，所有文件路徑的指定都應該相對于為磁盤配置的 `root` 目錄： $contents = Storage::get('file.jpg'); `exists` 方法可以用來判斷磁盤上是否存在指定的文件： $exists = Storage::disk('s3')->exists('file.jpg'); <a name="file-urls"></a> ### 文件 URLs 當使用 `local` 或者 `s3` 驅動時，你可以使用 `url` 方法來獲取給定文件的 URL。如果你使用的是 `local` 驅動，一般只是在給定的路徑前面加上 `/storage` 并返回一個相對的 URL 到那個文件。如果使用的是 `s3` 驅動，會返回完整的遠程 URL： use Illuminate\Support\Facades\Storage; $url = Storage::url('file1.jpg'); > {note} 切記，如果使用的是 `local` 驅動，則所有想被公開訪問的文件都應該放在 `storage/app/public` 目錄下。此外，你應該在 `public/storage` [創建一個符號鏈接 ](#the-public-disk) 來指向 `storage/app/public` 目錄。 #### 臨時 URLs 對于使用 `s3` 驅動來存儲的文件，可以使用 `temporaryUrl` 方法創建給定文件的臨時 URL 。這個方法接收路徑和 `DateTime` 實例來指定 URL 何時過期： $url = Storage::temporaryUrl( 'file1.jpg', Carbon::now()->addMinutes(5) ); #### 自定義本地 URL 主機如果要使用 `local` 驅動為存儲在磁盤上的文件預定義主機，可以向磁盤配置數組添加一個 `url` 選項： 'public' => [ 'driver' => 'local', 'root' => storage_path('app/public'), 'url' => env('APP_URL').'/storage', 'visibility' => 'public', ], <a name="file-metadata"></a> ### 文件元數據除了讀寫文件，Laravel 還可以提供有關文件本身的信息。例如，`size` 方法可用來獲取文件的大小（以字節為單位）： use Illuminate\Support\Facades\Storage; $size = Storage::size('file1.jpg'); `lastModified` 方法返回最后一次文件被修改的 UNIX 時間戳： $time = Storage::lastModified('file1.jpg'); <a name="storing-files"></a> ## 保存文件 `put` 方法可用于將原始文件內容保存到磁盤上。你也可以傳遞 PHP 的 `resource` 給 put 方法，它將使用文件系統下的底層流支持。強烈建議在處理大文件時使用流： use Illuminate\Support\Facades\Storage; Storage::put('file.jpg', $contents); Storage::put('file.jpg', $resource); #### 自動流式傳輸如果你想 Laravel 自動管理將給定文件流式傳輸到你想要的存儲位置，你可以使用 `putFile` 或 `putFileAs` 方法。這個方法接受 `Illuminate\HTTP\File` 或 `Illuminate\HTTP\UploadedFile` 實例，并自動將文件流式傳輸到你想要的位置： use Illuminate\Http\File; // 自動為文件名生成唯一的 ID... Storage::putFile('photos', new File('/path/to/photo')); // 手動指定文件名... Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg'); 關于 `putFile` 方法有些重要的事情要注意。請注意，我們只指定一個目錄名，而不是文件名。默認情況下，`putFile` 方法將生成唯一的 ID 作為文件名。該文件的路徑將被 `putFile` 方法返回，因此可以將路徑（包括生成的文件名）存儲在數據庫中。 `putFile` 和 `putFileAs` 方法也接受一個參數來指定存儲文件的「可見性」。如果你將文件存儲在諸如 S3 的云盤上，并且該文件可以公開訪問，這是特別有用的： Storage::putFile('photos', new File('/path/to/photo'), 'public'); #### 前置&追加 `prepend` 及 `append` 方法允許你寫入內容到文件的開頭或結尾： 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'); <a name="file-uploads"></a> ### 文件上傳在 Web 應用中，存儲文件最常見的例子之一就是存儲用戶上傳的文件，如個人資料圖片、照片和文檔。 Laravel 可以使用文件上傳實例的 `store` 方法來存儲上傳的文件。只需使用你想存儲上傳文件的路徑調用 `store` 方法： <?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; } } 關于這個例有些注意事項。我們只指定目錄名，而不是文件名。默認情況下，`store` 方法將生成唯一的 ID 來作為文件名。該文件的路徑將被 `store` 方法返回，因此你可以在數據庫中存儲路徑及生成的文件名。你也可以調用 `Storage` facade 的 `putFile` 方法來執行和上面例子相同的文件操作： $path = Storage::putFile('avatars', $request->file('avatar')); #### 指定文件名如果你不喜歡自動生成的文件名，你可以使用 `storeAs` 方法，它接收的路徑、文件名、磁盤（可選的）作為它的參數： $path = $request->file('avatar')->storeAs( 'avatars', $request->user()->id ); 當然，你也可以使用 `Storage` facade 的 `putFileAs` 方法，和上面例子的文件操作有相同效果： $path = Storage::putFileAs( 'avatars', $request->file('avatar'), $request->user()->id ); #### 指定磁盤默認情況下，此方法將使用默認的磁盤。如果你想指定其他磁盤，就將磁盤名稱作為第二個參數傳遞給 `store` 方法： $path = $request->file('avatar')->store( 'avatars/'.$request->user()->id, 's3' ); <a name="file-visibility"></a> ### 文件可見性在 Laravel 的文件系統集成里，「可見性」是跨多個平臺的文件權限的抽象。文件可能被聲明為 `public` 或 `private` 。當一個文件聲明為 `public` 時，就意味著文件通常可以被其他人訪問。例如，使用 S3 驅動時，你可檢索 `public` 文件的 URL。你可通過 `put` 方法在設置文件時指定它的可見性： use Illuminate\Support\Facades\Storage; Storage::put('file.jpg', $contents, 'public'); 如果文件已經被保存，可以通過 `getVisibility` 和 `setVisibility` 方法檢索和設置其可見性。 $visibility = Storage::getVisibility('file.jpg'); Storage::setVisibility('file.jpg', 'public') <a name="deleting-files"></a> ## 刪除文件 `delete` 方法接受文件名或文件名數組參數來刪除磁盤中相應的文件： use Illuminate\Support\Facades\Storage; Storage::delete('file.jpg'); Storage::delete(['file1.jpg', 'file2.jpg']); <a name="directories"></a> ## 目錄 #### 獲取目錄中的所有文件 `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); <a name="custom-filesystems"></a> ## 自定義文件系統 Laravel 的文件系統集成提供一系列開箱即用的驅動支持；然而文件系統不僅限于此，它還擁有其它存儲系統的適配器。如果你想在 Laravel 的應用中使用額外的存儲適配器，可以創建自定義驅動。為了設置自定義文件系統，你需要一個文件系統適配器。讓我們添加一個社區維護的 Dropbox 適配器到我們的項目中： composer require spatie/flysystem-dropbox 接下來，你需要創建一個[服務提供器](/docs/{{version}}/providers)，如 DropboxServiceProvider。并在該提供器的 `boot` 方法使用 `Storage` facade 的 `extend` 方法自定義你的驅動程序。 <?php namespace App\Providers; use Storage; use League\Flysystem\Filesystem; use Spatie\Dropbox\Client as DropboxClient; use Illuminate\Support\ServiceProvider; use Spatie\FlysystemDropbox\DropboxAdapter; class DropboxServiceProvider extends ServiceProvider { /** * 執行注冊后引導服務。 * * @return void */ public function boot() { Storage::extend('dropbox', function ($app, $config) { $client = new DropboxClient( $config['authorizationToken'] ); return new Filesystem(new DropboxAdapter($client)); }); } /** * 在容器中注冊綁定。 * * @return void */ public function register() { // } } `extend` 方法的第一個參數是驅動程序的名稱，第二個參數是接收 `$app` 及 `$config` 變量的閉包。該解析閉包必須返回 `League\Flysystem\Filesystem` 的實例。`$config` 變量包含了特定磁盤在 `config/filesystems.php` 中定義的值。一旦通過創建服務提供器注冊擴展名后，你就可以在 `config/filesystem.php` 配置文件中使用 `dropbox` 驅動程序。 ## 譯者署名 | 用戶名 | 頭像 | 職能 | 簽名 | | --- | --- | --- | --- | | [@Godruoyi](https://segmentfault.com/blog/godruoyi) | <img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/5359_1470894290.jpeg?imageView2/1/w/200/h/200"> | 翻譯 | 聽大悲咒敲代碼的二楞徐 | | [@Rambone](https://github.com/zuoRambo) | <img class="avatar-66 rm-style" src="http://tva1.sinaimg.cn/crop.0.0.1002.1002.180/92d03bcdjw8f0asasf3m1j20ru0rvaeo.jpg"> | 翻譯 | php,go求職簡歷請發zuoxiaojie@lianjia.com | --- > {note} 歡迎任何形式的轉載，但請務必注明出處，尊重他人勞動共創開源社區。 > > 轉載請注明：本文檔由 Laravel China 社區 [laravel-china.org](https://laravel-china.org) 組織翻譯，詳見 [翻譯召集帖](https://laravel-china.org/topics/5756/laravel-55-document-translation-call-come-and-join-the-translation)。 > > 文檔永久地址： https://d.laravel-china.org