会话 laravel laravelphp 中文文档

简介
- 配置
- 驱动程序先决条件
使用 Session
会话阻塞
添加自定义 Session 驱动程序
- 实现驱动程序
- 注册驱动程序

简介

由于 HTTP 驱动的应用程序是无状态的，Session 提供了一种在多个请求之间存储有关用户信息的方法，这类信息一般都存储在后续请求可以访问的持久存储 / 后端中。

Laravel 通过同一个可读性强的 API 处理各种自带的后台驱动程序。支持诸如比较热门的 Memcached、 Redis 和数据库。

配置

Session 的配置文件存储在 php config/session.php 文件中。请务必查看此文件中对于你而言可用的选项。默认情况下，Laravel 配置的 Session 驱动为 php database。

Session php driver 的配置预设了每个请求存储 Session 数据的位置。Laravel 自带了几个不错而且开箱即用的驱动：

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

技巧：数组驱动一般用于测试并且防止存储在 Session 中的数据被持久化。

驱动程序先决条件

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

php artisan make:session-table
php artisan migrate

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

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

使用 Session

获取数据

在 Laravel 中，处理会话数据有两种主要方法：全局的 php session 辅助函数和通过 php Request 实例。首先，让我们看一下如何通过 php 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]);
    }
}

当您从 Session 中检索一个项目时，您也可以将默认值作为第二个参数传递给 php get 方法。如果指定的键在 Session 中不存在，将返回这个默认值。如果您将闭包作为默认值传递给 php get 方法，且请求的键不存在，闭包将被执行并返回其结果：

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

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

Route::get('/home', function () {
    // 从 Session 中检索一条数据...
    $value = session('key');
    // 指定默认值...
    $value = session('key', 'default');
    // 在 Session 中存储一条数据...
    session(['key' => 'value']);
});

技巧
通过 HTTP 请求实例使用 session 与使用全局 php session 辅助函数之间几乎没有实际差异。这两种方法 testable 都可以通过 php assertSessionHas 方法进行测试，该方法在所有测试用例中都可用。

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

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

获取 Session 数据的一部分
可以使用 php only 和 php except 方法来获取会话数据的一部分：

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

确定 Session 中是否存在某项
要确定 Session 中是否存在某项，你可以使用 php has 方法。如果该项存在且不为 php null ，php has 方法将返回 php true。

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

要判断 Session 中是否存在某项，即使该项的值为 php null ，你可以使用 php exists 方法：

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

要判断 Session 中不存在某项时，你可以使用 php missing 方法。如果该项不存在，php missing 方法将返回 php true：

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

存储数据

Session 里存储数据，你通常将使用 Request 实例中的 php put 方法或者 php session 助手函数：

// 通过 Request 实例存储 ...
$request->session()->put('key', 'value');
// 通过全局 Session 助手函数存储 ...
session(['key' => 'value']);

向 Session 数组中添加元素
php push 方法可以把一个新值推入到以数组形式存储的 session 值里。例如：如果 php user.teams 键值对有一个关于团队名字的数组，你可以推入一个新值到这个数组里：

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

检索并删除项目
php pull 方法将在一个语句中从 Session 中检索并删除一个项目:

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

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

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

闪存数据

有时您可能希望将项目存储在 Session 中供下一个请求使用。您可以使用 php flash 方法来实现这一点。使用此方法存储在 Session 中的数据将立即可用，并在随后的 HTTP 请求中仍然可用。在随后的 HTTP 请求之后，闪存数据将被删除。闪存数据主要用于短期的状态消息：

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

如果您需要在多个请求中保持闪存数据，可以使用 php reflash 方法，它会将所有闪存数据保留到下一个请求。如果您只需要保留特定的闪存数据，可以使用 php keep 方法：

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

要仅在当前请求中保留您的闪存数据，您可以使用 php now 方法：

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

删除数据

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

// 删除一个单独的键值对 ...
$request->session()->forget('name');
// 删除多个键值对 ...
$request->session()->forget(['name', 'status']);
$request->session()->flush();

重新生成 Session ID

重新生成会话 ID 通常是为了防止恶意用户利用会话固定攻击对您的应用程序造成危害。

Laravel 在身份验证过程中，如果您使用 Laravel 的应用程序启步套件或 Laravel Fortify，会自动重新生成会话 ID。然而，如果您需要手动重新生成会话 ID，可以使用 php regenerate 方法：

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

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

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

会话阻塞

警告
要利用会话阻塞，您的应用程序必须使用支持原子锁（atomic locks）的缓存驱动。目前，这些缓存驱动包括 php memcached、php dynamodb、php redis、php database、php file 和 php array 驱动。此外，您不能使用 php cookie 会话驱动。

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

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

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

php block 方法接受两个可选参数。 php block 方法接受的第一个参数是 Session 锁应该持有的最大秒数，超过这个时间后锁将被释放。当然，如果请求在这个时间之前执行完毕，锁会更早释放。

php block 方法接受的第二个参数是请求在尝试获取 Session 锁时应该等待的秒数。如果请求在给定的秒数内无法获得 Session 锁，将抛出 php Illuminate\Contracts\Cache\LockTimeoutException 异常。

如果这两个参数都没有传递，锁将最多持有 10 秒，而请求在尝试获取锁时最多等待 10 秒：

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

添加自定义 Session 驱动程序

实现驱动程序

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

技巧
Laravel 并没有为您的扩展提供专门的目录。您可以自由地将它们放在任何您喜欢的地方。在这个例子中，我们创建了一个 php Extensions 目录来存放 php MongoSessionHandler 。

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

php open 方法通常用于基于文件的 Session 存储系统。因为 Laravel 自带了一个 php file Session 驱动程序，所以你很少需要在这个方法中添加任何东西。您可以简单地将此方法保留为空。
与 php open 方法一样，php close 方法通常也可以忽略。对于大多数驱动来说，这是不需要的。
php read 方法应该返回与给定 php $sessionId 相关联的 Session 数据的字符串版本。当在驱动程序中检索或存储会话数据时，不需要进行任何序列化或其他编码，因为 Laravel 将为您执行序列化。
php write 方法应该将给定的 php $data 字符串与 php $sessionId 关联到一些持久存储系统，例如 MongoDB 或您选择的其他存储系统。同样，你不应该执行任何序列化 - Laravel 已经为你处理过了。
php destroy 方法应该从持久存储中删除与 php $sessionId 相关的数据。
php gc 方法应该销毁比给定的 php $lifetime 更早的所有 Sessopm 数据，这是一个 UNIX 时间戳。对于像 Memcached 和 Redis 这样的自动过期系统，这个方法可能是空的。

注册驱动程序

一旦你的驱动程序被实现，你就可以在 Laravel 上注册它了。要为 Laravel 的会话后端添加额外的驱动程序，你可以使用 php Session 门面提供的 php extend 方法。你应该从服务提供者的 php boot 方法中调用 php extend 方法。您可以从现有的 php 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 驱动程序注册完毕，可以使用 php SESSION_DRIVER 环境变量或在应用程序的 php config/session.php 配置文件中将 php mongo 驱动程序指定为应用程序的 session 驱动程序。