文件存儲
文件存儲
文件存儲
簡介
Laravel 提供了一個強大的文件系統(tǒng)抽象,這得益于 Frank de Jonge 強大的 Flysystem 擴展包。Laravel 文件系統(tǒng)集成為使用本地文件系統(tǒng)、Amazon S3 和 Rackspace 云存儲提供了簡單易用的驅(qū)動程序。更棒的是,由于每個系統(tǒng)的 API 保持不變,所以在這些存儲選項之間切換是非常簡單的。
配置
文件系統(tǒng)的配置文件位于 config/filesystems.php
。在這個文件中你可以配置所有「磁盤」。每個磁盤代表特定的存儲驅(qū)動及存儲位置。每種支持的驅(qū)動程序的示例配置都包含在配置文件中。因此,只需要修改配置即可反映你的存儲偏好和憑據(jù)。
當(dāng)然,你可以根據(jù)需要配置多個磁盤,甚至你還可以使多個磁盤共用同一個驅(qū)動。
公共磁盤
public
磁盤適用于要公開訪問的文件。默認(rèn)情況下, public
磁盤使用 local
驅(qū)動,并且將這些文件存儲在 storage/app/public
目錄下。為了使它們能通過網(wǎng)絡(luò)訪問,你需要創(chuàng)建 public/storage
到 storage/app/public
的符號鏈接。這種方式能把可公開訪問文件都保留在同一個目錄下,以便在使用零停機時間部署系統(tǒng)如 Envoyer 的時候,就可以輕松地在不同的部署之間共享這些文件。你可以使用 Artisan 命令 storage:link
來創(chuàng)建符號鏈接:
你可以使用 Artisan 命令 storage:link
來創(chuàng)建符號鏈接:
php artisan storage:link
當(dāng)然,一旦一個文件被存儲并且已經(jīng)創(chuàng)建了符號鏈接,你就可以使用輔助函數(shù) asset
來創(chuàng)建文件的 URL:
echo asset('storage/file.txt');
本地驅(qū)動
使用 local
驅(qū)動時,所有文件操作都與你在配置文件中定義的 root
目錄相關(guān)。該目錄的默認(rèn)值是 storage/app
。因此,以下方法會把文件存儲在 storage/app/file.txt
中:
Storage::disk('local')->put('file.txt', 'Contents');
驅(qū)動程序先決條件
Composer 包
在使用 SFTP、S3 或 Rackspace 等驅(qū)動之前,你需要通過 Composer 安裝相應(yīng)的軟件包:
- 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 驅(qū)動配置
S3 驅(qū)動配置信息位于你的 config/filesystems.php
配置文件中。該文件包含 S3 驅(qū)動程序的示例配置數(shù)組。 你可以自由使用你自己的 S3 配置和憑證修改此陣列。 為方便起見,這些環(huán)境變量與 AWS CLI 使用的命名約定相匹配。
FTP 驅(qū)動配置
Laravel 的文件系統(tǒng)集成能很好的支持 FTP,不過 FTP 的配置示例并沒有被包含在框架默認(rèn)的 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 驅(qū)動器的配置
Laravel 的 Flysystem 集成包與 SFTP 協(xié)同得非常好;不過,在該框架的默認(rèn)配置文件 filesystems.php
中并沒有包含示范配置。如果要配置 SFTP 文件系統(tǒng),可以使用如下示例配置:
'sftp' => [ 'driver' => 'sftp', 'host' => 'example.com', 'username' => 'your-username', 'password' => 'your-password', // 基于 SSH 密鑰的身份驗證設(shè)置... // 'privateKey' => '/path/to/privateKey', // 'password' => 'encryption-password', // 可選的 SFTP 配置... // 'port' => 22, // 'root' => '', // 'timeout' => 30, ],
Rackspace 驅(qū)動器配置
Laravel 的 Flysystem 集成包與 Rackspace 協(xié)同得非常好;不過,在該框架的默認(rèn)配置文件 filesystems.php
中并沒有包含示范配置。如果要配置 Rackspace 文件系統(tǒng),可以使用如下示例配置:
'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', ],
緩存
給指定磁盤開啟緩存功能,需要在該磁盤的配置項中直接添加 cache
。 cache
選項應(yīng)該是一個緩存配置的數(shù)組,由緩存驅(qū)動名稱 store
(譯者注:文檔原始描述文字 disk
與示例代碼中的 store
不一致,驗證代碼后的確應(yīng)該是 store
,故作此修改。)、 單位為秒的過期時間 expire
,以及緩存前綴 prefix
組成:
's3' => [ 'driver' => 's3', // 驅(qū)動器其他配置... 'cache' => [ 'store' => 'memcached', 'expire' => 600, 'prefix' => 'cache-prefix', ], ],
獲取磁盤實例
Storage
門面可用于與任何已配置的磁盤進(jìn)行交互。例如,你可以使用門面中的 put
方法將頭像存儲到默認(rèn)磁盤。如果你使用 Storage
門面中的任何方法,而一開始并沒有使用 disk
方法,那么所調(diào)用的方法會自動傳遞給默認(rèn)的磁盤:
use Illuminate\Support\Facades\Storage; Storage::put('avatars/1', $fileContents);
如果應(yīng)用程序要與多個磁盤進(jìn)行互操作,可使用 Storage
門面中的 disk
方法對特定磁盤上的文件進(jìn)行操作:
Storage::disk('s3')->put('avatars/1', $fileContents);
檢索文件
get
方法可以用于檢索文件的內(nèi)容,此方法返回該文件的原始字符串內(nèi)容。 切記,所有文件路徑的指定都應(yīng)該相對于為磁盤配置的「root」目錄:
$contents = Storage::get('file.jpg');
exists
方法可以用來判斷磁盤上是否存在指定的文件:
$exists = Storage::disk('s3')->exists('file.jpg');
下載文件
download
方法可用于生成一個響應(yīng),強制用戶的瀏覽器在給定路徑下載文件。 download
方法接受一個文件名作為該方法的第二個參數(shù),它將確定用戶下載文件時看到的文件名。最后,你可以傳遞一個 HTTP 數(shù)組頭作為該方法的第三個參數(shù):
return response()->download('file.jpg'); return response()->download('file.jpg', $name, $headers);
文件 URLs
你可以使用 url
方法來獲取給定文件的 URL。如果你使用的時 local
驅(qū)動,一般只是在給定的路徑上加上 /storage
并返回一個相對的 URL 到那個文件。如果使用的是 s3
或者是 rackspace
驅(qū)動,會返回完整的遠(yuǎn)程 URL:
use Illuminate\Support\Facades\Storage; $url = Storage::url('file.jpg');
{note} 切記,如果使用的是
local
驅(qū)動,則所有想被公開訪問的文件都應(yīng)該放在storage/app/public
目錄下。此外你應(yīng)該在public/storage
創(chuàng)建一個符號鏈接 來指向storage/app/public
目錄。
臨時 URLs
當(dāng)使用 s3
或 rackspace
驅(qū)動來存儲文件,可以使用 temporaryUrl
方法創(chuàng)建給定文件的臨時 URL。這個方法會接收路徑和 DateTime
實例來指定 URL 何時過期:
$url = Storage::temporaryUrl( 'file.jpg', now()->addMinutes(5) );
自定義本地 URL 主機
如果要使用 local
驅(qū)動為存儲在磁盤上的文件預(yù)定義主機,可以向磁盤配置數(shù)組添加一個 url
選項:
'public' => [ 'driver' => 'local', 'root' => storage_path('app/public'), 'url' => env('APP_URL').'/storage', 'visibility' => 'public', ],
文件元數(shù)據(jù)
除了讀寫文件外,Laravel 還可以提供有關(guān)文件本身的信息,例如,size
方法可用來獲取文件的大?。ㄒ宰止?jié)為單位):
use Illuminate\Support\Facades\Storage; $size = Storage::size('file.jpg');
lastModified
方法返回文件最后一次被修改的 UNIX 時間戳:
$time = Storage::lastModified('file.jpg');
保存文件
put
方法可用于將原始文件內(nèi)容保存到磁盤上。你也可以傳遞 PHP 的 resource
給 put
方法,它將使用文件系統(tǒng)下的底層流支持。強烈建議在處理大文件時使用此方法:
use Illuminate\Support\Facades\Storage; Storage::put('file.jpg', $contents); Storage::put('file.jpg', $resource);
自動流式傳輸
如果你想 Laravel 自動將給定文件流式傳輸?shù)侥愕拇鎯ξ恢茫憧梢允褂?putFile
或 putFileAs
方法。這個方法接收 Illuminate\Http\File
或 Illuminate\Http\UploadedFile
實例,并自動將文件流式傳輸?shù)侥阆胍獋鬏數(shù)奈恢茫?/p>
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');
關(guān)于 putFile
方法,有些點需要注意。我們指定的是一個目錄名而不是文件名。默認(rèn)情況下, putFile
方法會生成一個唯一的 ID 作為文件名。文件的擴展名根據(jù)檢測文件的 MIME 類型來確定。 putFile
方法會返回文件路徑,以便你可以將文件路徑(包括生成的文件名)存儲在數(shù)據(jù)庫中。
putFile
和 putFileAs
方法也接受一個方法來指定存儲文件的 「可見性」。如果你將文件存儲在諸如 S3 的云盤上,并且想讓該文件公開訪問,則可以使用以下功能:
Storage::putFile('photos', new File('/path/to/photo'), 'public');
文件數(shù)據(jù)寫入
prepend
和 append
方法允許你在文件的開頭或結(jié)尾寫入數(shù)據(jù):
Storage::prepend('file.log', 'Prepended Text'); Storage::append('file.log', 'Appended Text');
復(fù)制 & 移動文件
copy
方法用來復(fù)制文件到磁盤上的新位置,而 move
方法用來重命名或移動文件到新位置:
Storage::copy('old/file.jpg', 'new/file.jpg'); Storage::move('old/file.jpg', 'new/file.jpg');
文件上傳
在 web 應(yīng)用程序中,最常用到的文件存儲的場景的地方就是上傳頭像,照片和文件。Laravel 上傳文件的實例方法 store
可以輕松的處理文件上傳存儲問題。你只需要調(diào)用帶有文件保存路徑作為參數(shù)的 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; } }
上例有幾個點需要注意。我們指定的是目錄名,而不是文件名。默認(rèn)情況下, store
方法會自動生成唯一的 ID 作為文件名。文件的擴展名將通過檢查文件的 MIME 類型來確定。該文件的路徑和文件名會被 store
方法返回,以便后續(xù)數(shù)據(jù)庫的存儲使用。
你也可以使用 Storage
facade 上的 putFile
方法達(dá)到和上例同樣的效果:
$path = Storage::putFile('avatars', $request->file('avatar'));
指定文件名
如果你不想將文件名自動分配給存儲的文件,可以使用 storeAs
方法,該方法接受路徑,文件名和 (可選) 磁盤作為其參數(shù):
$path = $request->file('avatar')->storeAs('avatars', $request->user()->id);
你可以使用 Storage
facade 上的 putFileAs
方法達(dá)到和上例同樣的文件操作:
$path = Storage::putFileAs('avatars', $request->file('avatar'), $request->user()->id);
指定磁盤
默認(rèn)情況下, store
方法使用默認(rèn)磁盤。如果你需要指定其他的磁盤,可以傳入磁盤名作為 store
方法的第二個參數(shù):
$path = $request->file('avatar')->store('avatars/'.$request->user()->id, 's3');
文件可見性
在 Laravel 集成的文件系統(tǒng)中,「可見性」是對多個平臺的文件權(quán)限的抽象。文件可以聲明為 public
或 private
。如果一個文件被聲明為 public
,意味著其他人可以訪問。例如,使用 S3 驅(qū)動時,就可以檢索聲明為 public
的文件。
你可以通過 put
方法設(shè)置文件的可見性:
use Illuminate\Support\Facades\Storage; Storage::put('file.jpg', $contents, 'public');
getVisibility
和 setVisibility
方法可以對現(xiàn)存文件的可見性進(jìn)行查詢和設(shè)置:
$visibility = Storage::getVisibility('file.jpg'); Storage::setVisibility('file.jpg', 'public')
刪除文件
delete
方法接收一個文件名或數(shù)組形式的文件名來刪除磁盤上的文件:
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');
目錄
獲取目錄下的所有的文件
files
方法返回指定目錄下的所有文件。如果你想檢索指定目錄(包括子目錄)中所有的文件列表,可以使用 allFiles
方法:
use Illuminate\Support\Facades\Storage; $files = Storage::files($directory); $files = Storage::allFiles($directory);
獲取目錄下的所有目錄
directories
方法返回指定目錄下所有目錄的數(shù)組。此外,你可以使用 allDirectories
方法獲取指定目錄以及其子目錄下所有目錄的列表:
$directories = Storage::directories($directory); // 遞歸... $directories = Storage::allDirectories($directory);
創(chuàng)建目錄
makeDirectory
方法會遞歸創(chuàng)建目錄:
Storage::makeDirectory($directory);
刪除目錄
deleteDirectory
方法會刪除指定目錄及其下所有的文件:
Storage::deleteDirectory($directory);
自定義文件系統(tǒng)
雖然 Laravel 的文件系統(tǒng)提供了一些開箱即用的驅(qū)動,但是它不僅限于這些,還提供了其他文件系統(tǒng)的適配器。通過這些適配器,可以在 Lavarel 應(yīng)用中創(chuàng)建自定義驅(qū)動。
為了設(shè)置自定義文件系統(tǒng),你需要一個 Flysystem 適配器。現(xiàn)在讓我們把社區(qū)維護(hù)的 Dropbox 適配器添加到項目中:
composer require spatie/flysystem-dropbox
接下來,你需要創(chuàng)建一個名為 DropboxServiceProvider
的 服務(wù)提供者 。在它的 boot
方法中,使用 Storage
facade 的 extend
方法自定義驅(qū)動:
<?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{ /** * 執(zhí)行注冊后引導(dǎo)驅(qū)動. * * @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
方法的第一個參數(shù)是驅(qū)動的名稱,第二個參數(shù)是閉包,接受 $app
和 $config
變量。這個閉包必須返回 League\Flysystem\Filesystem
的實例。 $config
變量包含了磁盤在 config/filesystems.php
中的位置。
接下來,在 config/app.php
配置文件中注冊服務(wù)提供者:
'providers' => [ // ... App\Providers\DropboxServiceProvider::class, ];
當(dāng)你創(chuàng)建并注冊好服務(wù)提供者后,就可以通過在 config/filesystems.php
配置文件中添加 dropbox
驅(qū)動并使用它了。