# HTTP 会话

-   [简介](#introduction)
    -   [配置](#configuration)
    -   [驱动程序前置条件](#driver-prerequisites)
-   [与会话交互](#interacting-with-the-session)
    -   [获取数据](#retrieving-data)
    -   [存储数据](#storing-data)
    -   [闪存数据](#flash-data)
    -   [删除数据](#deleting-data)
    -   [重新生成会话 ID](#regenerating-the-session-id)
-   [会话缓存](#session-cache)
-   [会话阻塞](#session-blocking)
-   [添加自定义会话驱动](#adding-custom-session-drivers)
    -   [实现驱动](#implementing-the-driver)
    -   [注册驱动](#registering-the-driver)

## 简介

由于 HTTP 驱动的应用程序是无状态的，因此会话提供了一种在多个请求之间存储用户信息的方式。这些用户信息通常会被存放在持久化存储 / 后端中，以便后续请求能够访问。

Laravel 自带多种会话后端，并通过富有表现力且统一的 API 进行访问。内置支持包括 [Memcached](https://memcached.org)、[Redis](https://redis.io) 和数据库等常用后端。

### 配置

应用程序的会话配置文件存储在 `config/session.php` 中。请务必查看该文件中提供的各项配置选项。默认情况下，Laravel 配置为使用 `database` 会话驱动。

会话的 `driver` 配置选项定义了每个请求的会话数据将存储在何处。Laravel 提供了多种驱动：

<div class="content-list" markdown="1">

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

</div>

> [!注意]
> `array` 驱动主要用于[测试](/docs/laravel/13.x/testing)，并会阻止存储在会话中的数据被持久化。



### 驱动程序前置条件

#### 数据库

使用 `database` 会话驱动时，你需要确保数据库中存在一个用于存储会话数据的表。通常情况下，Laravel 默认的 `0001_01_01_000000_create_users_table.php` [数据库迁移](/docs/laravel/13.x/migrations)中已经包含该表；不过，如果由于某种原因你没有 `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 文档](/docs/laravel/13.x/redis#configuration)。

> [!注意]
> 可以使用 `SESSION_CONNECTION` 环境变量，或者 `session.php` 配置文件中的 `connection` 选项，来指定用于会话存储的 Redis 连接。

## 与会话交互

### 获取数据

在 Laravel 中处理会话数据主要有两种方式：使用全局 `session` 辅助函数，以及通过 `Request` 实例。首先，我们来看如何通过 `Request` 实例访问会话。你可以在路由闭包或控制器方法中对该实例进行类型提示。请记住，控制器方法的依赖项会通过 Laravel [服务容器](/docs/laravel/13.x/container)自动注入：

```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 辅助函数

你也可以使用全局 `session` PHP 函数来获取和存储会话中的数据。当使用单个字符串参数调用 `session` 辅助函数时，它会返回该会话键对应的值。当使用由键 / 值对组成的数组调用该辅助函数时，这些值将被存储到会话中：

```php
Route::get('/home', function () {
    // 从会话中获取一项数据...
    $value = session('key');

    // 指定默认值...
    $value = session('key', 'default');

    // 在会话中存储一项数据...
    session(['key' => 'value']);
});
```

> [!注意]
> 通过 HTTP 请求实例使用会话与使用全局 `session` 辅助函数，在实际使用上几乎没有区别。这两种方式都可以通过 `assertSessionHas` 方法进行[测试](/docs/laravel/13.x/testing)，该方法在所有测试用例中都可用。

#### 获取所有会话数据

如果你希望获取会话中的所有数据，可以使用 `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
// 通过请求实例...
$request->session()->put('key', 'value');

// 通过全局 "session" 辅助函数...
session(['key' => 'value']);
```

#### 向会话数组值中追加数据

`push` 方法可用于向值为数组的会话项中追加一个新值。例如，如果 `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);
```

### Flash 数据

有时你可能希望将项目存储在 session 中，以供下一次请求使用。你可以使用 `flash` 方法来实现。使用此方法存储在 session 中的数据将立即可用，并且在随后的 HTTP 请求期间也可用。在随后的 HTTP 请求之后，flash 数据将被删除。Flash 数据主要用于短期状态消息：

```php
$request->session()->flash('status', 'Task was successful!');
```

如果你需要让 flash 数据在多个请求中持续存在，可以使用 `reflash` 方法，它会将所有 flash 数据额外保留一个请求。如果你只需要保留特定的 flash 数据，可以使用 `keep` 方法：

```php
$request->session()->reflash();

$request->session()->keep(['username', 'email']);
```

如果只想让 flash 数据在当前请求中持续存在，可以使用 `now` 方法：

```php
$request->session()->now('status', 'Task was successful!');
```

### 删除数据

`forget` 方法将从 session 中删除一项数据。如果你想从 session 中删除所有数据，可以使用 `flush` 方法：

```php
// 删除单个键...
$request->session()->forget('name');

// 删除多个键...
$request->session()->forget(['name', 'status']);

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



### 重新生成 Session ID

重新生成 session ID 通常是为了防止恶意用户利用 [session fixation](https://owasp.org/www-community/attacks/Session_fixation) 攻击你的应用程序。

如果你正在使用 Laravel 的某个 [应用程序入门套件](/docs/laravel/13.x/starter-kits) 或 [Laravel Fortify](/docs/laravel/13.x/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 缓存方法](/docs/laravel/13.x/cache)，例如 `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 缓存方法的更多信息，请参阅 [缓存文档](/docs/laravel/13.x/cache)。

## Session 阻塞

> [!警告]
> 要使用 session 阻塞，你的应用程序必须使用支持 [原子锁](/docs/laravel/13.x/cache#atomic-locks) 的缓存驱动。目前，这些缓存驱动包括 `memcached`、`dynamodb`、`redis`、`mongodb`（包含在官方 `mongodb/laravel-mongodb` 包中）、`database`、`file` 和 `array` 驱动。此外，你不能使用 `cookie` session 驱动。

默认情况下，Laravel 允许使用同一个 session 的请求并发执行。例如，如果你使用 JavaScript HTTP 库向你的应用程序发起两个 HTTP 请求，它们将同时执行。对于许多应用程序来说，这并不是问题；但是，在一小部分应用程序中，如果并发请求访问两个不同的应用程序端点，并且这两个端点都会向 session 写入数据，就可能发生 session 数据丢失。

为了缓解这个问题，Laravel 提供了允许你限制给定 session 并发请求的功能。要开始使用，你只需在路由定义后链式调用 `block` 方法即可。在这个示例中，传入 `/profile` 端点的请求会获取一个 session 锁。在持有该锁期间，任何共享相同 session ID 的、传入 `/profile` 或 `/order` 端点的请求，都会等待第一个请求执行完成后再继续执行：

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

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

`block` 方法接受两个可选参数。`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`。

由于这些方法的用途并不是一目了然，下面概述了每个方法的用途：

<div class="content-list" markdown="1">

-   `open` 方法通常用于基于文件的 session 存储系统。由于 Laravel 自带 `file` session 驱动，因此你很少需要在这个方法中放入任何内容。你可以直接将这个方法留空。
-   `close` 方法和 `open` 方法一样，通常也可以忽略。对于大多数驱动来说，并不需要它。
-   `read` 方法应该返回与给定 `$sessionId` 关联的 session 数据的字符串形式。在你的驱动中读取或存储 session 数据时，不需要进行任何序列化或其他编码，因为 Laravel 会替你完成序列化。
-   `write` 方法应该将与 `$sessionId` 关联的给定 `$data` 字符串写入某个持久化存储系统，例如 MongoDB 或你选择的其他存储系统。同样，你不应该执行任何序列化，因为 Laravel 已经替你处理好了。
-   `destroy` 方法应该从持久化存储中删除与 `$sessionId` 关联的数据。
-   `gc` 方法应该销毁所有早于给定 `$lifetime` 的 session 数据，其中 `$lifetime` 是一个 UNIX 时间戳。对于像 Memcached 和 Redis 这样会自行过期的系统，这个方法可以留空。

</div>



### 注册驱动

一旦你的驱动已经实现，就可以将其注册到 Laravel 中。要向 Laravel 的 session 后端添加额外的驱动，你可以使用 `Session` [门面](/docs/laravel/13.x/facades) 提供的 `extend` 方法。你应该在 [服务提供者](/docs/laravel/13.x/providers) 的 `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
{
    /**
     * 注册任何应用程序服务。
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 启动任何应用程序服务。
     */
    public function boot(): void
    {
        Session::extend('mongo', function (Application $app) {
            // 返回一个 SessionHandlerInterface 的实现...
            return new MongoSessionHandler;
        });
    }
}
```

一旦 session 驱动注册完成，你可以使用 `SESSION_DRIVER` 环境变量，或在应用程序的 `config/session.php` 配置文件中，将 `mongo` 驱动指定为应用程序的 session 驱动。