HTTP Session

简介

由于 HTTP 驱动的应用是无状态的，session 提供了一种在多次请求之间存储用户信息的方式。这些用户信息通常存放在可被后续请求访问的持久化存储 / 后端中。

Laravel 内置多种 session 后端，并通过富有表现力的统一 API 访问。已包含对 Memcached、Redis 和数据库等常见后端的支持。

配置

应用的 session 配置文件位于 config/session.php。请务必查看该文件中可用的选项。默认情况下，Laravel 配置为使用 database session 驱动。

session 的 driver 配置选项定义了每次请求时 session 数据的存储位置。Laravel 包含多种驱动：

file - session 存储在 storage/framework/sessions。
cookie - session 存储在安全的加密 cookie 中。
database - session 存储在关系型数据库中。
memcached / redis - session 存储在这些基于缓存的高速存储中。
dynamodb - session 存储在 AWS DynamoDB 中。
array - session 存储在 PHP 数组中，不会持久化。

INFO

array 驱动主要用于测试，并防止 session 中存储的数据被持久化。

驱动前提条件

数据库

使用 database session 驱动时，需要确保有一张数据库表来存放 session 数据。通常这已包含在 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 session 之前，需要通过 PECL 安装 PhpRedis PHP 扩展，或通过 Composer 安装 predis/predis 包。有关配置 Redis 的更多信息，请参阅 Laravel 的 Redis 文档。

INFO

可使用 SESSION_CONNECTION 环境变量，或 session.php 配置文件中的 connection 选项，指定用于 session 存储的 Redis 连接。

与 Session 交互

检索数据

在 Laravel 中处理 session 数据主要有两种方式：全局 session 辅助函数，以及通过 Request 实例。首先来看通过 Request 实例访问 session，可在路由闭包或控制器方法上类型提示。请记住，控制器方法的依赖会通过 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]);
    }
}

从 session 检索条目时，也可将默认值作为 get 方法的第二个参数传入。若指定键不存在于 session 中，将返回该默认值。若将闭包作为默认值传入 get，且请求的键不存在，则会执行该闭包并返回其结果：

php

$value = $request->session()->get('key', 'default');

$value = $request->session()->get('key', function () {
    return 'default';
});

全局 Session 辅助函数

也可使用全局 session PHP 函数来检索和存储 session 数据。当以单个字符串参数调用 session 辅助函数时，会返回该 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']);
});

INFO

通过 HTTP 请求实例使用 session，与使用全局 session 辅助函数，在实际使用上几乎没有区别。两种方式都可通过所有测试用例中可用的 assertSessionHas 方法进行测试。

检索全部 Session 数据

若希望检索 session 中的全部数据，可使用 all 方法：

php

$data = $request->session()->all();

检索部分 Session 数据

only 与 except 方法可用于检索 session 数据的子集：

php

$data = $request->session()->only(['username', 'email']);

$data = $request->session()->except(['username', 'email']);

判断条目是否存在于 Session

要判断条目是否存在于 session 中，可使用 has 方法。若条目存在且不为 null，has 返回 true：

php

if ($request->session()->has('users')) {
    // ...
}

要判断条目是否存在于 session 中（即使值为 null），可使用 exists 方法：

php

if ($request->session()->exists('users')) {
    // ...
}

要判断条目是否不存在于 session 中，可使用 missing 方法。若不存在，missing 返回 true：

php

if ($request->session()->missing('users')) {
    // ...
}

存储数据

要在 session 中存储数据，通常使用请求实例的 put 方法或全局 session 辅助函数：

php

// Via a request instance...
$request->session()->put('key', 'value');

// Via the global "session" helper...
session(['key' => 'value']);

向数组型 Session 值追加

push 方法可用于向作为数组的 session 值追加新值。例如，若 user.teams 键包含团队名称数组，可像这样向数组追加新值：

php

$request->session()->push('user.teams', 'developers');

检索并删除条目

pull 方法可在一条语句中从 session 检索并删除条目：

php

$value = $request->session()->pull('key', 'default');

递增与递减 Session 值

若 session 数据中包含希望递增或递减的整数，可使用 increment 与 decrement 方法：

php

$request->session()->increment('count');

$request->session()->increment('count', $incrementBy = 2);

$request->session()->decrement('count');

$request->session()->decrement('count', $decrementBy = 2);

闪存数据

有时你希望将条目存入 session 供下一次请求使用。可使用 flash 方法。通过此方法存入 session 的数据会立即可用，并在随后的 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 方法会从 session 中移除一条数据。若希望移除 session 中的全部数据，可使用 flush 方法：

php

// Forget a single key...
$request->session()->forget('name');

// Forget multiple keys...
$request->session()->forget(['name', 'status']);

$request->session()->flush();

重新生成 Session ID

重新生成 session ID 通常是为了防止恶意用户对应用发动 session fixation 攻击。

若使用 Laravel 应用起步套件或 Laravel Fortify，Laravel 会在认证过程中自动重新生成 session ID；不过，若需要手动重新生成 session ID，可使用 regenerate 方法：

php

$request->session()->regenerate();

若需要在一条语句中重新生成 session ID 并移除 session 中的全部数据，可使用 invalidate 方法：

php

$request->session()->invalidate();

Session 缓存

Laravel 的 session 缓存提供了一种便捷方式，用于缓存限定在单个用户 session 范围内的数据。与全局应用缓存不同，session 缓存数据会按 session 自动隔离，并在 session 过期或销毁时清理。session 缓存支持熟悉的 Laravel 缓存方法，如 get、put、remember、forget 等，但作用域限定为当前 session。

session 缓存非常适合存储临时的、用户相关的数据：希望在同一 session 的多次请求间保留，但不必永久存储。这包括表单数据、临时计算结果、API 响应，或任何应绑定到特定用户 session 的短暂数据。

可通过 session 上的 cache 方法访问 session 缓存：

php

$discount = $request->session()->cache()->get('discount');

$request->session()->cache()->put(
    'discount', 10, now()->plus(minutes: 5)
);

有关 Laravel 缓存方法的更多信息，请参阅缓存文档。

Session 阻塞

WARNING

要使用 session 阻塞，应用必须使用支持原子锁的缓存驱动。目前这些缓存驱动包括 memcached、dynamodb、redis、mongodb（包含在官方 mongodb/laravel-mongodb 包中）、database、file 与 array。此外，不能使用 cookie session 驱动。

默认情况下，Laravel 允许使用同一 session 的请求并发执行。例如，若使用 JavaScript HTTP 库向应用发起两个 HTTP 请求，它们会同时执行。对许多应用而言这不是问题；但在少数应用中，若对两个都会向 session 写入数据的不同端点发起并发请求，可能发生 session 数据丢失。

为缓解此问题，Laravel 提供了限制给定 session 并发请求的功能。开始时，只需在路由定义上链式调用 block 方法。在本例中，发往 /profile 端点的传入请求会获取 session 锁。持有该锁期间，发往 /profile 或 /order 且共享同一 session ID 的任何传入请求，都会等待第一个请求执行完毕后再继续：

php

Route::post('/profile', function () {
    // ...
})->block($lockSeconds = 10, $waitSeconds = 10);

Route::post('/order', function () {
    // ...
})->block($lockSeconds = 10, $waitSeconds = 10);

block 方法接受两个可选参数。第一个参数是 session 锁在释放前应持有的最长秒数。当然，若请求在此时间之前执行完毕，锁会更早释放。

block 方法的第二个参数是请求在尝试获取 session 锁时应等待的秒数。若请求在给定秒数内无法获取 session 锁，将抛出 Illuminate\Contracts\Cache\LockTimeoutException。

若两个参数都不传，锁最长持有 10 秒，请求在尝试获取锁时最多等待 10 秒：

php

Route::post('/profile', function () {
    // ...
})->block();

添加自定义 Session 驱动

实现驱动

若现有 session 驱动都不符合应用需求，Laravel 允许你编写自己的 session 处理器。自定义 session 驱动应实现 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) {}
}

Laravel 没有默认的扩展存放目录，你可随意放置。本例中我们创建了 Extensions 目录来存放 MongoSessionHandler。

这些方法的用途可能并不直观，下面概述各方法的作用：

`open` 方法通常用于基于文件的 session 存储系统。由于 Laravel 已内置 `file` session 驱动，你很少需要在此方法中写入内容，可直接留空。
`close` 方法与 `open` 类似，通常也可忽略。对大多数驱动而言并不需要。
`read` 方法应返回与给定 `$sessionId` 关联的 session 数据的字符串形式。在驱动中检索或存储 session 数据时无需进行序列化或其他编码，Laravel 会为你完成序列化。
`write` 方法应将与 `$sessionId` 关联的给定 `$data` 字符串写入某种持久化存储系统，例如 MongoDB 或你选择的其他存储。同样，你不应进行任何序列化——Laravel 已为你处理。
`destroy` 方法应从持久化存储中移除与 `$sessionId` 关联的数据。
`gc` 方法应销毁所有早于给定 `$lifetime`（UNIX 时间戳）的 session 数据。对于 Memcached、Redis 等自过期系统，此方法可留空。

注册驱动

实现驱动后，即可将其注册到 Laravel。要向 Laravel 的 session 后端添加额外驱动，可使用 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 驱动注册完成后，可通过 SESSION_DRIVER 环境变量或应用的 config/session.php 配置文件，将 mongo 指定为应用的 session 驱动。

HTTP Session ​

简介 ​

配置 ​

驱动前提条件 ​

数据库 ​

Redis ​

与 Session 交互 ​

检索数据 ​

全局 Session 辅助函数 ​

检索全部 Session 数据 ​

检索部分 Session 数据 ​

判断条目是否存在于 Session ​

存储数据 ​

向数组型 Session 值追加 ​

检索并删除条目 ​

递增与递减 Session 值 ​

闪存数据 ​

删除数据 ​

重新生成 Session ID ​

Session 缓存 ​

Session 阻塞 ​

添加自定义 Session 驱动 ​

实现驱动 ​

注册驱动 ​

HTTP Session

简介

配置

驱动前提条件

数据库

Redis

与 Session 交互

检索数据

全局 Session 辅助函数

检索全部 Session 数据

检索部分 Session 数据

判断条目是否存在于 Session

存储数据

向数组型 Session 值追加

检索并删除条目

递增与递减 Session 值

闪存数据

删除数据

重新生成 Session ID

Session 缓存

Session 阻塞

添加自定义 Session 驱动

实现驱动

注册驱动