Implementar mensagem de erro com orientação de tamanho do limite do arquivo para upload

[pauloregis-sanoliver]

Contexto

Atualmente, quando um usuário tenta realizar o upload de um arquivo cujo tamanho excede as diretivas configuradas no PHP (upload_max_filesize e post_max_size) ou nos limites da aplicação, a requisição pode falhar abruptamente com erros genéricos (ex: PostTooLargeException do Laravel ou erro 413/422/500), sem uma mensagem clara e orientativa para o usuário final.

Precisamos padronizar o tratamento desse erro integrando-o à nossa hierarquia de exceções (AppException), capturando a tentativa de upload acima do limite e retornando uma mensagem amigável com indicação do limite máximo permitido, tanto em requisições Web (Inertia/Sessão) quanto em requisições JSON/API.

---

Objetivo

• Como usuário do sistema
• Quero receber uma mensagem de erro clara informando o tamanho máximo permitido ao tentar enviar um arquivo maior que o limite configurado
• Para que eu compreenda o motivo da falha e possa redimensionar ou escolher um arquivo dentro das especificações suportadas.

---

Estrutura Arquitetural

Hierarquia de Classes (PlantUML)

@startuml
abstract class AppException {
    + getHttpStatus(): int
    + context(): array
    + shouldReport(): bool
}

package "App\\Exceptions\\Domain" {
    class FileUploadExceededException {
        + __construct(string $userMessage, int $maxBytes, int $httpStatus = 413)
        + getMaxBytes(): int
    }
}

AppException <|-- FileUploadExceededException
@enduml

---

Escopo

• Criar a exceção de domínio FileUploadExceededException herdando de AppException (com status HTTP 413 ou 422 e contexto com limites).
• Interceptar no bootstrap/app.php (ou middleware específico) a exceção Illuminate\Http\Exceptions\PostTooLargeException e erros de validação nativos de upload do PHP (UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE).
• Converter a falha para FileUploadExceededException com mensagem amigável informando o limite configurado (ex: "O arquivo enviado excede o limite máximo permitido de 10MB.").
• Garantir o retorno apropriado para requisições JSON/API (HTTP 413 Payload Too Large ou 422 com payload padronizado) e para requisições Inertia/Web (redirecionamento com mensagem de erro no flash/bag de validação).
• Adicionar testes automatizados de Feature para validar a interceptação e formatação da mensagem de erro.

---

Fora de Escopo

• Alterar as configurações globais de php.ini ou de infraestrutura (Nginx client_max_body_size).
• Implementar upload multipart/chunked em partes assíncronas.

---

Critérios de Aceitação

• Critério 1: Upload via Web/Inertia excedendo o limite do PHP

  Cenário: Tentativa de upload de arquivo acima do limite do PHP em formulário Web
    Dado que o limite configurado de upload é de "10MB"
    E o usuário está em uma tela com envio de arquivo (ex: Formalização ou Prestação de Contas)
    Quando o usuário submeter um arquivo com tamanho superior a "10MB"
    Então o sistema deve interceptar o erro de estouro de limite
    E deve retornar para a tela anterior mantendo o estado
    E deve exibir uma mensagem clara informando: "O arquivo enviado excede o limite máximo permitido de 10MB."

• Critério 2: Upload via API / Requisição JSON excedendo o limite

  Cenário: Tentativa de upload via API com payload acima do limite
    Dado que o limite configurado de upload é de "10MB"
    Quando uma requisição JSON/Multipart for enviada com arquivo superior a "10MB"
    Então o sistema deve responder com status HTTP 413 (Payload Too Large) ou 422 (Unprocessable Entity)
    E o corpo da resposta deve conter a mensagem informativa e o código da exceção "FileUploadExceededException"

• Critério 3: Conformidade com a hierarquia AppException

  Cenário: Estrutura da exceção integrada ao AppException
    Dado que ocorre uma falha de tamanho de upload
    Quando a exceção "FileUploadExceededException" for disparada
    Então ela deve herdar de "AppException"
    E deve conter no contexto os dados do limite configurado e tamanho recebido
    E deve ser tratada pelo handler global em "bootstrap/app.php"

• Critério 4: Upload de arquivo dentro do limite permitido

  Cenário: Upload bem-sucedido com arquivo de tamanho válido
    Dado que o limite configurado de upload é de "10MB"
    Quando o usuário submeter um arquivo com tamanho de "5MB"
    Então o upload deve ser processado normalmente sem disparar a exceção de limite

---

Observações

• Para formatar a mensagem de forma dinâmica, pode-se ler as diretivas ini_get('upload_max_filesize') ou ini_get('post_max_size') e converter para unidade legível (ex: MB/KB).
• Atenção ao tratamento da Illuminate\Http\Exceptions\PostTooLargeException, que é disparada pelo middleware ValidatePostSize do Laravel antes mesmo de chegar nos FormRequests.