文件存儲 · laravel 5.3 中文文檔

# 文件系統與云存儲 - [簡介](#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 的 flysystem 集成提供了可給本地端磁盤系統、Amazon S3、以及 Rackspace 云存儲使用的各種驅動（driver）。并且能像使用 API 一樣，輕易的切換這些存儲方式來應對各式系統。 <a name="configuration"></a> ## 設置文件系統配置文件位于 `config/filesystems.php`。該文件能讓你設置所有的「磁盤（disk）」。每個磁盤代表一個唯一的存儲驅動以及存儲位置。各種支持驅動的例子已包含其中，僅需要簡單的根據你的偏好配置及憑證設置進行修改即可。當然，你也可以設置多組磁盤，甚至在多個磁盤使用相同的驅動。 <a name="the-public-disk"></a> ### 公開磁盤公開磁盤意味著你的所有文件將可以公開訪問，默認的 `public` 磁盤使用 `local` 驅動，并且存儲文件至 `storage/app/public` 文件夾中。為了能公開訪問，你需要創建 `public/storage` 文件夾，然后作為符號鏈接到 `storage/app/public` 文件夾。這個約定能使你在使用 [Envoyer](https://envoyer.io) 類似的部署器的時候保證文件夾配置的統一。你就可以使用 `storage:link` Artisan 命令創建符號鏈接: 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 驅動的配置數組的例子。你可以隨意編輯 #### 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` 方法時，默認磁盤將被自動傳遞給該方法。 use Illuminate\Support\Facades\Storage; Storage::put('avatars/1', $fileContents); 當使用多個磁盤時，你可以通過 `Storage` facade 的 `disk` 方法訪問指定磁盤。當然，你也可以使用鏈式調用（chain methods）對磁盤使用各種執行方法。 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`。如果是 `s3` 的話，會返回完整的 S3 文件系統的 URL: use Illuminate\Support\Facades\Storage; $url = Storage::url('file1.jpg'); > {note} 當使用 `local` 驅動的時候，請確定 [創建符號鏈接到 `public/storage`](#the-public-disk) 來指向 `storage/app/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` 方法，它將使用文件系統底層的 stream 支持。強烈建議使用 stream 處理大型文件： 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; // Automatically calculate MD5 hash for file name... Storage::putFile('photos', new File('/path/to/photo')); // 手動指定一個文件名... Storage::putFile('photos', new File('/path/to/photo'), 'photo.jpg'); 還有要注意的有關 `putFile` 方法的一些重要的事情。請注意，我們只指定一個目錄名，而不是文件名。默認情況下，該 `putFile` 方法將自動基于該文件的內容而生成。這是通過的文件內容的 MD5 哈希來完成的。該文件的路徑將被 `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 { /** * 上傳 avatar 給用戶. * * @param Request $request * @return Response */ public function update(Request $request) { $path = $request->file('avatar')->store('avatars'); return $path; } } 需要注意這個例子中一些重要的事情。我們只指定一個目錄名，而不是文件名。默認情況下，`store`方法將自動生成基于自動基于該文件的內容而生成。這是通過的文件內容的MD5哈希來完成的。該文件的路徑將被 `store` 方法被退回，因此您可以在數據庫中存儲路徑和包括生成的文件名。您也可以調用在`Storage` facade `putFile` 方法來執行和上面例子相同的文件操作： $path = Storage::putFile('avatars', $request->file('avatar')); > {note} 如果您要上傳非常大的文件，你不妨手動指定文件名。計算大的文件文件的MD5哈希需要占用大量內存。 #### 指定文件名如果你不喜歡的文件名被自動分配給您的存儲的文件，你可以使用 `storeAs` 方法，它接收的路徑，文件名。選擇的磁盤作為它的參數： $path = $request->file('avatar')->storeAs( 'avatars', $request->user()->id ); 當然，你也可以在 `putFileAs` 方法里使用 `Storage` ，將執行上面的例子中相同的文件操作： $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的Flysystem整合，“可見性”是多平臺上的文件權限的抽象層。你也可以選擇在使用 `put` 創建文件時設置可見性，可見性的值為 `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 集成的 Flysystem 提供許多默認驅動；然而 Flysystem 本身不僅僅提供了這些，還包括其它保存系統的接口（adapter）。你能在 Laravel 的應用當中通過創建新的驅動使用這些額外的接口。為了建構一個自定義的磁盤系統，你將需要創建一個像是 `DropboxServiceProvider` 的 [服務提供者](/docs/{{version}}/providers)。并在該提供者的 `boot` 方法使用 `Storage` facade 的 `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 { /** * 運行服務注冊后的啟動進程。 * * @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() { // } } `extend` 方法的第一個參數是你的驅動名稱，第二個參數則是一個接受 `$app` 及 `$config` 變量的閉包。該閉包必須返回 `League\Flysystem\Filesystem` 實例。`$config` 變量包含了定義在 `config/filesystems.php` 對指定磁盤的設置。當你通過創建服務提供者注冊該擴展后，你便能在 `config/filesystem.php` 配置文件中使用 `dropbox` 驅動。 ## 譯者署名 | 用戶名 | 頭像 | 職能 | 簽名 | |---|---|---|---| | [@LXY](https://github.com/dongli0) | <img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/5832_1473813539.jpeg?imageView2/1/w/380/h/380"> | 翻譯 | PHP 小學生。 |