Laravel 11.x 中文文档

简体中文

English

简体中文

English

主题

上下文 ​

介绍 ​

Laravel 的“上下文”功能使您能够在应用程序中捕获、检索和共享信息，这些信息在请求、作业和命令执行过程中被捕获。这些捕获的信息也包含在应用程序写入的日志中，使您能够更深入地了解在写入日志条目之前发生的代码执行历史，并允许您在分布式系统中追踪执行流程。

工作原理 ​

理解 Laravel 的上下文功能的最佳方式是通过内置的日志记录功能来观察它的实际应用。要开始，您可以使用 Context 门面 添加信息到上下文。在这个例子中，我们将使用一个 中间件 在每个传入请求中将请求 URL 和唯一的追踪 ID 添加到上下文中：

php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Context;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AddContext
{
    /**
     * 处理传入请求。
     */
    public function handle(Request $request, Closure $next): Response
    {
        Context::add('url', $request->url());
        Context::add('trace_id', Str::uuid()->toString());

        return $next($request);
    }
}

添加到上下文的信息会自动附加为任何 日志条目 的元数据，这些日志条目在请求过程中被写入。将上下文附加为元数据允许区分传递给单个日志条目的信息与通过 Context 共享的信息。例如，假设我们写下以下日志条目：

php
Log::info('用户已认证。', ['auth_id' => Auth::id()]);

写入的日志将包含传递给日志条目的 auth_id，但它也将包含上下文的 url 和 trace_id 作为元数据：

用户已认证。 {"auth_id":27} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}

添加到上下文的信息也可用于调度到队列的作业。例如，假设我们在添加一些信息到上下文后调度一个 ProcessPodcast 作业到队列：

php
// 在我们的中间件中...
Context::add('url', $request->url());
Context::add('trace_id', Str::uuid()->toString());

// 在我们的控制器中...
ProcessPodcast::dispatch($podcast);

当作业被调度时，当前上下文中存储的任何信息都会被捕获并与作业共享。捕获的信息在作业执行时会被重新注入到当前上下文中。因此，如果我们的作业的处理方法写入日志：

php
class ProcessPodcast implements ShouldQueue
{
    use Queueable;

    // ...

    /**
     * 执行作业。
     */
    public function handle(): void
    {
        Log::info('处理播客。', [
            'podcast_id' => $this->podcast->id,
        ]);

        // ...
    }
}

生成的日志条目将包含在最初调度作业时添加到上下文的信息：

处理播客。 {"podcast_id":95} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}

尽管我们专注于 Laravel 上下文的内置日志记录相关功能，以下文档将说明上下文如何允许您在 HTTP 请求 / 队列作业边界之间共享信息，甚至如何添加 隐藏上下文数据，这些数据不会与日志条目一起写入。

捕获上下文 ​

您可以使用 Context 门面的 add 方法在当前上下文中存储信息：

php
use Illuminate\Support\Facades\Context;

Context::add('key', 'value');

要一次添加多个项目，您可以将关联数组传递给 add 方法：

php
Context::add([
    'first_key' => 'value',
    'second_key' => 'value',
]);

add 方法将覆盖任何共享相同键的现有值。如果您只希望在键不存在的情况下将信息添加到上下文中，可以使用 addIf 方法：

php
Context::add('key', 'first');

Context::get('key');
// "first"

Context::addIf('key', 'second');

Context::get('key');
// "first"

条件上下文 ​

when 方法可用于根据给定条件将数据添加到上下文中。提供给 when 方法的第一个闭包将在给定条件评估为 true 时被调用，而第二个闭包将在条件评估为 false 时被调用：

php
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Context;

Context::when(
    Auth::user()->isAdmin(),
    fn ($context) => $context->add('permissions', Auth::user()->permissions),
    fn ($context) => $context->add('permissions', []),
);

堆栈 ​

上下文提供了创建“堆栈”的能力，这些堆栈是按添加顺序存储的数据列表。您可以通过调用 push 方法向堆栈添加信息：

php
use Illuminate\Support\Facades\Context;

Context::push('breadcrumbs', 'first_value');

Context::push('breadcrumbs', 'second_value', 'third_value');

Context::get('breadcrumbs');
// [
//     'first_value',
//     'second_value',
//     'third_value',
// ]

堆栈对于捕获请求的历史信息非常有用，例如在应用程序中发生的事件。例如，您可以创建一个事件监听器，每次执行查询时将查询 SQL 和持续时间作为元组推送到堆栈：

php
use Illuminate\Support\Facades\Context;
use Illuminate\Support\Facades\DB;

DB::listen(function ($event) {
    Context::push('queries', [$event->time, $event->sql]);
});

您可以使用 stackContains 和 hiddenStackContains 方法确定堆栈中是否存在某个值：

php
if (Context::stackContains('breadcrumbs', 'first_value')) {
    //
}

if (Context::hiddenStackContains('secrets', 'first_value')) {
    //
}

stackContains 和 hiddenStackContains 方法还接受一个闭包作为第二个参数，允许对值比较操作进行更多控制：

php
use Illuminate\Support\Facades\Context;
use Illuminate\Support\Str;

return Context::stackContains('breadcrumbs', function ($value) {
    return Str::startsWith($value, 'query_');
});

检索上下文 ​

您可以使用 Context 门面的 get 方法从上下文中检索信息：

php
use Illuminate\Support\Facades\Context;

$value = Context::get('key');

only 方法可用于检索上下文中的一部分信息：

php
$data = Context::only(['first_key', 'second_key']);

pull 方法可用于从上下文中检索信息并立即将其从上下文中移除：

php
$value = Context::pull('key');

如果上下文数据存储在 堆栈 中，您可以使用 pop 方法从堆栈中弹出项目：

php
Context::push('breadcrumbs', 'first_value', 'second_value');

Context::pop('breadcrumbs')
// second_value

Context::get('breadcrumbs');
// ['first_value']

如果您想检索存储在上下文中的所有信息，可以调用 all 方法：

php
$data = Context::all();

确定项目存在性 ​

您可以使用 has 方法确定上下文中是否存储了给定键的任何值：

php
use Illuminate\Support\Facades\Context;

if (Context::has('key')) {
    // ...
}

has 方法将返回 true，无论存储的值是什么。因此，例如，具有 null 值的键将被视为存在：

php
Context::add('key', null);

Context::has('key');
// true

移除上下文 ​

forget 方法可用于从当前上下文中移除一个键及其值：

php
use Illuminate\Support\Facades\Context;

Context::add(['first_key' => 1, 'second_key' => 2]);

Context::forget('first_key');

Context::all();

// ['second_key' => 2]

您可以通过提供一个数组给 forget 方法一次性忘记多个键：

php
Context::forget(['first_key', 'second_key']);

隐藏上下文 ​

上下文提供了存储“隐藏”数据的能力。这些隐藏的信息不会附加到日志中，并且无法通过上述文档中记录的数据检索方法访问。上下文提供了一组不同的方法来与隐藏上下文信息进行交互：

php
use Illuminate\Support\Facades\Context;

Context::addHidden('key', 'value');

Context::getHidden('key');
// 'value'

Context::get('key');
// null

“隐藏”方法镜像了上述非隐藏方法的功能：

php
Context::addHidden(/* ... */);
Context::addHiddenIf(/* ... */);
Context::pushHidden(/* ... */);
Context::getHidden(/* ... */);
Context::pullHidden(/* ... */);
Context::popHidden(/* ... */);
Context::onlyHidden(/* ... */);
Context::allHidden(/* ... */);
Context::hasHidden(/* ... */);
Context::forgetHidden(/* ... */);

事件 ​

上下文调度两个事件，允许您在上下文的水合和脱水过程中进行钩子。

为了说明这些事件如何使用，想象一下在您应用程序的中间件中，您根据传入 HTTP 请求的 Accept-Language 头设置 app.locale 配置值。上下文的事件允许您在请求期间捕获此值，并在队列上恢复它，确保在队列上发送的通知具有正确的 app.locale 值。我们可以使用上下文的事件和 隐藏 数据来实现这一点，以下文档将说明。

脱水 ​

每当作业被调度到队列时，上下文中的数据会被“脱水”并与作业的有效负载一起捕获。Context::dehydrating 方法允许您注册一个闭包，该闭包将在脱水过程中被调用。在此闭包内，您可以对将与排队作业共享的数据进行更改。

通常，您应该在应用程序的 AppServiceProvider 类的 boot 方法中注册 dehydrating 回调：

php
use Illuminate\Log\Context\Repository;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Context;

/**
 * 启动任何应用程序服务。
 */
public function boot(): void
{
    Context::dehydrating(function (Repository $context) {
        $context->addHidden('locale', Config::get('app.locale'));
    });
}
lightbulb

您不应在 dehydrating 回调中使用 Context 门面，因为这将改变当前进程的上下文。确保您只对传递给回调的存储库进行更改。

水合 ​

每当排队的作业开始在队列上执行时，任何与作业共享的上下文都会被“水合”回当前上下文。Context::hydrated 方法允许您注册一个闭包，该闭包将在水合过程中被调用。

通常，您应该在应用程序的 AppServiceProvider 类的 boot 方法中注册 hydrated 回调：

php
use Illuminate\Log\Context\Repository;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Context;

/**
 * 启动任何应用程序服务。
 */
public function boot(): void
{
    Context::hydrated(function (Repository $context) {
        if ($context->hasHidden('locale')) {
            Config::set('app.locale', $context->getHidden('locale'));
        }
    });
}
lightbulb

您不应在 hydrated 回调中使用 Context 门面，而应确保只对传递给回调的存储库进行更改。

版权所有 © 2024-2025 laravel.wiki