文件存儲 · Laravel5.8筆記

# 文件存儲 - [簡介](#introduction) - [配置](#configuration) - [公共磁盤](#the-public-disk) - [本地驅動](#the-local-driver) - [驅動先決條件](#driver-prerequisites) - [緩存](#caching) - [獲取磁盤實例](#obtaining-disk-instances) - [檢索文件](#retrieving-files) - [下載文件](#downloading-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` 來創建符號鏈接：你可以使用 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 包在使用 SFTP、S3 或 Rackspace 等驅動之前，你需要通過 Composer 安裝相應的軟件包： - SFTP: `league/flysystem-sftp ~1.0` - Amazon S3: `league/flysystem-aws-s3-v3 ~1.0` - Rackspace: `league/flysystem-rackspace ~1.0` 使用緩存適配器是提高性能的一個絕對必要條件。你需要一個額外的包： - CachedAdapter: `league/flysystem-cached-adapter ~1.0` #### S3 驅動配置 S3 驅動配置信息位于你的 `config/filesystems.php` 配置文件中。該文件包含 S3 驅動程序的示例配置數組。你可以自由使用你自己的 S3配置和憑證修改此陣列。為方便起見，這些環境變量與 AWS CLI 使用的命名約定相匹配。 #### FTP 驅動配置 Laravel 的文件系統集成能很好的支持 FTP，不過 FTP 的配置示例并沒有被包含在框架默認的 `filesystems.php` 文件中。需要的話可以使用下面的示例配置： 'ftp' => [ 'driver' => 'ftp', 'host' => 'ftp.example.com', 'username' => 'your-username', 'password' => 'your-password', // 可選的 FTP 配置項... // 'port' => 21, // 'root' => '', // 'passive' => true, // 'ssl' => true, // 'timeout' => 30, ], #### SFTP 驅動器的配置 Laravel 的 Flysystem 集成包與 SFTP 協同得非常好；不過，在該框架的默認配置文件 `filesystems.php` 中并沒有包含示范配置。如果要配置 SFTP 文件系統，可以使用如下示例配置： 'sftp' => [ 'driver' => 'sftp', 'host' => 'example.com', 'username' => 'your-username', 'password' => 'your-password', // 基于 SSH 密鑰的身份驗證設置... // 'privateKey' => '/path/to/privateKey', // 'password' => 'encryption-password', // 可選的 SFTP 配置... // 'port' => 22, // 'root' => '', // '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', ], <a name="caching"></a> ### 緩存給指定磁盤開啟緩存功能，需要在該磁盤的配置項中直接添加 `cache` 。 `cache` 選項應該是一個緩存配置的數組，由緩存驅動名稱 `store` （譯者注：文檔原始描述文字 `disk` 與示例代碼中的 `store` 不一致，驗證代碼后的確應該是 `store` ，故作此修改。）、單位為秒的過期時間 `expire` ，以及緩存前綴 `prefix` 組成： 's3' => [ 'driver' => 's3', // 驅動器其他配置... 'cache' => [ 'store' => 'memcached', 'expire' => 600, 'prefix' => 'cache-prefix', ], ], <a name="obtaining-disk-instances"></a> ## 獲取磁盤實例 `Storage` 門面可用于與任何已配置的磁盤進行交互。例如，你可以使用門面中的 `put` 方法將頭像存儲到默認磁盤。如果你使用 `Storage` 門面中的任何方法，而一開始并沒有使用 `disk` 方法，那么所調用的方法會自動傳遞給默認的磁盤： use Illuminate\Support\Facades\Storage; Storage::put('avatars/1', $fileContents); 如果應用程序要與多個磁盤進行互操作，可使用 `Storage` 門面中的 `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="downloading-files"></a> ### 下載文件 `download` 方法可用于生成一個響應，強制用戶的瀏覽器在給定路徑下載文件。 `download` 方法接受一個文件名作為該方法的第二個參數，它將確定用戶下載文件時看到的文件名。最后，你可以傳遞一個 HTTP 數組頭作為該方法的第三個參數： return response()->download('file.jpg'); return response()->download('file.jpg', $name, $headers); <a name="file-urls"></a> ### 文件 URLs 你可以使用 `url` 方法來獲取給定文件的 URL。如果你使用的是 `local` 驅動，一般只是在給定的路徑上加上 `/storage` 并返回一個相對的 URL 到那個文件。如果使用的是 `s3` 或者是 `rackspace` 驅動，會返回完整的遠程 URL： use Illuminate\Support\Facades\Storage; $url = Storage::url('file.jpg'); > {note} 切記，如果使用的是 `local` 驅動，則所有想被公開訪問的文件都應該放在 `storage/app/public` 目錄下。此外你應該在 `public/storage` [創建一個符號鏈接](#the-public-disk) 來指向 `storage/app/public` 目錄。 #### 臨時 URLs 當使用 `s3` 或 `rackspace` 驅動來存儲文件，可以使用 `temporaryUrl` 方法創建給定文件的臨時 URL。這個方法會接收路徑和 `DateTime` 實例來指定 URL 何時過期： $url = Storage::temporaryUrl( 'file.jpg', 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('file.jpg'); `lastModified` 方法返回文件最后一次被修改的 UNIX 時間戳： $time = Storage::lastModified('file.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; use Illuminate\Support\Facades\Storage; // 自動為文件名生成唯一的ID... Storage::putFile('photos', new File('/path/to/photo')); // 手動指定文件名... Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg'); 關于 `putFile` 方法，有些點需要注意。我們指定的是一個目錄名而不是文件名。默認情況下， `putFile` 方法會生成一個唯一的 ID 作為文件名。文件的擴展名根據檢測文件的 MIME 類型來確定。 `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/file.jpg', 'new/file.jpg'); Storage::move('old/file.jpg', 'new/file.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作為文件名。文件的擴展名將通過檢查文件的 MIME 類型來確定。該文件的路徑和文件名會被 `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` 方法使用默認磁盤。如果你需要指定其他的磁盤，可以傳入磁盤名作為 `store` 方法的第二個參數： $path = $request->file('avatar')->store( 'avatars/'.$request->user()->id, 's3' ); <a name="file-visibility"></a> ### 文件可見性在 Laravel 集成的文件系統中，「可見性」是對多個平臺的文件權限的抽象。文件可以聲明為 `public` 或 `private`。如果一個文件被聲明為 `public`，意味著其他人可以訪問。例如，使用 S3 驅動時，就可以檢索聲明為 `public` 的文件。你可以通過 `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(['file.jpg', 'file2.jpg']); 必要的話，可以指定磁盤名來刪除其下的文件： use Illuminate\Support\Facades\Storage; Storage::disk('s3')->delete('folder_path/file_name.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 的文件系統提供了一些開箱即用的驅動，但是它不僅限于這些，還提供了其他文件系統的適配器。通過這些適配器，可以在 Lavarel 應用中創建自定義驅動。為了設置自定義文件系統，你需要一個Flysystem 適配器。現在讓我們把社區維護的 Dropbox 適配器添加到項目中： composer require spatie/flysystem-dropbox 接下來，你需要創建一個名為 `DropboxServiceProvider` 的 [服務提供者](/docs/{{version}}/providers) 。在它的 `boot` 方法中，使用 `Storage` facade 的 `extend` 方法自定義驅動： <?php namespace App\Providers; use Storage; use League\Flysystem\Filesystem; use Illuminate\Support\ServiceProvider; use Spatie\Dropbox\Client as DropboxClient; use Spatie\FlysystemDropbox\DropboxAdapter; class DropboxServiceProvider extends ServiceProvider { /** * 執行注冊后引導驅動. * * @return void */ public function boot() { Storage::extend('dropbox', function ($app, $config) { $client = new DropboxClient( $config['authorization_token'] ); return new Filesystem(new DropboxAdapter($client)); }); } /** * 在容器中注冊綁定. * * @return void */ public function register() { // } } `extend` 方法的第一個參數是驅動的名稱，第二個參數是閉包，接受 `$app` 和 `$config` 變量。這個閉包必須返回 `League\Flysystem\Filesystem` 的實例。 `$config` 變量包含了磁盤在 `config/filesystems.php` 中的位置。接下來，在`config/app.php` 配置文件中注冊服務提供者： 'providers' => [ // ... App\Providers\DropboxServiceProvider::class, ]; 當你創建并注冊好服務提供者后，就可以通過在 `config/filesystems.php` 配置文件中添加 `dropbox` 驅動并使用它了。