Функции генерирования и реализации капчи в Cotonti

Функции: cot_captcha_generate, cot_captcha_list, cot_captcha_validate и cot_generateCaptchaTags.
В этой статье расмотрим сразу несколько функций, вызов и использование которых нужно для реализации капчи на сайта под управлением Cotonti. Функции эти нужно рассматривать в общем контексте генерирования капчи, поэтому они все в одной статье.
 

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

Функция cot_captcha_generate

/**
 * Генерирует captcha
 *
 * @param ?string $useCaptcha Капча для явного использования
 * @return string
 * @global array $cot_captcha
 */
function cot_captcha_generate($useCaptcha = null)
{
    global $cot_captcha;

    // Если передан параметр $useCaptcha, используем его значение как капчу
    if (!empty($useCaptcha)) {
        $captcha = $useCaptcha;
    } elseif (!Cot::$cfg['captcharandom']) {  // Если случайная капча не разрешена в конфигурации
        $captcha = Cot::$cfg['captchamain'];  // Используем основную капчу из конфигурации
    } else {  // Если случайная капча включена
        $list = cot_captcha_list();  // Получаем список всех доступных капч
        if (empty($list)) {  // Если список пуст, возвращаем пустую строку
            return '';
        }
        // Выбираем случайную капчу из списка
        $captcha = $cot_captcha[rand(0, count($list) - 1)];
    }

    // Если капча не найдена или не задана, возвращаем пустую строку
    if (empty($captcha)) {
        return '';
    }

    // Создаем скрытое поле для передачи данных капчи
    $tepmcap = '<input type="hidden" name="capman" value="' . $captcha . '" />';

    // Добавляем суффикс '_generate' к имени капчи
    $captcha .= '_generate';

    // Проверяем, существует ли функция для генерации капчи
    if (!function_exists($captcha)) {
        return '';
    }

    // Если включен режим кэширования и страница не загружена через AJAX
    if (
        !COT_AJAX
        && Cot::$cfg['cache']
        && !empty(Cot::$cfg['cache_' . Cot::$env['ext']])
        && Cot::$cache
    ) {
        // Вставляем в футер код для загрузки капчи через JavaScript
        Resources::embedFooter(
            "document.addEventListener('DOMContentLoaded', function () {
                if (typeof cot !== 'undefined') {
                    cot.loadCaptcha();
                }
            });"
        );
        return '<span class="captcha-place-holder loading"></span>';  // Возвращаем заглушку для капчи
    }

    // Возвращаем результат работы функции капчи и скрытое поле
    return $captcha() . $tepmcap;
}

Анализ:

Назначение: Эта функция генерирует капчу для страницы. Капча может быть выбрана случайным образом или согласно основной конфигурации.
Параметры:
$useCaptcha — параметр, который позволяет вручную выбрать капчу, если она задана.
Основные шаги:
Если передан параметр $useCaptcha, используется эта капча.
Если в конфигурации не разрешена случайная капча, то используется основная капча из конфигурации.
Если случайная капча разрешена, выбирается случайная капча из доступных.
Функция проверяет, существует ли соответствующая функция для выбранной капчи. Если функция существует, она вызывает её для генерации капчи.
Кэширование и AJAX: При включенном кэшировании и отсутствии AJAX, вставляется JavaScript для загрузки капчи. Это помогает улучшить производительность, избегая загрузки капчи при каждом запросе.
Вывод: Функция возвращает HTML для капчи и скрытое поле с данными для валидации.

Логика работы
Выбор CAPTCHA.

Если передан параметр $useCaptcha, используется эта CAPTCHA.
Если настроено фиксированное использование одной CAPTCHA (captcharandom = false), выбирается основная (captchamain).
Если включена случайная CAPTCHA, выбирается случайный вариант из списка доступных.
Генерация скрытого поля.
Скрытое поле <input type="hidden"> передаёт название CAPTCHA для последующей проверки на сервере.

Кеширование и AJAX.

Если запрос не AJAX и кеширование активно, функция подключает JavaScript для загрузки CAPTCHA через AJAX.
Возвращается плейсхолдер <span>, который заменяется на реальную CAPTCHA после загрузки.
Генерация CAPTCHA.
Вызывается функция, соответствующая выбранной CAPTCHA, которая генерирует HTML-код.

Функция cot_captcha_list

/**
 * Возвращает список доступных капч
 * @global array $cot_captcha Реестр капч
 * @return array
 */
function cot_captcha_list()
{
    global $cot_captcha;
    return $cot_captcha;
}

Анализ:

Назначение: Функция возвращает список доступных капч, используя глобальный массив $cot_captcha.
Параметры: Нет параметров.
Возвращаемое значение: Возвращается массив $cot_captcha, который содержит список установленных капч.
Примечание: Этот массив обычно заполняется в конфигурации системы.

Функция cot_captcha_validate

/**
 * Валидирует значение капчи
 * @param string $value Вводимое значение капчи для проверки
 * @return bool
 */
function cot_captcha_validate($value)
{
    // Эта функция может быть вызвана только один раз за запрос
    static $called = false;
    if ($called) {
        return true;  // Если функция уже была вызвана, возвращаем true
    } else {
        $called = true;  // Помечаем, что функция была вызвана
    }

    // Получаем значение капчи из POST-запроса
    $captcha = cot_import('capman', 'P', 'TXT');

    // Проверяем, существует ли такая капча в списке доступных
    if (!in_array($captcha, cot_captcha_list())) {
        return false;  // Если капча не найдена в списке, возвращаем false
    }

    // Формируем название функции для валидации
    $validateFunction = $captcha . '_validate';

    // Если такая функция существует, вызываем её для проверки значения
    if (function_exists($validateFunction)) {
        return $validateFunction($value);
    }

    // Если функции для проверки капчи нет, возвращаем true
    return true;
}

Анализ:

Назначение: Эта функция проверяет правильность введенной капчи.
Параметры:
$value — значение капчи, которое было введено пользователем.

Основные шаги:
Функция использует статическую переменную $called, чтобы убедиться, что она вызывается только один раз за запрос.
Получает значение капчи из глобального массива $_POST.
Проверяет, существует ли капча в списке доступных капч.
Проверяет, существует ли функция для валидации конкретной капчи и вызывает её.
Возвращаемое значение:
Если капча валидна, возвращается true, иначе false.

Функция cot_generateCaptchaTags

/**
 * Генерирует XTemplate теги для капчи
 * @param string $captcha Тип капчи
 * @param string $inputName Имя для поля ввода
 * @param string $prefix Префикс для тега
 * @return array
 */
function cot_generateCaptchaTags($captcha = null, $inputName = 'rverify', $prefix = '')
{
    return [
        // Генерируем тег для изображения капчи
        $prefix . 'VERIFY_IMG' => cot_captcha_generate($captcha),
        // Генерируем тег для поля ввода капчи, если задано имя
        $prefix . 'VERIFY_INPUT' => !empty($inputName)
            ? cot_inputbox('text', $inputName, '', 'id="' . $inputName . '" maxlength="20"')
            : '',
    ];
}

Анализ:

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

Параметры:
$captcha — тип капчи, который используется.
$inputName — имя для поля ввода капчи.
$prefix — префикс, который будет добавлен к именам тегов.

Основные шаги:
Генерирует тег для изображения капчи с использованием функции cot_captcha_generate.
Генерирует тег для поля ввода капчи с использованием функции cot_inputbox, если задано имя поля.
Возвращаемое значение: Функция возвращает ассоциативный массив с тегами для изображения капчи и поля ввода, которые можно использовать в шаблоне.

Таким образом, все эти функции работают с системой капч в Cotonti, обеспечивая генерацию, валидацию и отображение капчи в шаблонах, а также создание соответствующих XTemplate тегов для интеграции с шаблонами.

пример в шаблоне страницы регистрации нового пользователя

            <!-- IF {PHP.cfg.captchamain|cot_plugin_active($this)} -->
            <tr>
                <td>{USERS_REGISTER_VERIFY_IMG}</td>
                <td>{USERS_REGISTER_VERIFY_INPUT} *</td>
            </tr>
            <!-- ENDIF -->