Laravel Context

Overview Managing state across a Laravel application's lifecycle often feels fragmented once background processes enter the mix. The **Context** feature solves this by providing a unified way to store and retrieve information throughout a single request's execution, including any dispatched Jobs or commands. This is vital for maintaining trace IDs, user preferences, or localization settings without messy prop-drilling. Prerequisites To follow this guide, you should be comfortable with: * PHP 8.2+ and Laravel 11 syntax. * Middleware implementation. * The basics of Queues and Job dispatching. Key Libraries & Tools * **Laravel Context**: The core service for managing shared request data. * **Ray**: A specialized debugging tool for inspecting variables and logs in real-time. * **PHPStorm**: The IDE used for navigating the codebase and managing PHP environments. Code Walkthrough Setting Data in Middleware First, capture the user's preferred locale from the request headers and store it in the context. ```php namespace App\Http\Middleware; use Illuminate\Support\Facades\Context; use Closure; class AddContext { public function handle($request, Closure $next) { $locale = $request->getPreferredLanguage(['en', 'de']); Context::addHidden('locale', $locale); app()->setLocale($locale); return $next($request); } } ``` Using `addHidden` ensures this sensitive data doesn't clutter your standard log files while remaining accessible to the application. Automatic Hydration in Service Providers When a Job runs on a separate process, the application state resets. To persist the locale, use the `hydrated` hook in your `AppServiceProvider`. ```php use Illuminate\Support\Facades\Context; use Illuminate\Support\Facades\Config; public function boot(): void { Context::hydrated(function ($context) { if ($context->hasHidden('locale')) { app()->setLocale($context->getHidden('locale')); } }); } ``` This hook triggers automatically when a queued job starts, pulling the stored "hidden" locale from the context and applying it to the new process's configuration. Syntax Notes Laravel provides two primary methods for adding data: `Context::add()` and `Context::addHidden()`. The hidden variant is specifically designed for metadata you want to propagate to jobs but exclude from automatic logging. This distinction is a best practice for maintaining clean, readable logs. Practical Examples * **Multi-tenant Applications**: Store the `tenant_id` at the start of a request to ensure all downstream database queries and queued reports target the correct client. * **Distributed Tracing**: Generate a `trace_id` in a global middleware to link web requests to async jobs in your logging dashboard. Tips & Gotchas Avoid manually setting config values inside your Job's `handle()` method. While it works for that specific class, it won't affect secondary jobs or notifications dispatched from within that job. Always use the `Context::hydrated` hook to ensure the environment is correctly configured for the entire execution tree.