Session · Laravel 5.6 中文文檔

* * * * * [TOC] ## 簡介由于 HTTP 驅動的應用程序是無狀態的，Session 提供了一種在多個請求之間存儲有關用戶的信息的方法。Laravel 通過同一個可讀性強的 API 處理各種自帶的 Session 后臺驅動程序。支持諸如比較熱門的?[Memcached](https://memcached.org/),?[Redis](https://redis.io/)?和數據庫。 ### 配置 Session 的配置文件存儲在?`config/session.php`?文件中。請務必查看此文件中對于你可用的選項。默認情況下，Laravel 配置了適用于大多數應用程序的?`file`?Session 驅動。在生產環境下，你可以考慮使用?`memcached`?或?`redis`?驅動來實現更出色的 Session 性能。 Session?`driver`?的配置選項定義了每個請求存儲 Session 數據的位置。Laravel 自帶了幾個不錯且可開箱即用的驅動： * `file`?- 將 Session 存儲在?`storage/framework/sessions`?中。 * `cookie`?- Session 存儲在安全加密的 cookie 中。 * `database`?- 將 Session 存儲在數據庫中。 * `memcached`?/?`redis`?- Session 存儲在基于高速緩存的存儲系統中。 * `array`?- Sessions 存儲在 PHP 數組中，但不會被持久化。 > {tip} 數組驅動一般用于?[測試](http://www.hmoore.net/tonyyu/laravel_5_6/786281)?，并防止存儲在 Session 中的數據被持久化。 ### 驅動程序先決條件 #### 數據庫使用?`database`?作為 Session 驅動時，你需要創建一張包含 Session 各項數據的表。以下例子是使用?`Schema`?建表： ~~~ Schema::create('sessions', function ($table) { $table->string('id')->unique(); $table->unsignedInteger('user_id')->nullable(); $table->string('ip_address', 45)->nullable(); $table->text('user_agent')->nullable(); $table->text('payload'); $table->integer('last_activity'); }); ~~~ 你可以使用 Artisan 命令?`session：table`?來生成此遷移： ~~~ php artisan session:table php artisan migrate ~~~ #### Redis Laravel 在使用 Redis 作為 Session 驅動之前，需要通過 Composer 安裝?`predis/predis`?擴展包 (~1.0)。然后在?`database`?配置文件中配置 Redis 連接信息。在?`session`?配置文件中，`connection`?選項可用于指定 Session 使用哪個 Redis 連接。 ## 使用 Session ### 獲取數據 Laravel 中處理 Session 數據有兩種主要方法：全局輔助函數?`session`?和通過一個?`Request`?實例。首先，我們來看看通過控制器方法類型提示一個?`Request`?實例來訪問 session。控制器方法依賴項會通過 Laravel?[服務容器](http://www.hmoore.net/tonyyu/laravel_5_6/786056)?實現自動注入: ~~~ <?php namespace App\Http\Controllers; use Illuminate\Http\Request; use App\Http\Controllers\Controller; class UserController extends Controller { /** * 展示給定用戶的配置文件。 * * @param Request $request * @param int $id * @return Response */ public function show(Request $request, $id) { $value = $request->session()->get('key'); // } } ~~~ 當你從 Session 獲取值時，你還可以傳遞一個默認值作為?`get`?方法的第二個參數。如果 Session 中不存在指定的鍵，便會返回這個默認值。若傳遞一個閉包作為?`get`?方法的默認值，并且所請求的鍵并不存在時，`get`?方法將執行閉包并返回其結果： ~~~ $value = $request->session()->get('key', 'default'); $value = $request->session()->get('key', function () { return 'default'; }); ~~~ #### 全局輔助函數 Session 你也可以使用全局的 PHP 輔助函數?`session`?來獲取和存儲的 Session 數據。使用單個字符串類型的值作為參數調用輔助函數?`session`?時，它會返回該字該符串對應的 Session 鍵的值。當使用一個鍵值對數組作為參數調用輔助函數?`session`?時，傳入的鍵值將會存儲在 Session 中： ~~~ Route::get('home', function () { // 獲取 session 中的一條數據... $value = session('key'); // 指定一個默認值... $value = session('key', 'default'); // 在 Session 中存儲一條數據... session(['key' => 'value']); }); ~~~ > {tip} 通過 HTTP 請求實例操作 Session 與使用全局輔助函數?`session`?兩者之間并沒有實質上的區別。這兩種方法都可以通過所有測試用例中可用的?`assertSessionHas`?方法進行?[測試](https://laravel-china.org/docs/laravel/5.6/testing/1409)。 #### 獲取所有的 Session 數據如果你想要獲取所有的 Session 數據，可以使用?`all`?方法： ~~~ $data = $request->session()->all(); ~~~ #### 判斷 Session 中是否存在某個值要確定 Session 中是否存在某個值，可以使用?`has`?方法。如果該值存在且不為?`null`，那么?`has`?方法會返回?`true`： ~~~ if ($request->session()->has('users')) { // } ~~~ 要確定 Session 中是否存在某個值，即使其值為?`null`，也可以使用?`exists`?方法。如果值存在，則?`exists`?方法返回?`true`： ~~~ if ($request->session()->exists('users')) { // } ~~~ ### 存儲數據要存儲數據到 Session，你可以使用?`put`?方法，或者使用輔助函數?`session`。 ~~~ // 通過請求實例... $request->session()->put('key', 'value'); // 通過全局輔助函數... session(['key' => 'value']); ~~~ #### 在 Session 數組中保存數據 `push`?方法可以將一個新的值添加到 Session 數組內。例如，假設?`user.teams`?這個鍵是包含團隊名稱的數組，你可以像這樣將一個新的值加入到此數組中： ~~~ $request->session()->push('user.teams', 'developers'); ~~~ #### 檢索 & 刪除一個項目 `pull`?方法可以只用一條語句就從 Session 中檢索并且刪除一個項目： ~~~ $value = $request->session()->pull('key', 'default'); ~~~ ### 閃存數據有時候你僅想在下一個請求之前在 Session 中存入數據，你可以使用?`flash`?方法。使用這個方法保存在 Session 中的數據，只會保留到下個 HTTP 請求到來之前，然后就會被刪除。閃存數據主要用于短期的狀態消息： ~~~ $request->session()->flash('status', 'Task was successful!'); ~~~ 如果需要給更多請求保留閃存數據，可以使用?`reflash`?方法，這將會所有的閃存數據保留給其它請求。如果只想保留特定的閃存數據，則可以使用?`keep`?方法： ~~~ $request->session()->reflash(); $request->session()->keep(['username', 'email']); ~~~ ### 刪除數據 `forget`?方法可以從 Session 內刪除一條數據。如果你想刪除 Session 內所有數據，可以使用?`flush`?方法： ~~~ $request->session()->forget('key'); $request->session()->flush(); ~~~ ### 重新生成 Session ID 重新生成 Session ID，通常是為了防止惡意用戶利用?[session fixation](https://en.wikipedia.org/wiki/Session_fixation)?對應用進行攻擊。如果使用了內置函數?`LoginController`，Laravel 會自動重新生成身份驗證中的 Session ID。否則，你需要手動使用?`regenerate`?方法重新生成 Session ID。 ~~~ $request->session()->regenerate(); ~~~ ## 添加自定義 Session 驅動 #### 實現驅動你自定義的 Session 驅動必須實現?`SessionHandlerInterface`?接口。這個接口包含了一些我們需要實現的簡單方法。下面是一個大概的 MongoDB 實現流程示例： ~~~ <?php namespace App\Extensions; class MongoSessionHandler implements \SessionHandlerInterface { public function open($savePath, $sessionName) {} public function close() {} public function read($sessionId) {} public function write($sessionId, $data) {} public function destroy($sessionId) {} public function gc($lifetime) {} } ~~~ > {tip} Laravel 默認沒有附帶擴展用的目錄，你可以把它放在你喜歡的目錄內。在下面這個例子中，我們創建了一個?`Extensions`?目錄放置自定義的?`MongoHandler`?擴展。接口中的這些方法不太容易理解。讓我們來快速了解每個方法的作用： * open 方法通常用于基于文件的 Session 存儲系統。因為 Laravel 已經附帶了一個?`file`?的驅動，所以你不需要在該方法中放置任何代碼。PHP 要求必需要有這個方法的實現（這只是一個糟糕的接口設計），你只需要把這個方法置空。 * `close`?方法跟?`open`?方法很相似，通常也可以被忽略。對大多數的驅動而言，此方法不是必須的。 * `read`?方法應當返回與給定的?`$sessionId`?相匹配的 Session 數據的字符串格式。在你的自定義的驅動中獲取或存儲 Session 數據時，不需要進行任何序列化或其它編碼，因為 Laravel 會執行序列化。 * `write`?將與?`$sessionId`?關聯的給定的?`$data`?字符串寫入到一些持久化存儲系統，如 MongoDB、Dynamo 等。再次重申，你不需要進行任何序列化或其它編碼，因為 Laravel 會自動處理這些事情。 * `destroy`?方法會從持久化存儲中移除與?`$sessionId`?相關聯的數據 * `gc`?方法能銷毀給定的?`$lifetime`?（UNIX 的時間戳）之前的所有數據。對本身擁有過期機制的系統如 Memcached 和 Redis 而言，該方法可以置空。 #### 注冊驅動你的 Session 驅動實現之后，你還需要在框架中注冊該驅動，即將該擴展驅動添加到 Laravel Session 后臺。然后在?[服務提供者](http://www.hmoore.net/tonyyu/laravel_5_6/786058)?的?`boot`?方法內調用?`Session`?Facade 的?`extend`?方法。之后你就可以從現有的?`AppServiceProvider`或者新創建的提供器中執行此操作。 ~~~ <?php namespace App\Providers; use App\Extensions\MongoSessionHandler; use Illuminate\Support\Facades\Session; use Illuminate\Support\ServiceProvider; class SessionServiceProvider extends ServiceProvider { /** * 執行注冊后引導服務。 * * @return void */ public function boot() { Session::extend('mongo', function ($app) { // Return implementation of SessionHandlerInterface... return new MongoSessionHandler; }); } /** * 在容器中注冊綁定。 * * @return void */ public function register() { // } } ~~~ 一旦 Session 驅動被注冊，則必須在?`config/session.php`?的配置文件內使用?`Mongo`?驅動。