Appearance
HTTP 会话
简介
由于 HTTP 驱动的应用程序是无状态的,会话提供了一种在多个请求之间存储用户信息的方法。这些用户信息通常放置在可以从后续请求中访问的持久存储/后端中。
Laravel 附带了各种会话后端,可通过富有表现力的统一 API 访问。支持流行的后端,如 Memcached、Redis 和数据库。
配置
你的应用程序的会话配置文件存储在 config/session.php
中。请务必查看此文件中可用的选项。默认情况下,Laravel 配置为使用 database
会话驱动程序。
会话 driver
配置选项定义了每个请求的会话数据将存储在何处。Laravel 包含了多种驱动程序:
file
- 会话存储在storage/framework/sessions
中。cookie
- 会话存储在安全的加密 cookie 中。database
- 会话存储在关系数据库中。memcached
/redis
- 会话存储在这些快速的基于缓存的存储中。dynamodb
- 会话存储在 AWS DynamoDB 中。array
- 会话存储在 PHP 数组中,不会被持久化。
NOTE
数组驱动程序主要用于 测试,它可以防止存储在会话中的数据被持久化。
驱动程序先决条件
数据库
使用 database
会话驱动程序时,你需要确保有一个数据库表来存储会话数据。通常,这包含在 Laravel 的默认 0001_01_01_000000_create_users_table.php
数据库迁移 中;但是,如果由于某种原因你没有 sessions
表,可以使用 make:session-table
Artisan 命令生成此迁移:
shell
php artisan make:session-table
php artisan migrate
Redis
在 Laravel 中使用 Redis 会话之前,你需要通过 PECL 安装 PhpRedis PHP 扩展或通过 Composer 安装 predis/predis
包(~1.0)。有关配置 Redis 的更多信息,请参阅 Laravel 的 Redis 文档。
NOTE
SESSION_CONNECTION
环境变量或 session.php
配置文件中的 connection
选项可用于指定用于会话存储的 Redis 连接。
与会话交互
获取数据
在 Laravel 中处理会话数据有两种主要方式:全局 session
助手和通过 Request
实例。首先,让我们看看如何通过 Request
实例访问会话,该实例可以在路由闭包或控制器方法中进行类型提示。记住,控制器方法依赖项是通过 Laravel 服务容器 自动注入的:
php
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\View\View;
class UserController extends Controller
{
/**
* Show the profile for the given user.
*/
public function show(Request $request, string $id): View
{
$value = $request->session()->get('key');
// ...
$user = $this->users->find($id);
return view('user.profile', ['user' => $user]);
}
}
当从会话中检索项目时,还可以将默认值作为 get
方法的第二个参数传递。如果指定的键不存在于会话中,将返回此默认值。如果将闭包作为 get
方法的默认值传递,并且请求的键不存在,将执行该闭包并返回其结果:
php
$value = $request->session()->get('key', 'default');
$value = $request->session()->get('key', function () {
return 'default';
});
全局会话助手
你还可以使用全局 session
PHP 函数来检索和存储会话中的数据。当使用单个字符串参数调用 session
助手时,它将返回该会话键的值。当使用键/值对数组调用 session
助手时,这些值将存储在会话中:
php
Route::get('/home', function () {
// Retrieve a piece of data from the session...
$value = session('key');
// Specifying a default value...
$value = session('key', 'default');
// Store a piece of data in the session...
session(['key' => 'value']);
});
NOTE
使用 HTTP 请求实例访问会话与使用全局 session
助手的实际差异很小。这两种方法都可以通过所有测试用例中的 assertSessionHas
方法进行测试。
获取所有会话数据
如果要检索会话中的所有数据,可以使用 all
方法:
php
$data = $request->session()->all();
获取会话数据的一部分
only
和 except
方法可用于检索会话数据的子集:
php
$data = $request->session()->only(['username', 'email']);
$data = $request->session()->except(['username', 'email']);
确定会话中是否存在项目
要确定项目是否存在于会话中,可以使用 has
方法。如果项目存在且不为 null
,has
方法将返回 true
:
php
if ($request->session()->has('users')) {
// ...
}
要确定项目是否存在于会话中,即使其值为 null
,也可以使用 exists
方法:
php
if ($request->session()->exists('users')) {
// ...
}
要确定项目是否不存在于会话中,可以使用 missing
方法。如果项目不存在,missing
方法将返回 true
:
php
if ($request->session()->missing('users')) {
// ...
}
存储数据
要在会话中存储数据,通常会使用请求实例的 put
方法或全局 session
助手:
php
// Via a request instance...
$request->session()->put('key', 'value');
// Via the global "session" helper...
session(['key' => 'value']);
将值推送到数组会话值
push
方法可用于将新值推送到会话值为数组的情况下。例如,如果 user.teams
键包含一个团队名称数组,可以像这样将新值推送到该数组中:
php
$request->session()->push('user.teams', 'developers');
检索并删除项目
pull
方法可以在单个语句中检索并删除会话中的项目:
php
$value = $request->session()->pull('key', 'default');
增加和减少会话值
如果会话数据包含你希望增加或减少的整数,可以使用 increment
和 decrement
方法:
php
$request->session()->increment('count');
$request->session()->increment('count', $incrementBy = 2);
$request->session()->decrement('count');
$request->session()->decrement('count', $decrementBy = 2);
闪存数据
有时,你可能希望将项目存储在会话中,以便在下一个请求中使用。你可以使用 flash
方法来实现这一点。使用此方法存储在会话中的数据将立即可用,并在随后的 HTTP 请求中可用。在随后的 HTTP 请求之后,闪存数据将被删除。闪存数据主要用于短期状态消息:
php
$request->session()->flash('status', 'Task was successful!');
如果需要在几个请求中持久化闪存数据,可以使用 reflash
方法,它将保留所有闪存数据,以便再进行一次请求。如果只需要保留特定的闪存数据,可以使用 keep
方法:
php
$request->session()->reflash();
$request->session()->keep(['username', 'email']);
要仅在当前请求中持久化闪存数据,可以使用 now
方法:
php
$request->session()->now('status', 'Task was successful!');
删除数据
forget
方法将从会话中删除一条数据。如果要从会话中删除所有数据,可以使用 flush
方法:
php
// Forget a single key...
$request->session()->forget('name');
// Forget multiple keys...
$request->session()->forget(['name', 'status']);
$request->session()->flush();
重新生成会话 ID
重新生成会话 ID 通常是为了防止恶意用户利用应用程序上的 会话固定 攻击。
如果你使用的是 Laravel 的任何一个 应用程序启动器包 或 Laravel Fortify,Laravel 会在身份验证期间自动重新生成会话 ID;但是,如果需要手动重新生成会话 ID,可以使用 regenerate
方法:
php
$request->session()->regenerate();
如果需要在单个语句中重新生成会话 ID 并从会话中删除所有数据,可以使用 invalidate
方法:
php
$request->session()->invalidate();
会话阻塞
WARNING
要利用会话阻塞,你的应用程序必须使用支持 原子锁 的缓存驱动程序。目前,这些缓存驱动程序包括 memcached
、dynamodb
、redis
、database
、file
和 array
驱动程序。此外,你不能使用 cookie
会话驱动程序。
默认情况下,Laravel 允许使用相同会话的请求并发执行。因此,例如,如果你使用 JavaScript HTTP 库向应用程序发出两个 HTTP 请求,它们将同时执行。对于大多数应用程序来说,这不是问题;但是,在一小部分应用程序中,会发生会话数据丢失,这些应用程序会向两个不同的应用程序端点发出并发请求,这两个端点都会向会话写入数据。
为了缓解这种情况,Laravel 提供了功能,允许你限制给定会话的并发请求。要开始使用,只需在路由定义上链接 block
方法即可。在此示例中,对 /profile
端点的传入请求将获取会话锁。在持有此锁的同时,对 /profile
或 /order
端点的任何传入请求(共享相同会话 ID)都将等待第一个请求完成执行后再继续执行:
php
Route::post('/profile', function () {
// ...
})->block($lockSeconds = 10, $waitSeconds = 10)
Route::post('/order', function () {
// ...
})->block($lockSeconds = 10, $waitSeconds = 10)
block
方法接受两个可选参数。block
方法接受的第一个参数是会话锁应持有的最长秒数。当然,如果请求在此时间之前完成执行,锁将更早释放。
block
方法接受的第二个参数是请求在尝试获取会话锁时应等待的秒数。如果请求在给定的秒数内无法获取会话锁,将抛出 Illuminate\Contracts\Cache\LockTimeoutException
。
如果未传递这两个参数,锁将最多持有 10 秒,请求将最多等待 10 秒以获取锁:
php
Route::post('/profile', function () {
// ...
})->block()
添加自定义会话驱动程序
实现驱动程序
如果现有的会话驱动程序都不符合你的应用程序的需求,Laravel 使你可以编写自己的会话处理程序。你的自定义会话驱动程序应该实现 PHP 的内置 SessionHandlerInterface
。此接口只包含几个简单的方法。MongoDB 存根实现如下所示:
php
<?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) {}
}
NOTE
Laravel 不随附包含扩展的目录。你可以将它们放置在任何你喜欢的位置。在此示例中,我们创建了一个 Extensions
目录来存放 MongoSessionHandler
。
由于这些方法的目的不是很明显,让我们快速介绍一下每个方法的作用:
open
方法通常用于基于文件的会话存储系统。由于 Laravel 附带了file
会话驱动程序,你通常不需要在此方法中放置任何内容。你可以直接将此方法留空。close
方法,与open
方法一样,通常可以忽略。对于大多数驱动程序,它是不需要的。read
方法应返回与给定$sessionId
关联的会话数据的字符串版本。在检索或存储会话数据时,无需执行任何序列化或其他编码,因为 Laravel 会为你执行序列化。write
方法应将给定的$data
字符串与$sessionId
一起写入持久存储系统,例如 MongoDB 或你选择的其他存储系统。同样,你不需要执行任何序列化 - Laravel 已经为你处理了。destroy
方法应从持久存储中删除与$sessionId
关联的数据。gc
方法应销毁所有早于给定的$lifetime
(UNIX 时间戳)的会话数据。对于自动过期的系统,如 Memcached 和 Redis,此方法可以留空。
注册驱动程序
一旦实现了驱动程序,就可以将其注册到 Laravel 中。要向 Laravel 的会话后端添加其他驱动程序,可以使用 Session
facade 提供的 extend
方法。你应该在服务提供程序的 boot
方法中调用 extend
方法。你可以在现有的 App\Providers\AppServiceProvider
中执行此操作,也可以创建一个全新的提供程序:
php
<?php
namespace App\Providers;
use App\Extensions\MongoSessionHandler;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Session;
use Illuminate\Support\ServiceProvider;
class SessionServiceProvider extends ServiceProvider
{
/**
* Register any application services.
*/
public function register(): void
{
// ...
}
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Session::extend('mongo', function (Application $app) {
// Return an implementation of SessionHandlerInterface...
return new MongoSessionHandler;
});
}
}
一旦注册了会话驱动程序,就可以使用 SESSION_DRIVER
环境变量或应用程序的 config/session.php
配置文件指定 mongo
驱动程序作为应用程序的会话驱动程序。