Функция cot_title в Cotonti

Функция cot_title генерирует строку заголовка, заменяя маски в шаблоне на соответствующие значения из переданных параметров. Она полезна, например, для создания динамических заголовков страниц, где маски в шаблоне подставляются значениями, полученными из конфигурации или переданных данных.

Код функции

function cot_title($mask, $params = [], $escape = true)
{
    $res = (!empty(Cot::$cfg[$mask])) ? Cot::$cfg[$mask] : $mask;
    is_array($params) ? $args = $params : mb_parse_str($params, $args);
    if (preg_match_all('#\{(.+?)\}#', $res, $matches, PREG_SET_ORDER)) {
        foreach($matches as $m) {
            $var = $m[1];
            $val = '';
            if (isset($args[$var])) {
                $val = $escape
                    ? htmlspecialchars($args[$var], ENT_COMPAT, 'UTF-8', false)
                    : $args[$var];
            }
            $res = str_replace($m[0], $val, $res);
        }
    }

    return trim($res);
}

Подробное объяснение работы функции:

Описание параметров:

$mask (string) — это маска, строка-шаблон, которая может содержать специальные элементы, заключённые в фигурные скобки ({}), такие как {SITE_TITLE}, {USER_NAME} и т. д. Также это может быть имя переменной из конфигурации (например, title_mask), если такой параметр существует в настройках.

$params (array|string) — это ассоциативный массив, который содержит параметры, которые будут подставлены на место соответствующих масок в строке. Это может быть либо ассоциативный массив (например, ['USER_NAME' => 'John']), либо строка, которая будет распарсена в массив с помощью mb_parse_str() (например, "USER_NAME=John").

$escape (bool) — флаг, который указывает, нужно ли экранировать специальные HTML-символы в значениях параметров. Если true, будут экранированы символы HTML, такие как <, >, & и другие.

Описание работы функции:

Проверка наличия маски в конфигурации:

$res = (!empty(Cot::$cfg[$mask])) ? Cot::$cfg[$mask] : $mask;

Сначала функция проверяет, есть ли в конфигурации (Cot::$cfg) значение, соответствующее ключу $mask. Если такой ключ существует, значение из конфигурации используется как шаблон. Если нет, используется сама строка $mask.

Парсинг параметров:

is_array($params) ? $args = $params : mb_parse_str($params, $args);

Если $params — это массив, он сохраняется в переменную $args. Если это строка, то она парсится в массив с помощью mb_parse_str(), которая преобразует строку вида "key1=value1&key2=value2" в ассоциативный массив.

Поиск масок в строке шаблона:

if (preg_match_all('#\{(.+?)\}#', $res, $matches, PREG_SET_ORDER)) {
    foreach($matches as $m) {
        $var = $m[1];
        $val = '';
        if (isset($args[$var])) {
            $val = $escape
                ? htmlspecialchars($args[$var], ENT_COMPAT, 'UTF-8', false)
                : $args[$var];
        }
        $res = str_replace($m[0], $val, $res);
    }
}

С помощью регулярного выражения preg_match_all() ищутся все подстроки в шаблоне, заключённые в фигурные скобки ({}). Например, если шаблон выглядит как "{SITE_TITLE} - {PAGE_NAME}", то будут найдены маски {SITE_TITLE} и {PAGE_NAME}.

Для каждой найденной маски:
Извлекается имя маски (например, SITE_TITLE).
Если эта маска найдена в массиве $args, то заменяется на её значение.
Если флаг $escape установлен в true, значение маски экранируется функцией htmlspecialchars(), чтобы избежать XSS-атак.
Затем это значение подставляется на место оригинальной маски в строке $res.

Возврат результата:

return trim($res);

 

Возвращается финальная строка с подставленными значениями.
Функция trim() удаляет лишние пробелы в начале и конце строки.

Пример использования:

Пример №1

if ($pag['page_cat'] == 'system') {
    Cot::$out['subtitle'] = empty($pag['page_metatitle']) ? $pag['page_title'] : $pag['page_metatitle'];
} else {
    $title_params = array(
        'TITLE' => empty($pag['page_metatitle']) ? $pag['page_title'] : $pag['page_metatitle'],
        'CATEGORY' => $cat['title']
    );
    Cot::$out['subtitle'] = cot_title(Cot::$cfg['page']['title_page'], $title_params);
}

Пример №2

$title_params = array(
    'FORUM' => Cot::$L['Forums'],
    'SECTION' => Cot::$structure['forums'][$s]['title'],
    'TITLE' => $rowt['ft_title']
);
$out['subtitle'] = cot_title(Cot::$cfg['forums']['title_posts'], $title_params);

 

Пример №3 с некими параметрами в виде массива:

$params = ['SITE_TITLE' => 'My Site', 'PAGE_NAME' => 'Home'];
$mask = '{SITE_TITLE} - {PAGE_NAME}';
echo cot_title($mask, $params);

Выведет:

My Site - Home

Пример с параметрами в виде строки (используется mb_parse_str для преобразования):

$params = 'SITE_TITLE=My Site&PAGE_NAME=Home';
$mask = '{SITE_TITLE} - {PAGE_NAME}';
echo cot_title($mask, $params);

Выведет:

My Site - Home

Пример с экранированием HTML-сущностей:

$params = ['SITE_TITLE' => '<My Site>', 'PAGE_NAME' => 'Home'];
$mask = '{SITE_TITLE} - {PAGE_NAME}';
echo cot_title($mask, $params, true);

Выведет:

<My Site> - Home

В этом примере, угловые скобки в SITE_TITLE будут экранированы, чтобы избежать возможных XSS-уязвимостей.

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