Laravel Context

Tempo de leitura: 4 minutos

O Laravel Context é um recurso relativamente novo que oferece um mecanismo poderoso para capturar, armazenar e propagar informações contextuais durante o ciclo de vida de uma requisição HTTP ou Job. Seu principal objetivo é enriquecer os logs da aplicação com metadados relevantes, tornando a depuração, análise de logs e o rastreamento de requisições muito mais eficientes.

1. ❓ O Que É e Por Que Usar o Context?

O Context atua como um armazenamento temporário de dados vinculados ao fluxo de execução atual. Ele resolve o problema de ter que passar manualmente dados como user_id ou request_id para todas as funções que geram logs.

Vantagens

Rastreabilidade (Traceability): Ao adicionar um ID de requisição (request_id) ao contexto, todos os logs gerados durante essa requisição (incluindo Jobs disparados) carregarão esse ID, permitindo rastrear o fluxo completo.
Depuração Aprimorada: Logs se tornam significativamente mais úteis ao incluir informações essenciais (ex: ID do usuário, URL, método).
Log Limpo: Mantém as chamadas de log concisas (Log::error('Falha de conexão')) enquanto o contexto injeta os metadados automaticamente.

2. 📝 Adicionando e Acessando Informações

A Facade Context é a interface principal para interagir com o sistema.

A. Adicionando Dados ao Contexto

Use o método add() para injetar um par chave-valor no contexto atual.

PHP

use Illuminate\Support\Facades\Context;

// Adiciona dados relevantes no início da requisição (ex: em um Middleware)
Context::add('user_id', auth()->id());
Context::add('request_url', request()->url());

B. Logs Automáticos

Quando você dispara um log, o Laravel automaticamente anexa os dados presentes no contexto como metadados no arquivo de log.

PHP

use Illuminate\Support\Facades\Log;

// O Log::info será enriquecido com 'user_id' e 'request_url'
Log::info('Tentativa de acesso a recurso protegido.');

C. Recuperando Informações

Você pode recuperar dados que foram armazenados no contexto em qualquer ponto da requisição:

PHP

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

3. 🧩 Stacks, Remoção e Ocultação

A. Stacks (Agrupamento)

O Context permite o uso de Stacks para agrupar informações relacionadas, evitando colisões de chaves e organizando a informação.

PHP

// Cria uma stack chamada 'user'
Context::stack('user')->add('name', auth()->user()->name);

// O dado 'name' agora reside dentro da stack 'user'
Log::info('Nome do usuário registrado.');

B. Remoção e Ocultação

O Context deve ser limpo ao final da requisição (geralmente tratado automaticamente). Você pode manipular chaves específicas:

Método	Função	Exemplo
`remove(key)`	Remove a chave permanentemente do contexto atual.	`Context::remove('sensitive_data');`
`add(key, value, true)`	O terceiro argumento (`true`) marca a informação como oculta (`hidden`).	`Context::add('password', 'minha_senha', true);`

Observação: Dados ocultos são omitidos dos logs, mas permanecem no contexto e podem ser acessados via Context::get('password').

4. 🔗 Propagação para Jobs (Filas)

Um dos recursos mais valiosos é a propagação automática do contexto para Jobs que são disparados durante a requisição.

Quando você usa dispatch(new MyJob()), o Laravel serializa o contexto atual e o inclui no Job. Quando o Worker processa o Job em segundo plano, ele hidrata o contexto.

Dehydrating e Hydrating (Serialização)

Os métodos dehydrate() e hydrate() facilitam a persistência do contexto em sistemas externos (como um banco de dados) ou a sua transmissão via filas.

Desidratar (Converter para Array):PHP// Captura o contexto atual para um array serializável $contextData = Context::dehydrate();
Hidratar (Restaurar de Array):PHP// Restaura o contexto em outro processo (ex: no Worker) Context::hydrate($contextData);

✅ Conclusão Laravel Context

Laravel Context: O Context é uma ferramenta moderna e poderosa para instrumentação e observabilidade no Laravel. Ao utilizá-lo para injetar informações cruciais (como IDs de rastreamento e detalhes do usuário) e aproveitar sua propagação automática para Logs, Exceções e Jobs, você transforma logs básicos em registros detalhados e rastreáveis, otimizando drasticamente o tempo gasto em depuração.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: