Функция cot_die_message в Cotonti

Назначение функции и ее применени в Cotonti

Функция cot_die_message в Cotonti предназначена для завершения выполнения скрипта и отображения страницы с сообщением пользователю. Её цель — обработка критических ошибок или ситуаций, когда дальнейшее выполнение кода невозможно или нецелесообразно.

Она:

Отправляет соответствующий HTTP-заголовок: Функция определяет статус ответа на основе кода сообщения и отправляет соответствующий заголовок. Например, для кода 404 отправляется заголовок "404 Not Found".

Отображает сообщение пользователю: Функция выводит пользовательский интерфейс с сообщением об ошибке. Это может быть сообщение об ошибке, предупреждение или информационное сообщение.

Опционально перенаправляет пользователя: Если указан параметр $redirect, функция добавляет мета-тег для автоматического перенаправления пользователя через 3 секунды на указанный URL.

Использует шаблоны для отображения: Функция ищет и использует шаблоны для рендеринга страницы с сообщением, что позволяет разработчикам кастомизировать вид этих страниц.

Функция cot_die_message обычно вызывается в случаях, когда необходимо уведомить пользователя о критической ошибке, например, если ресурс не найден (404), доступ запрещён (403), или произошла внутренняя ошибка сервера (500).

Код функции cot_die_message:

function cot_die_message($code, $header = true, $message_title = '', $message_body = '', $redirect = '')
{
    // Globals and requirements
    // cot class can be not initialised yet
    global $error_string, $out, $L, $R, $cfg;

    // Загружаем языковой файл для сообщений
    $LL = is_array($L) ? $L : array();
    require_once cot_langfile('message', 'core');
    // Объединяем языковые файлы
    $L = array_merge($L, $LL);

    // Если произошла ошибка и запрос был POST, сохраняем данные из формы
    if (cot_error_found() && $_SERVER['REQUEST_METHOD'] === 'POST') {
        // Сохраняем данные POST-запроса
        cot_import_buffer_save();
        // Если есть ошибки, выводим их
        if (!empty($error_string)) {
            // Ошибки не должны исчезать
            cot_error($error_string);
        }
    }

    // Массив, который содержит статус ответа для разных кодов
    static $msg_status = [
        100 => '403 Forbidden',
        101 => '200 OK',
        102 => '200 OK',
        105 => '200 OK',
        106 => '200 OK',
        109 => '200 OK',
        117 => '403 Forbidden',
        118 => '200 OK',
        151 => '403 Forbidden',
        152 => '403 Forbidden',
        153 => '403 Forbidden',
        157 => '403 Forbidden',
        300 => '200 OK',
        400 => '400 Bad Request',
        401 => '401 Authorization Required',
        403 => '403 Forbidden',
        404 => '404 Not Found',
        500 => '500 Internal Server Error',
        503 => '503 Service Unavailable',
        602 => '403 Forbidden',
        603 => '403 Forbidden',
        900 => '503 Service Unavailable',
        904 => '403 Forbidden',
        911 => '404 Not Found',
        915 => '200 OK',
        916 => '200 OK',
        920 => '200 OK',
        930 => '403 Forbidden',
        940 => '403 Forbidden',
        950 => '403 Forbidden',
        951 => '503 Service Unavailable',
    ];

    // Устанавливаем тип контента, если он не был установлен
    if (empty($out['contentType'])) {
        $out['contentType'] = 'text/html';
    }
    // Если код сообщения есть в массиве статусов, отправляем соответствующий HTTP заголовок
    if (isset($msg_status[$code])) {
        cot_sendheaders($out['contentType'], $msg_status[$code]);
    }

    // Определяем заголовок и тело сообщения
    $title = empty($message_title) ? $L['msg' . $code . '_title'] : $message_title;
    $body = empty($message_body) ? $L['msg' . $code . '_body'] : $message_body;

    // Определяем путь к шаблону сообщения
    $tpl_type = defined('COT_ADMIN') ? 'core' : 'module';
    $tpl_path = '';
    // Получаем путь к файлу схемы (стили)
    $schemeFile = cot_schemeFile();
    $stylesheet = $schemeFile && file_exists($schemeFile)
        ? '<link rel="stylesheet" type="text/css" href="' . $schemeFile . '"/>'
        : '';
    $redirect_meta = '';
    // Если URL для редиректа указан, создаём мета-тег для автоматического перенаправления через 3 секунды
    if (!empty($redirect)) {
        if (cot_url_check($redirect)) {
            $redirect_meta = '<meta http-equiv="refresh" content="3; url='.$redirect.'" />';
        }
    }

    // Если не загружены ресурсы, загружаем их
    if (!isset($R['code_basehref'])) {
        // Ресурсные строки
        include $cfg['system_dir'].'/resources.rc.php';
    }

    // Если нужно отобразить заголовок страницы
    if ($header) {
        $tpl_path = cot_tplfile("error.$code", $tpl_type);
        if ($tpl_path) {
            $header = false;
        } else {
            // Если шаблон не найден, выводим стандартный заголовок
            echo '<html><head><title>'.$title.'</title><meta name="robots" content="noindex" />'.$R['code_basehref'].$stylesheet.$redirect_meta.'</head><body><div class="block">';
        }
    }

    // Если не найден путь к шаблону, используем шаблон сообщения
    if (empty($tpl_path)) {
        $tpl_path = cot_tplfile('message', $tpl_type);
    }

    // Если шаблон не найден, выводим сообщение прямо в HTML
    if (empty($tpl_path) || !file_exists($tpl_path)) {
        echo $body;
    } else {
        // Если шаблон найден, создаём объект шаблонизатора XTemplate
        $t = new XTemplate($tpl_path);

        // Присваиваем переменные шаблона
        $t->assign(array(
            'AJAX_MODE' => defined('COT_AJAX') && COT_AJAX,
            'MESSAGE_BASEHREF' => $R['code_basehref'],
            'MESSAGE_STYLESHEET' => $stylesheet,
            'MESSAGE_REDIRECT' => $redirect_meta,
            'MESSAGE_TITLE' => $title,
            'MESSAGE_BODY' => $body
        ));

        // Парсим и выводим содержимое шаблона
        $t->parse('MAIN');
        $t->out('MAIN');
    }

    // Если нужно было вывести заголовок, закрываем HTML
    if ($header) {
        echo '</div></body></html>';
    }

    /* === Hook === */
    // Вызов плагинов, если они существуют
    foreach (cot_getextplugins('die.message') as $pl)
    {
        include $pl;
    }
    /* ===== */

    // Завершаем выполнение скрипта
    exit;
}

Пошаговое объяснение php-функции в cot_die_message Cotonti.

Глобальные переменные:

В первой строке функции используются глобальные переменные: $error_string, $out, $L, $R, $cfg. Эти переменные содержат конфигурацию сайта, языковые строки, данные об ошибках и другие системные параметры.

Загрузка языкового файла:

require_once cot_langfile('message', 'core'); — загружается языковой файл для сообщений, чтобы получить переводы текста для различных сообщений (например, ошибки, информация).

Проверка на ошибки при POST-запросах:

Если есть ошибки и запрос был сделан методом POST, данные формы сохраняются, чтобы избежать их потери при перезагрузке страницы.

Массив статусов сообщений:

Здесь определен массив $msg_status, который сопоставляет коды ошибок HTTP (например, 404, 500, 403) с их текстовыми значениями. Это нужно для отправки правильных заголовков HTTP-ответа.

Отправка заголовков HTTP-ответа:

В зависимости от переданного кода $code, функция отправляет нужный HTTP-статус (например, "404 Not Found" или "500 Internal Server Error").

Определение заголовка и тела сообщения:

Если параметры $message_title или $message_body не заданы, они будут заменены значениями, полученными из языкового файла, например, для кода ошибки 404 будет использовано сообщение "Страница не найдена".

Генерация CSS и редиректа:

Если задан редирект, создается HTML мета-тег для перенаправления через 3 секунды.

Загрузка ресурсов:

Загружается файл с ресурсами (например, стили и другие зависимости), если он ещё не был загружен.

Генерация HTML-страницы с сообщением:

Если задан параметр $header = true, создается стандартная HTML-страница с заголовком, который может быть изменен в зависимости от кода ошибки.
Для отображения сообщения используется шаблон, который может быть настроен для каждого кода ошибки.

Парсинг и вывод шаблона:

В случае успешной загрузки шаблона сообщения данные передаются в шаблон и выводятся на страницу.

Вызов плагинов через хуки:

Функция вызывает дополнительные плагины (если они существуют) для обработки сообщений перед выводом.
Завершение выполнения:
В конце работы функции выполнение скрипта останавливается с помощью команды exit, чтобы пользователь не видел дальнейшие ошибки или нежелательное поведение.

 

Функция cot_die_message принимает следующие параметры:

/**
 * Terminates script execution and displays message page
 *
 * @param int $code Message code
 * @param bool $header Render page header
 * @param string $message_title Custom page title
 * @param string $message_body Custom message body
 * @param string $redirect Optional URL to redirect after 3 seconds
 */

1. Код сообщения $code (int)

Описание: Это код сообщения, который определяет тип ошибки или состояния, которое должно быть отображено пользователю.
Назначение: Код используется для отправки соответствующего HTTP-статуса ответа и выбора нужного текстового сообщения.
Пример значений:
404: Страница не найдена.
500: Внутренняя ошибка сервера.
403: Доступ запрещён.
200: Обычный успешный запрос (например, после действия, выполненного пользователем).
Подробности: Коды сообщения, такие как 403, 404, 500, могут быть использованы для передачи информации о статусе выполнения скрипта и связанного с ним сообщения.

2. заголовок HTML-страницы $header (bool)

Описание: Если параметр установлен в true, то будет отображён заголовок HTML-страницы, в противном случае заголовок будет пропущен.
Назначение: Этот параметр позволяет контролировать, будет ли выведен стандартный HTML-заголовок страницы с <head>, <title>, и мета-данными. Если заголовок не нужен (например, при Ajax-запросах), можно установить его в false.
Значение по умолчанию: true.
Пример использования:
Если нужно отобразить полный HTML-страницу с заголовком, оставляем true.
Если нужен только контент, например, при Ajax-запросах, можно поставить false.

3. Заголовок сообщения $message_title (string)

Описание: Заголовок сообщения, который будет отображён пользователю.
Назначение: Позволяет задать индивидуальный заголовок для страницы сообщения. Если параметр не передан, то используется стандартный заголовок, соответствующий коду сообщения из языкового файла.
Значение по умолчанию: Пустая строка ('').
Пример: Если не передать этот параметр, заголовок будет соответствовать значению, определённому в языковом файле, например, "404 Not Found". Если передать значение, например "Ошибка доступа", оно будет использовано вместо стандартного.

4. Текст сообщения $message_body (string)

Описание: Основной текст сообщения, который будет отображён на странице.
Назначение: Это тело сообщения, которое будет показано пользователю в случае ошибки или другого важного события.
Значение по умолчанию: Пустая строка ('').
Пример: Если не передать параметр, используется стандартное сообщение, соответствующее коду, например, "Страница не найдена." для кода 404. Если передать, например, "Запрашиваемая страница не существует", это сообщение будет отображаться.

5. URL перенаправления $redirect (string)

Описание: URL для автоматического перенаправления пользователя после отображения сообщения. Используется для того, чтобы через некоторое время (обычно 3 секунды) перенаправить пользователя на другой ресурс.
Назначение: Если необходимо выполнить редирект после сообщения (например, для возвращения на главную страницу или другую страницу), передается URL, куда нужно направить пользователя.

Значение по умолчанию: Пустая строка ('').

Пример: Если передать URL, например, '/home', то через 3 секунды после отображения сообщения пользователь будет перенаправлен на страницу домашнего ресурса.

Пример вызова функции cot_die_message в котонти:

cot_die_message(404, true, "Page Not Found", "The page you're looking for does not exist.", "/home");

Результат:

Код: 404 (страница не найдена).
Заголовок: true (выводить заголовок страницы).
Заголовок сообщения: "Page Not Found".
Тело сообщения: "The page you're looking for does not exist.".
Редирект: Перенаправление на главную страницу (/home) через 3 секунды.

В этом примере, если запрашиваемая страница не найдена, функция выведет сообщение об ошибке, с заголовком и текстом, а затем через 3 секунды автоматически перенаправит пользователя на домашнюю страницу.

 

Заключение:
Функция cot_die_message используется для отображения различных типов сообщений об ошибках (или информации) пользователю. Она поддерживает динамическое создание заголовков, тела сообщений, редиректов и поддержку различных кодов ошибок.