Laravel 中文文档

主题

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

NOTE

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 包（~1.0）。有关配置 Redis 的更多信息，请查阅 Laravel 的 Redis 文档。

NOTE

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

与 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
{
    /**
     * 显示给定用户的个人资料。
     */
    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 () {
    // 从 session 中获取一条数据...
    $value = session('key');

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

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

NOTE

通过 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
// 通过请求实例...
$request->session()->put('key', 'value');

// 通过全局 "session" 辅助函数...
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
// 忘记单个键...
$request->session()->forget('name');

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

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

重新生成 Session ID ​

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

如果你使用的是 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 方法接受两个可选参数。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 的 session 数据，$lifetime 是一个 UNIX 时间戳。对于像 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
{
    /**
     * 注册任何应用程序服务。
     */
    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 驱动。