Context

Introduction
- How it Works
Capturing Context
- Stacks
Retrieving Context
- Determining Item Existence
Removing Context
Hidden Context
Events
- Dehydrating
- Hydrated

介绍

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

工作原理

理解 Laravel 上下文功能的最佳方式是使用内置日志记录功能来观察其实际运行情况。首先，你可以使用Facade 向上下文添加信息Context。在本例中，我们将使用中间件在每个传入请求时向上下文添加请求 URL 和唯一的跟踪 ID：

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6use Illuminate\Http\Request;
 7use Illuminate\Support\Facades\Context;
 8use Illuminate\Support\Str;
 9use Symfony\Component\HttpFoundation\Response;
10 
11class AddContext
12{
13    /**
14     * Handle an incoming request.
15     */
16    public function handle(Request $request, Closure $next): Response
17    {
18        Context::add('url', $request->url());
19        Context::add('trace_id', Str::uuid()->toString());
20 
21        return $next($request);
22    }
23}

<?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中。将上下文作为元数据附加，可以将传递给各个日志条目的信息与通过共享的信息区分开来。例如，假设我们写入以下日志条目：

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

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

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

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

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

添加到上下文的信息也会提供给调度到队列的作业。例如，假设我们ProcessPodcast在上下文中添加了一些信息后，将一个作业调度到队列：

1// In our middleware...
2Context::add('url', $request->url());
3Context::add('trace_id', Str::uuid()->toString());
4 
5// In our controller...
6ProcessPodcast::dispatch($podcast);

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

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

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

 1class ProcessPodcast implements ShouldQueue
 2{
 3    use Queueable;
 4 
 5    // ...
 6 
 7    /**
 8     * Execute the job.
 9     */
10    public function handle(): void
11    {
12        Log::info('Processing podcast.', [
13            'podcast_id' => $this->podcast->id,
14        ]);
15 
16        // ...
17    }
18}

class ProcessPodcast implements ShouldQueue
{
    use Queueable;

    // ...

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

        // ...
    }
}

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

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

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

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

捕捉上下文

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

1use Illuminate\Support\Facades\Context;
2 
3Context::add('key', 'value');

use Illuminate\Support\Facades\Context;

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

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

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

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

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

1Context::add('key', 'first');
2 
3Context::get('key');
4// "first"
5 
6Context::addIf('key', 'second');
7 
8Context::get('key');
9// "first"

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

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

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

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

Context 还提供了便捷的方法来增加或减少给定键的值。这两个方法都至少接受一个参数：要跟踪的键。第二个参数可以用于指定键应增加或减少的量：

1Context::increment('records_added');
2Context::increment('records_added', 5);
3 
4Context::decrement('records_added');
5Context::decrement('records_added', 5);

Context::increment('records_added');
Context::increment('records_added', 5);

Context::decrement('records_added');
Context::decrement('records_added', 5);

条件上下文

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

1use Illuminate\Support\Facades\Auth;
2use Illuminate\Support\Facades\Context;
3 
4Context::when(
5    Auth::user()->isAdmin(),
6    fn ($context) => $context->add('permissions', Auth::user()->permissions),
7    fn ($context) => $context->add('permissions', []),
8);

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

作用域上下文

该scope方法提供了一种在给定回调执行期间临时修改上下文的方法，并在回调执行完成后将上下文恢复到其原始状态。此外，您还可以在闭包执行期间传递应合并到上下文中的额外数据（作为第二和第三个参数）。

 1use Illuminate\Support\Facades\Context;
 2use Illuminate\Support\Facades\Log;
 3 
 4Context::add('trace_id', 'abc-999');
 5Context::addHidden('user_id', 123);
 6 
 7Context::scope(
 8    function () {
 9        Context::add('action', 'adding_friend');
10 
11        $userId = Context::getHidden('user_id');
12 
13        Log::debug("Adding user [{$userId}] to friends list.");
14        // Adding user [987] to friends list.  {"trace_id":"abc-999","user_name":"taylor_otwell","action":"adding_friend"}
15    },
16    data: ['user_name' => 'taylor_otwell'],
17    hidden: ['user_id' => 987],
18);
19 
20Context::all();
21// [
22//     'trace_id' => 'abc-999',
23// ]
24 
25Context::allHidden();
26// [
27//     'user_id' => 123,
28// ]

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

Context::add('trace_id', 'abc-999');
Context::addHidden('user_id', 123);

Context::scope(
    function () {
        Context::add('action', 'adding_friend');

        $userId = Context::getHidden('user_id');

        Log::debug("Adding user [{$userId}] to friends list.");
        // Adding user [987] to friends list.  {"trace_id":"abc-999","user_name":"taylor_otwell","action":"adding_friend"}
    },
    data: ['user_name' => 'taylor_otwell'],
    hidden: ['user_id' => 987],
);

Context::all();
// [
//     'trace_id' => 'abc-999',
// ]

Context::allHidden();
// [
//     'user_id' => 123,
// ]

如果在范围闭包内修改了上下文内的对象，则该改变将反映在范围之外。

堆栈

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

 1use Illuminate\Support\Facades\Context;
 2 
 3Context::push('breadcrumbs', 'first_value');
 4 
 5Context::push('breadcrumbs', 'second_value', 'third_value');
 6 
 7Context::get('breadcrumbs');
 8// [
 9//     'first_value',
10//     'second_value',
11//     'third_value',
12// ]

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 和持续时间捕获为元组：

1use Illuminate\Support\Facades\Context;
2use Illuminate\Support\Facades\DB;
3 
4// In AppServiceProvider.php...
5DB::listen(function ($event) {
6    Context::push('queries', [$event->time, $event->sql]);
7});

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

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

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

1if (Context::stackContains('breadcrumbs', 'first_value')) {
2    //
3}
4 
5if (Context::hiddenStackContains('secrets', 'first_value')) {
6    //
7}

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

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

and方法还接受闭包作为第二stackContains个hiddenStackContains参数，从而可以更好地控制值比较操作：

1use Illuminate\Support\Facades\Context;
2use Illuminate\Support\Str;
3 
4return Context::stackContains('breadcrumbs', function ($value) {
5    return Str::startsWith($value, 'query_');
6});

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

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

检索上下文

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

1use Illuminate\Support\Facades\Context;
2 
3$value = Context::get('key');

use Illuminate\Support\Facades\Context;

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

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

1$data = Context::only(['first_key', 'second_key']);
2 
3$data = Context::except(['first_key']);

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

$data = Context::except(['first_key']);

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

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

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

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

1Context::push('breadcrumbs', 'first_value', 'second_value');
2 
3Context::pop('breadcrumbs');
4// second_value
5 
6Context::get('breadcrumbs');
7// ['first_value']

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

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

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

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

1$data = Context::all();

$data = Context::all();

确定项目存在

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

1use Illuminate\Support\Facades\Context;
2 
3if (Context::has('key')) {
4    // ...
5}
6 
7if (Context::missing('key')) {
8    // ...
9}

use Illuminate\Support\Facades\Context;

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

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

无论存储的值是什么，该has方法都会返回true。例如，一个带有null值的键将被视为存在：

1Context::add('key', null);
2 
3Context::has('key');
4// true

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

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

删除上下文

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

1use Illuminate\Support\Facades\Context;
2 
3Context::add(['first_key' => 1, 'second_key' => 2]);
4 
5Context::forget('first_key');
6 
7Context::all();
8 
9// ['second_key' => 2]

use Illuminate\Support\Facades\Context;

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

Context::forget('first_key');

Context::all();

// ['second_key' => 2]

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

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

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

隐藏背景

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

1use Illuminate\Support\Facades\Context;
2 
3Context::addHidden('key', 'value');
4 
5Context::getHidden('key');
6// 'value'
7 
8Context::get('key');
9// null

use Illuminate\Support\Facades\Context;

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

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

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

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

 1Context::addHidden(/* ... */);
 2Context::addHiddenIf(/* ... */);
 3Context::pushHidden(/* ... */);
 4Context::getHidden(/* ... */);
 5Context::pullHidden(/* ... */);
 6Context::popHidden(/* ... */);
 7Context::onlyHidden(/* ... */);
 8Context::exceptHidden(/* ... */);
 9Context::allHidden(/* ... */);
10Context::hasHidden(/* ... */);
11Context::missingHidden(/* ... */);
12Context::forgetHidden(/* ... */);

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

Events

Context 调度两个事件，使您可以参与上下文的水合和脱水过程。

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

脱水

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

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

 1use Illuminate\Log\Context\Repository;
 2use Illuminate\Support\Facades\Config;
 3use Illuminate\Support\Facades\Context;
 4 
 5/**
 6 * Bootstrap any application services.
 7 */
 8public function boot(): void
 9{
10    Context::dehydrating(function (Repository $context) {
11        $context->addHidden('locale', Config::get('app.locale'));
12    });
13}

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

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

水合

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

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

 1use Illuminate\Log\Context\Repository;
 2use Illuminate\Support\Facades\Config;
 3use Illuminate\Support\Facades\Context;
 4 
 5/**
 6 * Bootstrap any application services.
 7 */
 8public function boot(): void
 9{
10    Context::hydrated(function (Repository $context) {
11        if ($context->hasHidden('locale')) {
12            Config::set('app.locale', $context->getHidden('locale'));
13        }
14    });
15}

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

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

Prologue

Getting Started

Architecture Concepts

The Basics

Digging Deeper

Security

Database

Eloquent ORM

Testing

Packages

Context

介绍

工作原理

捕捉上下文

条件上下文

作用域上下文

堆栈

检索上下文

确定项目存在

删除上下文

隐藏背景

Events

脱水

水合

本页内容