Управление ошибками

В MODX для ошибок 401 (Unauthorized), 403 (Forbidden), 404 (Page Not Found) и 503 (Service Unavailable) предусмотрены отдельные страницы. Если вдруг в процессе возникнут другие ошибки, то у MODX на этот счёт предусмотрены статические файлы, которые находятся в папке /core/error/.

В ZoomX список ошибок значительно больше. Вот их полный список:

400 – Bad Request. Вызывается пользователем.
401 – Unauthorized. Системный.
403 – Forbidden. Системный.
404 – Not Found. Системный.
405 – Method Not Allowed. Системный.
406 – Not Acceptable. Вызывается пользователем.
415 – Unsupported Media Type. Вызывается пользователем.
500 – Internal Server Error. Системный.
503 – Service Unavailable. Системный.

Этот список можно расширять самостоятельно с помощью исключений.

Важно помнить, что в режимах "Отключён" и "Смешанный" (в случае, когда роут для текущего ресурса не определён), ошибками занимается MODX. Он или переадресует на указанную в соответствующей системной настройке ("error_page", "unauthorized_page" или "site_unavailable_page") страницу ошибки, или выводит статическую страницу ошибки из директории core/error/.

В строгом режиме, а также в смешанном (когда роут для указанного URI определён), но ресурса с таким URI нет, или сгенерирована ошибка (об этом дальше), ZoomX выведет собственную страницу ошибки на основе шаблона error.tpl.

Шаблоны ошибок

Для вывода ошибок в компонент добавлен универсальный шаблон error.tpl. Если необходим уникальный шаблон для какой-то ошибки, то нужно создать файл, в названии которого указан код ошибки. Т.е. для ошибки 401 файл шаблона должен называться 401.tpl. Это шаблон подхватится автоматически для данной ошибки.

Исключения

В ZoomX все ошибки работают на основе исключений. Из коробки идут 9 Http исключений – одно базовое, остальные его потомки. Найти их можно в папке компонента core/components/zoomx/src/Exceptions/. Это системные исключения. Их изменять нельзя. Но вы можете легко создавать свои по аналогии и даже подменять системные. Для этого есть специальный файл конфига, который находится в core/config/.

<?php

return [
    // Подменяет системное исключения для ошибки 404.
    404 => Zoomx\Exceptions\MyNotFoundHttpException::class,
    // Добавляет исключение для кастомной ошибки "4041 Пользователь не найден".
    4041 => Zoomx\Exceptions\UserNotFoundHttpException::class, 
];

После этого вы можете использовать эти исключения в роутах.

$router->get('users/{id:\d+}', function(int $id) use ($modx) {
    if (!$user = $modx->getObject('modUser', ['id' => $id])) {
        abortx(4041); // Выведется страница ошибки error.tpl, если нет шаблона 4041.tpl   
    }
    return viewx('profile.tpl', $user);
});

Из исключения в шаблон передаются следующие данные:

$e – DTO объект ошибки. Он содержит всю информацию об ошибке. Пример использования можно посмотреть в шаблоне error.tpl.
$type – тип ошибки - "error" или "exception".

Для того, чтобы изменить текст или заголовок сообщения не обязательно создавать своё исключение. Достаточно передать эти данные в параметрах хелпера abortx() для системного исключения.

$router->get('users/{id:\d+}', function(int $id) use ($modx) {
    if (!$user = $modx->getObject('modUser', ['id' => $id])) {
        abortx(404, 'Текст сообщения об ошибке', 'Заголовок'); // Используется системное исключение 404.   
    }
    return viewx('profile.tpl', $user);
});

Исключения можно использовать как в обычных роутах, так и в роутах для API запросов. И даже, если уж очень надо, вне роутов.

// routes.php

if (какое-то условие && пользователь не админ) {
   abortx(503);  // Отключаем сайт
}

// Определения роутов
...

Событие OnRequestError

В MODX есть всего 2 события для ошибок (OnPageNotFound и OnPageUnauthorized). Их явно не хватает для других ошибок. Поэтому ZoomX добавляет общее событие для всех остальных ошибок "OnRequestError".