Функция cot_url в Cotonti

1. Тема и описание функции cot_url в Cotonti:

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

2. Код штатной функции cot_url в Cotonti:

/**
 * Преобразует параметры в URL с учетом пользовательских правил.
 * Эта функция может быть перегружена функцией cot_url_custom().
 *
 * @param string $name Имя модуля или скрипта
 * @param array|string $params Параметры URL в виде массива или строки
 * @param string $tail Постфикс URL, например, якорь
 * @param bool $htmlspecialcharsBypass Если TRUE, не преобразует & в & и другие специальные символы
 * @param bool $ignoreAppendix Если TRUE, $cot_url_appendix игнорируется для данного URL
 * @return string Корректный HTTP URL
 */
function cot_url($name, $params = '', $tail = '', $htmlspecialcharsBypass = false, $ignoreAppendix = false)
{
    global $cot_url_appendix; // Используется глобальная переменная $cot_url_appendix для добавления параметров к URL.

    // Предварительная обработка аргументов
    if (is_string($params)) {
        $params = cot_parse_str($params);
        // Если $params переданы в виде строки, вызывается функция cot_parse_str, которая преобразует строку в массив параметров.
    } elseif (!is_array($params)) {
        $params = [];
        // Если $params не является массивом, оно приводится к пустому массиву.
    }

    if (!$ignoreAppendix && count($cot_url_appendix) > 0) {
        $params = $params + $cot_url_appendix;
        // Если $ignoreAppendix равно FALSE и $cot_url_appendix содержит параметры, они добавляются к массиву $params.
    }

    // Обработка параметров
    foreach ($params as $k => $param) {
        if (is_bool($param)) {
            $params[$k] = (int) $param;
            // Если параметр является булевым значением, он преобразуется в целое число (0 или 1).
        }
        if (!is_array($param) && !is_object($param)) {
            $params[$k] = strval($param);
            // Если параметр не является массивом или объектом, он приводится к строке.
        }
        if ($params[$k] === '' || $params[$k] === null) {
            unset($params[$k]);
            // Если значение параметра пустое или равно null, оно удаляется из массива $params.
        }
    }

    // Проверка наличия пользовательской функции cot_url_custom
    if (function_exists('cot_url_custom')) {
        return cot_url_custom($name, $params, $tail, $htmlspecialcharsBypass);
        // Если существует функция cot_url_custom, управление передается ей, и текущая функция завершает работу.
    }

    // Определение базового URL
    $url = in_array($name, array('admin', 'login', 'message')) ? "$name.php" : 'index.php';
    // Если $name является одним из 'admin', 'login' или 'message', базовый URL устанавливается как $name.php, иначе используется 'index.php'.

    if (!in_array($name, array('admin', 'index', 'login', 'message', 'plug'))) {
        $params = array('e' => $name) + $params;
        // Если $name не находится в списке определенных значений, параметр 'e' с именем скрипта добавляется в массив $params.
    }

    // Добавление строки запроса, если это необходимо
    if (count($params) > 0) {
        $sep = $htmlspecialcharsBypass ? '&' : '&';
        // Определяем разделитель параметров: & для $htmlspecialcharsBypass = TRUE, или & для FALSE.

        $url .= '?' . http_build_query($params, '', $sep, PHP_QUERY_RFC3986);
        // Формируем строку запроса из массива $params с использованием функции http_build_query, указывая стандарт RFC3986.
    }

    $url .= $tail;
    // Добавляем к URL значение параметра $tail, если оно задано.

    //$url = str_replace('&', '&', $url);
    // Этот закомментированный код устраняет лишнее экранирование &, но он не используется.

    return $url;
    // Возвращаем сформированный URL.
}

Разбираем сновной код функции:

global $cot_url_appendix;

Комментарий:

Глобальная переменная $cot_url_appendix содержит дополнения, которые будут автоматически добавлены ко всем URL, если это не отключено через параметр $ignoreAppendix.
Обработка входных параметров:
 
 

// Предобработка аргументов
if (is_string($params)) {
    $params = cot_parse_str($params);
} elseif (!is_array($params)) {
    $params = [];
}

Комментарий:

Если $params передан как строка (например, param1=value1&param2=value2), он преобразуется в массив с помощью функции cot_parse_str() (ранее разобранной).
Пример: "param1=value1&param2=value2" станет ['param1' => 'value1', 'param2' => 'value2'].
Если $params не является массивом и не строкой (например, null), он инициализируется как пустой массив.
Добавление глобального $cot_url_appendix:
 
if (!$ignoreAppendix && count($cot_url_appendix) > 0) {
    $params = $params + $cot_url_appendix;
}
Комментарий:

Если параметр $ignoreAppendix равен false, а глобальный $cot_url_appendix содержит данные, они добавляются в массив $params.
Оператор + добавляет элементы из $cot_url_appendix, если они ещё не существуют в $params.
Это позволяет автоматически добавлять глобальные параметры, такие как токены сессии.
Обработка значений параметров:
 
foreach ($params as $k => $param) {
    if (is_bool($param)) {
        $params[$k] = (int) $param;
    }
    if (!is_array($param) && !is_object($param)) {
        $params[$k] = strval($param);
    }
    if ($params[$k] === '' || $params[$k] === null) {
        unset($params[$k]);
    }
}
Комментарий:

Если значение параметра — булево (true или false), оно преобразуется в 1 или 0.
Это необходимо, так как URL-строка не поддерживает булевы значения.
Если значение не массив и не объект, оно преобразуется в строку.
Параметры с пустыми значениями ('' или null) удаляются из массива $params.
Проверка на существование кастомной функции:
 
if (function_exists('cot_url_custom')) {
    return cot_url_custom($name, $params, $tail, $htmlspecialcharsBypass);
}
Комментарий:

Если существует пользовательская функция cot_url_custom(), она вызывается вместо стандартной реализации cot_url().
Это позволяет разработчикам переопределять логику генерации URL, если требуется.
Формирование базового URL:
 
$url = in_array($name, array('admin', 'login', 'message')) ? "$name.php" : 'index.php';
if (!in_array($name, array('admin', 'index', 'login', 'message', 'plug'))) {
    $params = array('e' => $name) + $params;
}
Комментарий:

Если $name равен 'admin', 'login' или 'message', базовый URL устанавливается как $name.php.
Например, 'admin' → 'admin.php'.
В остальных случаях базовый URL — это 'index.php'.
Если $name не равен 'admin', 'index', 'login', 'message' или 'plug', в параметры добавляется элемент 'e' => $name.
Это позволяет указать имя модуля или плагина, который будет обработан.
Добавление строки запроса:
 
if (count($params) > 0) {
    $sep = $htmlspecialcharsBypass ? '&' : '&';
    $url .= '?' . http_build_query($params, '', $sep, PHP_QUERY_RFC3986);
}
Комментарий:

Если в $params есть параметры, они преобразуются в строку запроса с помощью http_build_query().
Разделитель между параметрами (& или &) зависит от значения $htmlspecialcharsBypass:
Если true, используется & (без преобразования для HTML).
Если false, используется & (для корректного отображения в HTML).
Добавление постфикса (якори):
 
$url .= $tail;
Комментарий:

Если указан постфикс $tail (например, #anchor), он добавляется в конец URL.
Возврат результата:
 
return $url;
Комментарий:

Возвращается готовый URL.
3. Пример работы функции:
 
$url = cot_url('page', ['id' => 123, 'cat' => 'news'], '#comments');
echo $url;
Результат:
index.php?e=page&id=123&cat=news#comments

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