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 数组中，不会被持久化。

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

驱动程序先决条件

数据库

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

1php artisan make:session-table
2 
3php artisan migrate

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 服务容器自动注入

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\Request;
 6use Illuminate\View\View;
 7 
 8class UserController extends Controller
 9{
10    /**
11     * Show the profile for the given user.
12     */
13    public function show(Request $request, string $id): View
14    {
15        $value = $request->session()->get('key');
16 
17        // ...
18 
19        $user = $this->users->find($id);
20 
21        return view('user.profile', ['user' => $user]);
22    }
23}

<?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 方法，并且请求的键不存在，则将执行该闭包并返回其结果

1$value = $request->session()->get('key', 'default');
2 
3$value = $request->session()->get('key', function () {
4    return 'default';
5});

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

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

全局会话助手函数

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

 1Route::get('/home', function () {
 2    // Retrieve a piece of data from the session...
 3    $value = session('key');
 4 
 5    // Specifying a default value...
 6    $value = session('key', 'default');
 7 
 8    // Store a piece of data in the session...
 9    session(['key' => 'value']);
10});

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']);
});

通过 HTTP 请求实例使用会话与使用全局 session 助手函数之间几乎没有实际区别。这两种方法都可以通过 assertSessionHas 方法进行测试，该方法在您的所有测试用例中都可用。

检索所有会话数据

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

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

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

检索会话数据的一部分

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

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

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

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

确定会话中是否存在项目

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

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

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

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

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

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

要确定会话中是否不存在项目，您可以使用 missing 方法。如果项目不存在，则 missing 方法返回 true

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

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

存储数据

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

1// Via a request instance...
2$request->session()->put('key', 'value');
3 
4// Via the global "session" helper...
5session(['key' => 'value']);

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

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

推送到数组会话值

push 方法可用于将新值推送到作为数组的会话值。例如，如果 user.teams 键包含团队名称数组，您可以像这样将新值推送到数组

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

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

检索和删除项目

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

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

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

递增和递减会话值

如果您的会话数据包含您希望递增或递减的整数，您可以使用 increment 和 decrement 方法

1$request->session()->increment('count');
2 
3$request->session()->increment('count', $incrementBy = 2);
4 
5$request->session()->decrement('count');
6 
7$request->session()->decrement('count', $decrementBy = 2);

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

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

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

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

Flash 数据

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

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

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

如果您需要为多个请求持久化您的 Flash 数据，您可以使用 reflash 方法，这将使所有 Flash 数据再保留一个请求。如果您只需要保留特定的 Flash 数据，您可以使用 keep 方法

1$request->session()->reflash();
2 
3$request->session()->keep(['username', 'email']);

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

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

要仅为当前请求持久化您的 Flash 数据，您可以使用 now 方法

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

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

删除数据

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

1// Forget a single key...
2$request->session()->forget('name');
3 
4// Forget multiple keys...
5$request->session()->forget(['name', 'status']);
6 
7$request->session()->flush();

// 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 方法

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

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

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

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

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

会话阻塞

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

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

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

1Route::post('/profile', function () {
2    // ...
3})->block($lockSeconds = 10, $waitSeconds = 10);
4 
5Route::post('/order', function () {
6    // ...
7})->block($lockSeconds = 10, $waitSeconds = 10);

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 秒

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

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

添加自定义会话驱动程序

实现驱动程序

如果现有的会话驱动程序都不能满足您应用程序的需求，Laravel 允许您编写自己的会话处理程序。您的自定义会话驱动程序应实现 PHP 的内置 SessionHandlerInterface。此接口仅包含几个简单的方法。桩 MongoDB 实现如下所示

 1<?php
 2 
 3namespace App\Extensions;
 4 
 5class MongoSessionHandler implements \SessionHandlerInterface
 6{
 7    public function open($savePath, $sessionName) {}
 8    public function close() {}
 9    public function read($sessionId) {}
10    public function write($sessionId, $data) {}
11    public function destroy($sessionId) {}
12    public function gc($lifetime) {}
13}

<?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 方法通常用于基于文件的会话存储系统。由于 Laravel 自带 file 会话驱动程序，因此您很少需要在此方法中放置任何内容。您可以简单地将此方法留空。
与 open 方法一样，通常也可以忽略 close 方法。对于大多数驱动程序，它不是必需的。
read 方法应返回与给定 $sessionId 关联的会话数据的字符串版本。在驱动程序中检索或存储会话数据时，无需进行任何序列化或其他编码，因为 Laravel 将为您执行序列化。
write 方法应将与 $sessionId 关联的给定 $data 字符串写入到某些持久存储系统，例如 MongoDB 或您选择的其他存储系统。同样，您不应执行任何序列化 - Laravel 已经为您处理了。
destroy 方法应从持久存储中删除与 $sessionId 关联的数据。
gc 方法应销毁早于给定 $lifetime 的所有会话数据，$lifetime 是 UNIX 时间戳。对于像 Memcached 和 Redis 这样的自过期系统，此方法可以留空。

注册驱动程序

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

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use App\Extensions\MongoSessionHandler;
 6use Illuminate\Contracts\Foundation\Application;
 7use Illuminate\Support\Facades\Session;
 8use Illuminate\Support\ServiceProvider;
 9 
10class SessionServiceProvider extends ServiceProvider
11{
12    /**
13     * Register any application services.
14     */
15    public function register(): void
16    {
17        // ...
18    }
19 
20    /**
21     * Bootstrap any application services.
22     */
23    public function boot(): void
24    {
25        Session::extend('mongo', function (Application $app) {
26            // Return an implementation of SessionHandlerInterface...
27            return new MongoSessionHandler;
28        });
29    }
30}

<?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 驱动程序指定为应用程序的会话驱动程序。

序言

快速入门

架构概念

基础知识

深入挖掘

安全

数据库

Eloquent ORM

测试

软件包

HTTP 会话

简介

配置

驱动程序先决条件

数据库

Redis

与会话交互

检索数据

全局会话助手函数

检索所有会话数据

检索会话数据的一部分

确定会话中是否存在项目

存储数据

推送到数组会话值

检索和删除项目

递增和递减会话值

Flash 数据

删除数据

重新生成会话 ID

会话阻塞

添加自定义会话驱动程序

实现驱动程序

注册驱动程序

产品

软件包

资源