Исключения ядра и обработка ошибок

Документ описывает иерархию доменных исключений, карту HTTP-статусов, работу JsonErrorHandler и форматы ошибок API.

1. Иерархия исключений

Все доменные исключения находятся в core/domain/exception/.

graph TD
    DomainException --> BadRequestException
    DomainException --> ValidationException
    DomainException --> LogicException
    DomainException --> RuntimeException

    BadRequestException --> PermissionDeniedException
    BadRequestException --> EntityNotFoundException
    BadRequestException --> EntityAlreadyExistsException
    BadRequestException --> EntityUnavailableException
    BadRequestException --> InvalidCredentialsException
    BadRequestException --> EmailNotVerifiedException
    BadRequestException --> UserNotFoundException
    BadRequestException --> UserAlreadyExistsException
    BadRequestException --> IdentityNotFoundException
    BadRequestException --> IdentityAlreadyExistsException
    BadRequestException --> FileStorageException
    BadRequestException --> GoneException
    BadRequestException --> NotImplementedException

    IHttpException ~~~ BadRequestException  .- интерфейс с getStatusCode()

Базовые классы

Интерфейс IHttpException

interface IHttpException
{
    public function getStatusCode(): int;
}

Реализуется для маппинга на HTTP-статус (через JsonErrorHandler).

2. Карта HTTP-статусов

Важно: часть контроллеров не бросает исключения, а возвращает ErrorDto с кодом 200 (см. known-issues-and-roadmap). Фронтенду нужно проверять структуру error даже при HTTP 200.

3. JsonErrorHandler (формат ошибки)

Файл: core/infrastructure/handler/JsonErrorHandler.php

Переопределяет ErrorHandler Yii2 — все ошибки возвращаются единообразно в JSON.

Логика обработки

1. Определяется statusCode:
   • HttpException → $exception->statusCode
   • IHttpException → $exception->getStatusCode()
   • иначе → 500
2. Формируется ErrorDto (см. dto.md).
3. Если есть getErrors() или getDetails() — добавляются в error.details.
4. В dev-режиме (YII_DEBUG === true) добавляются отладочные данные:
   • DEBUG_LVL >= 1 → trace (массив { file, line, function, class, type, args? })
   • DEBUG_LVL >= 2 → request ({ method, url, headers, body } с редакцией секретов)
   • DEBUG_LVL = 3 → в trace добавляются args с редукцией (объекты → "Object(ClassName)", массивы → "Array(N)", строки → "[REDACTED]")
5. Ошибка логируется через Yii::error.
6. Ответ отправляется.

Redaction (редакция секретных данных)

Пример dev-ответа с ошибкой

{
  "error": {
    "code": 500,
    "message": "Undefined variable 'x'",
    "details": {
      "trace": [
        {
          "file": "/path/Handler.php",
          "line": 42,
          "function": "handle",
          "class": "SomeHandler",
          "type": "->"
        }
      ],
      "request": {
        "method": "POST",
        "url": "/api/task",
        "headers": {
          "content-type": ["application/json"],
          "authorization": "[REDACTED]"
        },
        "body": "{\"title\":\"...\",\"password\":\"[REDACTED]\"}"
      }
    }
  }
}

4. DEBUG_LVL уровни (переменная окружения)