Excecoes

Namespace: local_middag\framework\exception.

---

Hierarquia

Classe	Extends	HTTP	Uso
middag_exception	RuntimeException	500	Classe abstrata raiz. Catch generico: catch (middag_exception $e)
middag_domain_exception	middag_exception	400	Regra de negocio violada, invariante quebrado
middag_validation_exception	middag_domain_exception	422	Input inválido com mapa de erros por campo
middag_not_found_exception	middag_domain_exception	404	Recurso ou registro não encontrado
middag_authentication_exception	middag_exception	401	Usuário não identificado — token inválido/expirado, sessão ausente, guest
middag_authorization_exception	middag_exception	403	Sem capability, API desabilitada, sesskey inválido
middag_infrastructure_exception	middag_exception	500	Falha de infra (DB, rede, filesystem, serviço externo)
middag_persistence_exception	middag_infrastructure_exception	500	Falha específica de persistência/storage
middag_lifecycle_violation_exception	middag_exception	500	Violacao de fase do container (@internal)

RuntimeException
 └── middag_exception (abstract)           500
      ├── middag_domain_exception           400
      │    ├── middag_validation_exception   422
      │    └── middag_not_found_exception    404
      ├── middag_authentication_exception    401
      ├── middag_authorization_exception     403
      ├── middag_infrastructure_exception    500
      │    └── middag_persistence_exception  500
      └── middag_lifecycle_violation_exception  500  @internal

---

Quem pode lancar o que

Camada	Excecoes permitidas
domain/	middag_domain_exception, middag_validation_exception, middag_not_found_exception
infrastructure/	middag_infrastructure_exception, middag_persistence_exception
extensions/	middag_domain_exception, middag_validation_exception, middag_not_found_exception, middag_authorization_exception
kernel/	middag_lifecycle_violation_exception (exclusivo), middag_authentication_exception e middag_authorization_exception (camada HTTP do kernel)

Extensions nunca lancam middag_infrastructure_exception ou middag_persistence_exception diretamente. Essas exceções são responsabilidade da camada de infraestrutura.

---

validation_exception

Carrega um mapa estruturado de erros por campo.

Construtor

new middag_validation_exception(
    message: 'Validation failed',
    errors: ['field' => 'message'],
);

Exemplo

throw new middag_validation_exception(
    message: 'Dados invalidos',
    errors: [
        'name'  => 'O campo name é obrigatório.',
        'email' => 'Formato de email inválido.',
    ],
);

Acesso aos erros

try {
    $request->validate();
} catch (middag_validation_exception $e) {
    $errors = $e->errors();    // ['field' => 'message', ...]
    $code   = $e->getStatusCode(); // 422
}

---

Regra de wrapping

Excecoes nativas do PHP ou do Moodle (dml_exception, moodle_exception, \InvalidArgumentException, etc.) devem ser encapsuladas antes de cruzar a fronteira da camada. Use o parametro previous: para preservar o erro original.

try {
    $DB->insert_record('middag_items', $record);
} catch (\dml_exception $e) {
    throw new middag_persistence_exception(
        message: 'Failed to persist item',
        previous: $e,
    );
}

---

lifecycle_violation_exception

Marcada @internal. Lancada exclusivamente pelo kernel quando código tenta uma operação fora da fase permitida (ex: registrar service apos boot).

Extensions nunca lancam esta exceção. Extensions nunca fazem catch desta exceção — ela indica erro de programacao.

---

Conversao HTTP

Toda exceção middag_exception expoe getStatusCode(): int. O kernel usa esse método para converter exceções em respostas HTTP automaticamente.

$e->getStatusCode(); // 400, 401, 403, 404, 422, 500

Distinção 401 vs 403

• 401 middag_authentication_exception — usuário desconhecido: token ausente/inválido/expirado, sem sessão ativa, guest. A identidade não foi estabelecida.
• 403 middag_authorization_exception — usuário identificado mas sem permissão: capability ausente, API desabilitada, sesskey inválido.