Controlando o Truncamento de Exceções de Requisição no Laravel

No desenvolvimento de aplicações web modernas, especialmente aquelas que consomem APIs externas, lidar com erros de forma eficiente é crucial. O Laravel, por padrão, trunca mensagens de exceção de requisição para evitar a sobrecarga dos logs. No entanto, isso pode ocultar informações valiosas para depuração. Felizmente, o Laravel oferece controles flexíveis para ajustar esse comportamento tanto globalmente quanto por requisição.

Entendendo o Comportamento Padrão

Por padrão, o Laravel trunca mensagens de RequestException para 120 caracteres ao registrar ou reportar erros. Isso evita que respostas massivas de erro de APIs inundem seus logs, mas pode esconder detalhes importantes necessários para a depuração.

// Isso pode ser truncado para apenas os primeiros 120 caracteres
HTTP request returned status code 422:
{"errors":{"email":["The email has already been taken."],"password":["The password must be at least 8 characters."],"phone":["The phone format is invalid."]}} // ... (truncated)

Configurando o Comportamento de Truncamento Globalmente

Você pode personalizar esse comportamento globalmente no arquivo bootstrap/app.php usando os novos métodos de truncamento:

use Illuminate\Foundation\Configuration\Exceptions;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        // Aumentar o limite de truncamento para 240 caracteres
        $exceptions->truncateRequestExceptionsAt(240);
        
        // Ou desabilitar o truncamento completamente
        $exceptions->dontTruncateRequestExceptions();
    })
    ->create();

Exemplo Prático

Considere um aplicativo de e-commerce que integra com múltiplos provedores de pagamento e sistemas de inventário. Diferentes APIs retornam níveis variados de detalhe em suas respostas de erro, e você precisa de estratégias de truncamento diferentes baseadas na criticidade da operação.

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class PaymentService
{
    public function processPayment(array $paymentData): array
    {
        try {
            $response = Http::truncateExceptionsAt(500)
                ->timeout(30)
                ->post('https://api.payment-provider.com/charge', $paymentData);

            return $response->json();
            
        } catch (RequestException $e) {
            // Detalhes completos do erro preservados para depuração de pagamento
            Log::error('Payment processing failed', [
                'payment_data' => $paymentData,
                'error' => $e->getMessage(), // Até 500 caracteres
                'response_body' => $e->response?->body()
            ]);
            
            throw $e;
        }
    }
}

Este controle granular é especialmente valioso em arquiteturas de microsserviços onde diferentes serviços têm padrões variados de resposta de erro, ou ao lidar com APIs de terceiros que retornam erros de validação detalhados que você precisa preservar para depuração.

Os métodos de truncamento por requisição (truncateExceptionsAt() e withoutTruncatingExceptions()) dão a você controle cirúrgico sobre a visibilidade do erro sem afetar sua estratégia global de logging. Você pode manter a maioria das operações usando o truncamento padrão enquanto expande os limites apenas onde você precisa de informações detalhadas de erro.