上下文

• 介绍
  • 它是如何工作的
• 捕获上下文
  • 堆栈
• 检索上下文
  • 确定项是否存在
• 删除上下文
• 隐藏上下文
• 事件
  • 冻结
  • Hydrated

介绍

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

它是如何工作的

了解 Laravel 的上下文功能的最佳方式是使用内置的日志记录功能查看它的实际效果。首先，您可以使用 Context Facade将信息添加到上下文中。在此示例中，我们将使用中间件将请求 URL 和唯一的跟踪 ID 添加到每个传入请求的上下文中:

<?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
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        Context::add('url', $request->url());
        Context::add('trace_id', Str::uuid()->toString());

        return $next($request);
    }
}

添加到上下文的信息会自动作为元数据附加到整个请求中写入的任何日志条目。将 context 附加为元数据可以区分传递给各个日志条目的信息与通过 Context 共享的信息。例如，假设我们编写以下日志条目:

Log::info('User authenticated.', ['auth_id' => Auth::id()]);

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

User authenticated. {"auth_id":27} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}

添加到上下文的信息也可用于分派到队列的作业。例如，假设我们在向上下文添加一些信息后将 ProcessPodcast 作业分派到队列中:

// In our middleware...
Context::add('url', $request->url());
Context::add('trace_id', Str::uuid()->toString());

// In our controller...
ProcessPodcast::dispatch($podcast);

分派作业时，将捕获当前存储在上下文中的任何信息并与作业共享。然后，在执行作业时，捕获的信息将水合回当前上下文。所以，如果我们工作的 handle 方法是写入日志:

class ProcessPodcast implements ShouldQueue
{
    use Queueable;

    // ...

    /**
     * Execute the job.
     */
    public function handle(): void
    {
        Log::info('Processing podcast.', [
            'podcast_id' => $this->podcast->id,
        ]);

        // ...
    }
}

生成的日志条目将包含在最初分派作业的请求期间添加到上下文中的信息:

Processing podcast. {"podcast_id":95} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}

虽然我们专注于 Laravel 上下文的内置日志相关功能，但以下文档将说明 context 如何允许你跨 HTTP 请求 / 排队作业边界共享信息，甚至如何添加未与日志条目一起写入的隐藏上下文数据。

捕获上下文

你可以使用 Context Facade 的 add 方法在当前上下文中存储信息:

use Illuminate\Support\Facades\Context;

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

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

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

add 方法将覆盖共享同一键的任何现有值。如果你只想在键不存在的情况下向上下文中添加信息，你可以使用 addIf 方法:

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

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

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

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

条件上下文

when 方法可用于根据给定条件将数据添加到上下文中。如果给定条件的计算结果为 true，则将调用提供给 when 方法的第一个闭包，如果条件的计算结果为 false，则将调用第二个闭包:

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

堆栈

Context 提供了创建“堆栈”的功能，“堆栈”是按添加顺序存储的数据列表。您可以通过调用 push 方法将信息添加到堆栈中:

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 和 duration 捕获为元组:

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

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

您可以使用 stackContains 和 hiddenStackContains 方法确定值是否在堆栈中:

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

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

stackContains 和 hiddenStackContains 方法也接受闭包作为其第二个参数，从而允许对值比较操作进行更多控制:

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

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

检索上下文

你可以使用 Context Facade 的 get 方法从上下文中检索信息:

use Illuminate\Support\Facades\Context;

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

only 方法可用于检索上下文中的信息子集:

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

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

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

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

$data = Context::all();

确定项是否存在

你可以使用 has 方法来确定上下文是否为给定的键存储了任何值:

use Illuminate\Support\Facades\Context;

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

无论存储的值如何，has 方法都将返回 true。因此，例如，具有 null 值的 key 将被视为存在:

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

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

删除上下文

forget 方法可用于从当前上下文中删除键及其值:

use Illuminate\Support\Facades\Context;

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

Context::forget('first_key');

Context::all();

// ['second_key' => 2]

你可以通过向 forget 方法提供一个数组来一次忘记几个键:

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

隐藏上下文

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

use Illuminate\Support\Facades\Context;

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

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

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

“隐藏”方法反映了上面记录的非隐藏方法的功能:

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

事件

Context 调度两个事件，允许您挂接到上下文的冻结和冻结过程。

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

冻结

每当将作业分派到队列时，上下文中的数据都会被“冻结”并与作业的有效负载一起捕获。Context::d ehydrating 方法允许您注册将在冻结过程中调用的闭包。在此 Close 中，您可以更改将与排队作业共享的数据。

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

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Context::dehydrating(function (Repository $context) {
        $context->addHidden('locale', Config::get('app.locale'));
    });
}

NOTE

您不应在冻结回调中使用 Context 外观，因为这会更改当前流程的上下文。确保仅对传递给回调的存储库进行更改。

Hydrated

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

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

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Context::hydrated(function (Repository $context) {
        if ($context->hasHidden('locale')) {
            Config::set('app.locale', $context->getHidden('locale'));
        }
    });
}

NOTE

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