TUTORIAL: Como adicionar o Contexto da applicação ás excepções do Laravel

This post is also available in: English

Um dos aspectos mais importantes de qualquer aplicação é o correcto tratamento de excepções, quer seja para informar ao usuário sobre a excepção ocorrida, ou então para que os desenvolvedores possam dar seguimento á excepção posteriormente. O Laravel, o Framework PHP mais popular da actualidade, possui uma excelente capacidade de gestão de excepções, graças ao seu excepcion handling. Além disso, o Laravel já possuia um mecanismo de adicionar o contexto global da excepção ás mensagens de Logs geradas por elas. Por exemplo, se um usuário estiver autenticado no seu sistema, todas as excepções geradas por ele irão incluir o ID do usuário.

Também já era possivel adicionar mais informações do contexto global da aplicação ás excepções do Laravel, adicionando a seguinte função a sua classe App\Exceptions\Handler:

//app/Exceptions/Handler.php
protected function context()
{
    return array_merge(parent::context(), [
        'foo' => 'bar',
    ]);
}

Agora, desde a versão 8.30.0 do Laravel que foi recentemente lançada, é possivel ainda adicionar informações de contexto específicas a cada uma das excepções do Framework. Por exemplo, se tivermos uma classe Estudante, que gera uma excepção do tipo EstudanteReprovadoException, é possivel adicionar informações sobre o ID do estudante, o seu nome, a nota de reprovação, etc, que serão incluidas na mensagem de Log da excepção.

Para adicionar tasi informações ao contexto da Excepção no Laravel, basta adicionar o método context a respectiva excepção. Este método deverá retornar um array contendo todas as informações que desejamos que seja incluida ao contexto da excepção no seu log:

<php

namespace App\Exceptions;

use Exception;

class EstudanteReprovado extends Exception
{
    // ...

    public function context(): array
    {
        return [
            'estudante_id' => $this->estudanteId,
            'nota_reprovacao' => $this->nota
        ];
    }
}

Note que ferramentas de gestão de erros e logs como o Sentry já possuiam essa funcionalidade, mas agora sendo nativa do Framework torna-se muito mais pratica a sua aplicação em qualquer ferramenta de gestão de logs que o seu sistema estiver a usar.

Lembrar que para usar esta funcionalidade, terá de actualizar o seu projecto/sistema para a versão 8.30.0 do Laravel ou superior