Context - Knowledge of Laravel

What is Context

Laravel’s Context feature is a mechanism for recording and sharing information across requests, queue jobs, and command executions. When you add information through the Illuminate\Support\Facades\Context facade, that information is automatically attached to every log entry your application writes. This lets you clearly distinguish between data passed to individual log calls and shared information held by Context. It’s especially useful for tracing in distributed systems or queue-based architectures.

Context propagation flow

Basic usage

The most typical usage is to set a trace_id in middleware. It will automatically be included in every subsequent log entry.

Create the middleware

php artisan make:middleware AddContext

Add a trace ID to Context

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

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\AddContext::class);
})

After this setup, logs written from your controllers and services will automatically be tagged with url and trace_id.

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

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

Writing to context

add — add a value

use Illuminate\Support\Facades\Context;

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

// Add several at once
Context::add([
    'first_key'  => 'value',
    'second_key' => 'value',
]);

add overwrites existing keys. Use addIf to add only when the key does not already exist.

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

Context::get('key');
// "first" — not overwritten

increment / decrement — manage counters

Dedicated methods for incrementing or decrementing numbers. Specify the change amount as the second argument.

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

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

when — add conditionally

The when method lets you add different data depending on whether a condition is true or 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', []),
);

push — add to a stack

Context supports “stacks” that hold list-style data. Using push, values are appended in the order they are added.

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

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

Here’s an example of recording query execution history on a stack:

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

// Register in the boot method of AppServiceProvider.php
DB::listen(function ($event) {
    Context::push('queries', [$event->time, $event->sql]);
});

Retrieving context

get / all

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

// Retrieve everything
$data = Context::all();

only / except — retrieve a subset

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

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

pull / pop — retrieve and remove

pull retrieves a key’s value and removes it from the context at the same time.

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

To pop the last value off a stack, use pop.

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

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

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

remember — set and return if missing

$permissions = Context::remember(
    'user-permissions',
    fn () => $user->permissions,
);

has / missing — check whether a key exists

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

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

has returns true even if null is stored. It only checks whether the key is registered.

Removing context

Use forget to remove keys.

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

Context::forget('first_key');

Context::all();
// ['second_key' => 2]

// Remove multiple at once
Context::forget(['first_key', 'second_key']);

Scoped context

The scope method lets you temporarily change context only while a closure runs, and automatically restores the previous state afterward. It’s useful for testing or when you want to include temporary additional information in logs for a specific local operation.

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

// After the scope ends, values return to what they were
Context::all();
// ['trace_id' => 'abc-999']

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

If you modify an object inside the scope, that change is reflected outside the scope as well. There’s no problem with primitive values.

Hidden Context

Data you don’t want to appear in logs (passwords, API keys, PII, etc.) should be stored in Hidden Context. It cannot be retrieved via the ordinary get method—only via dedicated methods like getHidden.

use Illuminate\Support\Facades\Context;

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

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

Context::get('key');
// null — not retrievable via ordinary get

Hidden Context has the same set of methods as regular context.

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

Propagating to queue jobs

When you dispatch a job to a queue, the current context is automatically serialized into the job’s payload. When the job runs, the original context is restored, so the trace_id you attached during the request automatically flows through to queue-side logs.

// Set in middleware
Context::add('trace_id', Str::uuid()->toString());

// Dispatch the job in the controller
ProcessPodcast::dispatch($podcast);

class ProcessPodcast implements ShouldQueue
{
    use Queueable;

    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"}

You can see that the request-time trace_id also appears in the queue-side log.

Dehydrating — customize on job send

Use Context::dehydrating to transform the context immediately before a job is sent. For example, use it when you want to pass the locale determined by the Accept-Language header to the queue.

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

Inside a dehydrating callback, do not use the Context facade; only operate on the $context repository passed to the callback. Using the facade would modify the current process’s context.

Hydrated — restore on job execution

Use Context::hydrated to add processing right when the context is restored just before a job runs. For example, apply a saved locale to your configuration.

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

Inside a hydrated callback, do not use the Context facade either; only operate on the $context repository passed in.

Summary

Context vs Log::withContext

	`Context`	`Log::withContext`
Scope	All log channels	Specific channels only
Propagation to queue jobs	Automatic (Dehydrate/Hydrate)	None
Hidden data	Supported	None
Purpose	Tracing, distributed systems	Channel-specific metadata

Data that belongs in Hidden Context

Because Hidden Context is not written to logs, you can safely store the following types of data:

Session IDs or user IDs (when you don’t want them in logs)
API keys or authentication tokens
Locales or configuration values (that you want to propagate to queues but not log)
Internal flags or state

Common Dehydrate/Hydrate use patterns

Propagating locale: Save app.locale into Hidden Context in dehydrating, then Config::set in hydrated to restore.
Propagating authentication info: Make the authenticated user’s information from the request available inside queue jobs.
Tenant ID: In multi-tenant applications, share the tenant identifier across queues.

​What is Context

​Context propagation flow

​Basic usage

​Writing to context

​add — add a value

​increment / decrement — manage counters

​when — add conditionally

​push — add to a stack

​Retrieving context

​get / all

​only / except — retrieve a subset

​pull / pop — retrieve and remove

​remember — set and return if missing

​has / missing — check whether a key exists

​Removing context

​Scoped context

​Hidden Context

​Propagating to queue jobs

​Dehydrating — customize on job send

​Hydrated — restore on job execution

​Summary

What is Context

Context propagation flow

Basic usage

Writing to context

add — add a value

increment / decrement — manage counters

when — add conditionally

push — add to a stack

Retrieving context

get / all

only / except — retrieve a subset

pull / pop — retrieve and remove

remember — set and return if missing

has / missing — check whether a key exists

Removing context

Scoped context

Hidden Context

Propagating to queue jobs

Dehydrating — customize on job send

Hydrated — restore on job execution

Summary