Функция cot_rc в Cotonti

Описание функции cot_rc.
Функция cot_rc является одной из вспомогательных, но часто применяемой функцией в PHP-фреймворке Cotonti, используемой для обработки строк с подстановкой значений. Она предназначена для замены переменных в строках с их реальными значениями.

Назначение функции cot_rc
Функция cot_rc используется для замены переменных в строках на значения, которые передаются ей через ассоциативный массив или строку параметров. Она может быть полезна, когда нужно динамически формировать текстовые строки с учетом различных значений, например, для генерации HTML-кода, сообщений, ссылок или других строк, содержащих переменные, которые должны быть заменены на актуальные данные.

/**
 * Resource string formatter function. Takes a string with predefined variable substitution, e.g.
 * 'My {$pet} likes {$food}. And {$pet} is hungry!' and an assotiative array of substitution values, e.g.
 * array('pet' => 'rabbit', 'food' => 'carrots') and assembles a formatted result.
 * You can also use parameter strings instead of arrays, e.g.
 * 'pet=rabbit&food=carrots'. Or omit the second parameter in case all substitutions are globals.
 *
 * @global array $R Resource strings
 * @global array $L Language strings, support resource sequences too
 * @param string $name Name of the $R item or a resource string itself
 * @param array<string, string>|string $params Associative array of arguments or a parameter string
 * @return string Assembled resource string
 */
function cot_rc($name, $params = [])
{
    global $R, $L, $theme_reload;

    if (isset($R[$name]) && is_array($theme_reload) && !empty($theme_reload['R'][$name])) {
        $R[$name] = $theme_reload['R'][$name];

    } elseif (isset($L[$name]) && is_array($theme_reload) && !empty($theme_reload['L'][$name])) {
        $L[$name] = $theme_reload['L'][$name];
    }

    if (isset($R[$name])) {
        $res = $R[$name];
    } elseif(isset($L[$name])) {
        $res = $L[$name];
    } else {
        $res = $name;
    }

    is_array($params) ? $args = $params : parse_str($params, $args);
    if (preg_match_all('#\{\$(\w+)\}#', $res, $matches, PREG_SET_ORDER)) {
        foreach($matches as $m) {
            $var = $m[1];
            $val = null;
            if (isset($args[$var])) {
                $val = $args[$var];
            }
            if ($val !== null) {
                $res = str_replace($m[0], $val, $res);
            } else {
                $res = str_replace($m[0], '', $res);
            }
        }
    }

    return $res;
}

Давайте разберем функцию cot_rc, которая выполняет форматирование строки ресурса с подстановкой переменных.

Задача: Функция предназначена для форматирования строк с предопределенной подстановкой переменных. Она принимает строку с переменными, например, 'My {$pet} likes {$food}. And {$pet} is hungry!', и ассоциативный массив или строку параметров для подставляемых значений. Результатом работы функции будет строка с подставленными значениями, например, 'My rabbit likes carrots. And rabbit is hungry!'.

Параметры:

$name: Это либо имя строки ресурса из глобальных массивов $R или $L, либо сама строка, требующая подстановки переменных.
$params: Это либо ассоциативный массив с парами "ключ-значение" для подстановки, либо строка параметров в формате ключ=значение.

Возвращаемое значение:

Функция возвращает строку с подставленными значениями.

Разбор кода:
 
global $R, $L, $theme_reload;
Здесь объявляются глобальные переменные, доступные внутри функции:
$R: Массив строк ресурсов.
$L: Массив строк на языке.
$theme_reload: Массив, который хранит данные, касающиеся перезагрузки темы.
 
if (isset($R[$name]) && is_array($theme_reload) && !empty($theme_reload['R'][$name])) {
    $R[$name] = $theme_reload['R'][$name];
} elseif (isset($L[$name]) && is_array($theme_reload) && !empty($theme_reload['L'][$name])) {
    $L[$name] = $theme_reload['L'][$name];
}

Этот блок проверяет, есть ли перезагруженные строки в массиве $theme_reload. Если такие строки существуют (например, при обновлении темы), то значения строк в массивах $R или $L обновляются с учетом новых значений из $theme_reload.
 
if (isset($R[$name])) {
    $res = $R[$name];
} elseif(isset($L[$name])) {
    $res = $L[$name];
} else {
    $res = $name;
}

Здесь происходит поиск строки в массиве $R (если это строка ресурса). Если ее нет в массиве $R, то она ищется в массиве $L (строка языка). Если строку не удалось найти ни в одном из массивов, то функция вернет имя переменной $name как результат.
 
is_array($params) ? $args = $params : parse_str($params, $args);

Если параметр $params является массивом, то он присваивается переменной $args. Если же $params — строка (например, "pet=rabbit&food=carrots"), то эта строка парсится в ассоциативный массив с помощью функции parse_str.
 
if (preg_match_all('#\{\$(\w+)\}#', $res, $matches, PREG_SET_ORDER)) {
    foreach($matches as $m) {
        $var = $m[1];
        $val = null;
        if (isset($args[$var])) {
            $val = $args[$var];
        }
        if ($val !== null) {
            $res = str_replace($m[0], $val, $res);
        } else {
            $res = str_replace($m[0], '', $res);
        }
    }
}

Эта часть кода выполняет подстановку переменных в строку. Для этого используется регулярное выражение preg_match_all, которое ищет все вхождения шаблона {$...} в строке $res.

\{\$(\w+)\} — регулярное выражение для поиска переменных в формате {$var}, где \w+ означает последовательность букв, цифр и подчеркиваний.

Все найденные переменные сохраняются в массиве $matches.
В цикле foreach($matches as $m):

$m[1] — это имя переменной, например, pet из {$pet}.
Если в массиве $args есть подставляемое значение для этой переменной, оно используется для подстановки.
Если значение найдено ($val !== null), то происходит подстановка этого значения в строку с помощью str_replace.
Если переменной нет в $args, то из строки убирается сама переменная, заменяя её на пустую строку.
 
return $res;

После завершения подстановки всех переменных функция возвращает готовую строку.

Пример использования:
 
// Пример массива с ресурсами
$R = array(
    'greeting' => 'Hello, {$name}! Welcome to {$place}.'
);

// Пример вызова функции cot_rc
echo cot_rc('greeting', array('name' => 'Alice', 'place' => 'Wonderland'));
// Вывод: "Hello, Alice! Welcome to Wonderland."

Поддерживаемые форматы параметров:

Ассоциативный массив:
 
cot_rc('greeting', array('name' => 'Alice', 'place' => 'Wonderland'));

Строка параметров (в формате URL-encoded):
 
cot_rc('greeting', 'name=Alice&place=Wonderland');

Глобальные параметры: Если параметры не переданы, функция может использовать глобальные значения.

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

Пример использования функции cot_rc

Проанализируем функцию и разберем выражение, в контексте логики php-фреймворка Cotonti

'FORUMS_POSTS_ROW_ANCHORLINK' => cot_rc('forums_code_post_anchor', array('id' => $row['fp_id'])),

Описание:
Это выражение используется для создания строки с подстановкой значений, а именно для создания ссылки на якорь в форуме. Рассмотрим каждый элемент подробнее:

FORUMS_POSTS_ROW_ANCHORLINK:

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

cot_rc('forums_code_post_anchor', array('id' => $row['fp_id'])):

Это вызов функции cot_rc, которая используется для форматирования строки с подстановкой переменных. Давайте разберем, как это работает:
Как работает cot_rc в данном выражении:
'forums_code_post_anchor':

Это имя строки ресурса, которое, скорее всего, хранится в глобальном массиве $R (или $L), как строка для генерации ссылки.
Строка forums_code_post_anchor должна быть определена в массиве ресурсов, например:

$R['forums_code_post_anchor'] = '<a href="#post{$id}">Jump to post {$id}</a>';

Здесь мы видим, что строка ресурса содержит ссылку в HTML-формате с переменной {$id}, которую нужно заменить на фактическое значение.

array('id' => $row['fp_id']):

Это ассоциативный массив, который передается функции cot_rc. Массив имеет один элемент, где:
Ключ: 'id' — это имя переменной, которое будет подставляться в строку ресурса.
Значение: $row['fp_id'] — это значение, которое будет подставлено на место переменной {$id} в строке ресурса.
Таким образом, из массива будет подставлено значение идентификатора поста (например, 123).
Функция cot_rc:

Как мы уже разобрали, эта функция заменяет в строках ресурса все переменные в формате {$var} на значения, переданные через массив или строку параметров.

В данном случае строка ресурса может быть, например:

$R['forums_code_post_anchor'] = '<a href="#post{$id}">Jump to post {$id}</a>';

Функция cot_rc заменит {$id} на значение, переданное в массиве array('id' => $row['fp_id']). Например, если $row['fp_id'] равно 123, то результат будет:

<a href="#post123">Jump to post 123</a>
Полный процесс:
Функция cot_rc ищет строку ресурса с именем 'forums_code_post_anchor' в глобальных массивах $R или $L.
Находит строку:

<a href="#post{$id}">Jump to post {$id}</a>

Подставляет значение из массива параметров в строку, заменяя {$id} на значение из $row['fp_id'] (например, 123).

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

<a href="#post123">Jump to post 123</a>

Результат:
Выражение 'FORUMS_POSTS_ROW_ANCHORLINK' => cot_rc('forums_code_post_anchor', array('id' => $row['fp_id'])) создает ссылку, которая будет вести на пост с идентификатором, соответствующим значению $row['fp_id'].
Это может быть полезно, например, для генерации ссылок на посты в форумах, чтобы пользователи могли перейти прямо к нужному сообщению на странице.
Заключение:
cot_rc используется для динамической подстановки переменных в строки, которые хранятся в ресурсах (например, строки HTML).
В данном примере создается динамическая ссылка на пост форума с использованием идентификатора, который извлекается из массива данных $row.

Детальное описание:

function cot_rc($name, $params = [])
{
    global $R, $L, $theme_reload;

    // Проверка и замена значений в случае перезагрузки темы
    if (isset($R[$name]) && is_array($theme_reload) && !empty($theme_reload['R'][$name])) {
        $R[$name] = $theme_reload['R'][$name];
    } elseif (isset($L[$name]) && is_array($theme_reload) && !empty($theme_reload['L'][$name])) {
        $L[$name] = $theme_reload['L'][$name];
    }

    // Проверка наличия строки в массиве $R (ресурсные строки)
    if (isset($R[$name])) {
        $res = $R[$name]; // Если строка найдена в $R, присваиваем значение переменной
    } elseif (isset($L[$name])) {
        $res = $L[$name]; // Если строка найдена в $L, присваиваем значение переменной
    } else {
        $res = $name; // Если строка не найдена, возвращаем саму строку имени
    }

    // Обрабатываем параметры, если они переданы в виде строки
    is_array($params) ? $args = $params : parse_str($params, $args);

    // Ищем все переменные в строке в формате {var_name}
    if (preg_match_all('#\{\$(\w+)\}#', $res, $matches, PREG_SET_ORDER)) {
        foreach($matches as $m) {
            $var = $m[1]; // Извлекаем имя переменной
            $val = null;
            // Проверяем, есть ли значение для этой переменной в массиве $args
            if (isset($args[$var])) {
                $val = $args[$var];
            }
            // Если значение найдено, заменяем переменную на значение
            if ($val !== null) {
                $res = str_replace($m[0], $val, $res);
            } else {
                // Если значение не найдено, удаляем переменную из строки
                $res = str_replace($m[0], '', $res);
            }
        }
    }

    // Возвращаем готовую строку
    return $res;
}

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

global $R, $L, $theme_reload; — здесь подключаются глобальные массивы $R и $L для строк ресурсов и строк языковых настроек соответственно. Также используется массив $theme_reload, который отвечает за перезагрузку строк при смене темы.
Перезагрузка строк в теме:

Далее идет проверка, если строки ресурсов были перезагружены в теме, то эти строки из массива $theme_reload перезаписываются в массивы $R или $L.
Это нужно для того, чтобы поддерживать актуальные строки при изменениях темы.
Поиск строки в глобальных массивах:

if (isset($R[$name])) { — если в массиве $R найдена строка с ключом $name, она присваивается переменной $res.
Если в $R строки нет, то функция ищет ее в массиве $L (языковые строки).
Если строка не найдена в обоих массивах, то возвращается сам ключ строки $name.
Обработка параметров:

Проверяется, переданы ли параметры в виде ассоциативного массива. Если параметры переданы как строка (например, 'id=rabbit&food=carrots'), то используется функция parse_str, чтобы превратить строку в ассоциативный массив $args.
Это позволяет удобно передавать параметры для подстановки в строку.
Регулярное выражение для поиска переменных в строке:

preg_match_all('#\{\$(\w+)\}#', $res, $matches, PREG_SET_ORDER); — это регулярное выражение ищет все переменные в формате {$var_name}, например, {$pet}, в строке $res.

Все найденные совпадения сохраняются в массив $matches, где каждый элемент — это найденная переменная.

Замена переменных в строке:

Для каждой найденной переменной:
Извлекается имя переменной, например, pet.
Проверяется, есть ли значение для этой переменной в массиве $args.
Если значение найдено, то оно подставляется в строку на место переменной. Если значения нет, то переменная просто удаляется из строки.

Функция str_replace используется для замены каждого вхождения переменной в строку.
Возвращаем результат:

После всех замен и подстановок функция возвращает итоговую строку.

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

Допустим, у нас есть строка ресурса:

$R['welcome_message'] = 'Hello, {$name}! Welcome to {$site}.';
И параметры:

$params = array('name' => 'John', 'site' => 'Cotonti');

Когда мы вызываем:

$formatted_message = cot_rc('welcome_message', $params);

Функция cot_rc заменит {$name} на John, а {$site} на Cotonti, и результат будет:

Hello, John! Welcome to Cotonti.

Заключение:

Функция cot_rc — это мощный инструмент для динамической генерации строк с подстановкой значений в их шаблоны. Она особенно полезна в контексте работы с языковыми и ресурсными строками в Cotonti. Этот механизм помогает легко управлять текстовыми строками в коде, позволяя формировать их на основе переданных данных.