简介

由于 HTTP 驱动的应用程序是无状态的，会话提供了一种在多个请求中存储有关用户信息的方法。该用户信息通常放置在可以从后续请求访问的持久性存储/后端中。

Laravel 附带了各种通过富有表现力的统一 API 访问的会话后端。包括对流行后端的支持，如Memcached (opens in a new tab)、Redis (opens in a new tab)和数据库。

配置

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

会话driver配置选项定义了每个请求的会话数据将存储在哪里。Laravel 包括多种驱动程序：

[!注意]
array驱动程序主要在测试期间使用，并防止会话中存储的数据被持久化。

驱动程序先决条件

数据库

当使用database会话驱动程序时，您需要确保有一个数据库表来包含会话数据。通常，这包含在 Laravel 的默认0001_01_01_000000_create_users_table.php数据库迁移中；但是，如果由于任何原因您没有sessions表，您可以使用make:session-table Artisan 命令生成此迁移：

php artisan make:session-table
 
php artisan migrate

Redis

在使用 Laravel 的 Redis 会话之前，您需要通过 PECL 安装 PhpRedis PHP 扩展或通过 Composer 安装predis/predis包（~1.0）。有关配置 Redis 的更多信息，请查阅 Laravel 的Redis 文档。

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

与会话进行交互

检索数据

在 Laravel 中有两种处理会话数据的主要方式：全局session助手和通过Request实例。首先，让我们看看通过Request实例访问会话，它可以在路由闭包或控制器方法中进行类型提示。请记住，控制器方法依赖项通过 Laravel 服务容器自动注入：

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 显示给定用户的个人资料。
     */
    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方法，并且请求的键不存在，则将执行闭包并返回其结果：

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

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

全局会话助手

您还可以使用全局session PHP 函数在会话中检索和存储数据。当使用单个字符串参数调用session助手时，它将返回该会话键的值。当使用键/值对数组调用助手时，这些值将存储在会话中：

Route::get('/home', function () {
    // 从会话中检索一条数据...
    $value = session('key');

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

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

[!注意]
通过 HTTP 请求实例使用会话与使用全局session助手之间几乎没有实际区别。两种方法都可以通过在所有测试用例中可用的assertSessionHas方法进行测试。

检索所有会话数据

如果您想要检索会话中的所有数据，可以使用 all 方法：

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

检索会话数据的一部分

only 和 except 方法可用于检索会话数据的一个子集：

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

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

确定会话中是否存在某一项

要确定一个项是否存在于会话中，如果该项存在且不为 null，您可以使用 has 方法。has 方法会返回 true：

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

要确定一个项是否存在于会话中，即使其值为 null，您可以使用 exists 方法：

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

要确定一个项不存在于会话中，您可以使用 missing 方法。如果该项不存在，missing 方法会返回 true：

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

存储数据

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

// 通过请求实例...
$request->session()->put('key', 'value');

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

向数组会话值推送

push 方法可用于将会话值（该值为数组）中推送一个新值。例如，如果 user.teams 键包含一个团队名称数组，您可以像这样向数组中推送一个新值：

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

检索并删除一项

pull 方法将在一个语句中从会话中检索并删除一项：

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

递增和递减会话值

如果您的会话数据包含一个整数，您希望对其进行递增或递减，可以使用 increment 和 decrement 方法：

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

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

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

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

闪存数据

有时您可能希望将会话项存储到下一个请求中。您可以使用 flash 方法来实现。使用此方法存储在会话中的数据将立即可用，并在后续的 HTTP 请求期间可用。在后续的 HTTP 请求之后，闪存数据将被删除。闪存数据主要用于短暂的状态消息：

$request->session()->flash('status', '任务已成功！');

如果您需要为多个请求保留您的闪存数据，您可以使用 reflash 方法，这将为另一个请求保留所有的闪存数据。如果您只需要保留特定的闪存数据，您可以使用 keep 方法：

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

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

如果您只想为当前请求保留您的闪存数据，您可以使用 now 方法：

$request->session()->now('status', '任务已成功！');

删除数据

forget 方法将从会话中删除一段数据。如果您想要从会话中删除所有数据，可以使用 flush 方法：

// 忘记一个单个键...
$request->session()->forget('name');

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

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

重新生成会话 ID

重新生成会话 ID 通常是为了防止恶意用户利用您的应用程序中的 会话固定 (opens in a new tab) 攻击。

如果您使用的是 Laravel 的 应用程序启动套件 或 Laravel Fortify 之一，Laravel 会在认证期间自动重新生成会话 ID；但是，如果您需要手动重新生成会话 ID，您可以使用 regenerate 方法：

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

如果您需要在一个语句中重新生成会话 ID 并从会话中删除所有数据，您可以使用 invalidate 方法：

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

会话阻塞

[!WARNING]
要使用会话阻塞功能，您的应用程序必须使用支持原子锁的缓存驱动程序。目前，这些缓存驱动程序包括 memcached、dynamodb、redis、database、file 和 array 驱动程序。此外，您不能使用 cookie 会话驱动程序。

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

为了缓解这个问题，Laravel 提供了一种功能，允许您限制给定会话的并发请求。要开始使用，您可以简单地将 block 方法链接到您的路由定义上。在这个示例中，对 /profile 端点的传入请求将获取会话锁。在持有此锁期间，对具有相同会话 ID 的 /profile 或 /order 端点的任何传入请求将等待第一个请求完成执行后再继续执行：

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 秒：

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

添加自定义会话驱动程序

实现驱动程序

如果现有的会话驱动程序都不符合您的应用程序需求，Laravel 允许您编写自己的会话处理程序。您的自定义会话驱动程序应该实现 PHP 内置的 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) {}
}

[!NOTE]
Laravel 没有附带一个目录来包含您的扩展。您可以将它们放在您喜欢的任何地方。在这个示例中，我们创建了一个 Extensions 目录来存放 MongoSessionHandler。

由于这些方法的目的不太容易理解，让我们快速了解一下每个方法的作用：

注册驱动程序

一旦您的驱动程序实现完成，您就可以准备将其注册到 Laravel 中。要向 Laravel 的会话后端添加其他驱动程序，您可以使用 Session 外观提供的 extend 方法。您应该从 服务提供者的 boot 方法中调用 extend 方法。您可以从现有的 App\Providers\AppServiceProvider 中进行此操作，或者创建一个全新的提供者：

<?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_DRIVER 环境变量或在应用程序的 config/session.php 配置文件中指定 mongo 驱动程序作为您的应用程序的会话驱动程序。