Плагин Logincheck

Плагин Logincheck для Cotonti: полное руководство

1. Назначение и концепция

Плагин Logincheck предназначен для автоматической нормализации и строгой проверки логина пользователя при регистрации в системе управления контентом Cotonti (версия 0.9.26 и выше, поддержка PHP 8.4+). Основная задача — преобразовать произвольный ввод пользователя в поле «Имя пользователя» (которое может содержать кириллические символы, пробелы, дефисы, подчёркивания, цифры и даже случайные специальные символы) в единообразный формат, полностью соответствующий внутренним ограничениям Cotonti и дополнительным требованиям безопасности.

Идея для нового плагина была взята и переработана на основе этого расширения.

 Постоянная ссылка на актуальный исходный код плагина на GitHub. 

Cotonti накладывает на поле user_name следующие ограничения:

• длина не более 32 символов (тип VARCHAR(32) в базе данных);
• первый символ должен быть латинской буквой (строчной или заглавной);
• последующие символы могут быть латинскими буквами, цифрами, подчёркиванием или дефисом.

Однако пользователи часто вводят имена с кириллицей, пробелами или случайными спецсимволами. Плагин Logincheck вмешивается на этапе валидации регистрационной формы, перехватывает введённое значение, выполняет серию преобразований и возвращает системе уже очищенное и проверенное значение. Если после всех преобразований логин не соответствует требованиям или попадает в чёрный список, регистрация отклоняется с понятным сообщением об ошибке.

Таким образом, администратор избавляется от необходимости вручную модерировать некорректные имена, а пользователи могут вводить привычные для них символы (например, кириллицу) и получать на выходе корректный латинский логин.

2. Техническая реализация: хук в системе Cotonti

Плагин подключается к системе через стандартный механизм хуков. В заголовке файла logincheck.users.register.add.validate.php указана директива:

Hooks=users.register.add.validate

Это означает, что код плагина будет выполнен в момент валидации данных, отправленных формой регистрации нового пользователя. Хук срабатывает до того, как Cotonti проверит данные по своим внутренним правилам и попытается создать запись в базе данных. Параметр Order=1 гарантирует, что данный хук выполнится первым среди других плагинов, использующих этот же хук, что важно для последовательной обработки логина.

Внутри хука доступен массив $ruser, содержащий все поля, переданные из формы регистрации. Интересующее нас поле — $ruser['user_name']. Плагин извлекает его значение, проводит все необходимые манипуляции и записывает обратно в тот же массив, после чего управление передаётся следующим хукам и, в конечном счёте, ядру Cotonti.

3. Пошаговый разбор нормализации логина

Рассмотрим последовательность преобразований, которым подвергается исходная строка логина. Каждый шаг сопровождается комментарием о его цели и примером.

3.1. Получение исходного значения

$username = $ruser['user_name'] ?? '';

Безопасное извлечение значения с помощью оператора объединения с null. Если по какой-то причине ключ отсутствует, переменная будет пустой строкой. Это предотвращает появление ошибок PHP в случае некорректных данных.

3.2. Транслитерация: cot_translit_encode

$username = cot_translit_encode($username);

Ключевой этап — преобразование нелатинских символов (например, кириллицы) в латиницу. Используется штатная функция Cotonti cot_translit_encode(), которая загружает массив соответствий из языкового файла translit.XX.lang.php, где XX — текущий язык системы. 

/**
 * Transliterates a string if transliteration is available
 *
 * @param string $str Source string
 * @return string
 *
 * @todo use intl php-extension
 */
function cot_translit_encode($str)
{
	global $lang, $cot_translit;
	static $lang_loaded = false;
	if (!$lang_loaded && $lang != 'en' && file_exists(cot_langfile('translit', 'core')))
	{
		require_once cot_langfile('translit', 'core');
		$lang_loaded = true;
	}
	if (is_array($cot_translit))
	{
		// Apply transliteration
		$str = strtr($str, $cot_translit);
	}
	return $str;
}

Механизм работы функции:

• Проверяется, не является ли текущий язык английским ($lang == 'en').
• Если язык не английский и файл translit.XX.lang.php существует, он подключается.
• Файл определяет глобальный массив $cot_translit, где ключами являются исходные символы (в UTF-8), а значениями — их латинские эквиваленты.
• Функция strtr() заменяет все вхождения ключей на соответствующие значения.

Важно отметить, что порядок элементов в массиве $cot_translit имеет значение: более длинные комбинации (диграфы, триграфы) должны быть расположены раньше, чтобы корректно обрабатываться. Например, в украинской таблице 'Щ' → 'Shch' стоит перед 'Ш' → 'Sh'.

Пример (русский язык): пользователь ввёл Иван Петров. После транслитерации получится Ivan Petrov 

(предполагая, что таблица транслитерации содержит стандартные замены: ).

'И'→'I', 'в'→'v', 'а'→'a', 'н'→'n', ' '→' ', 'П'→'P', 'е'→'e', 'т'→'t', 'р'→'r', 'о'→'o', 'в'→'v'

Пример (украинский язык): Євгенія → Yevheniia (согласно таблице: ).

'Є'→'Ye', 'в'→'v', 'г'→'h', 'е'→'e', 'н'→'n', 'і'→'i', 'я'→'ia'

Транслитерация — это основа «интернационализации» логина, позволяющая пользователям вводить имена на родном языке, но получать пригодное для URL и системных идентификаторов представление.

3.3. Замена пробельных символов на подчёркивание

$username = preg_replace('/\s+/u', '_', $username);

Регулярное выражение /\s+/u находит любые последовательности пробельных символов (пробел, табуляция, перенос строки и т.п.) и заменяет их на один символ подчёркивания. Модификатор u включает работу с UTF-8. В результате все пробелы схлопываются в одиночные подчёркивания.

Пример: Ivan Petrov → Ivan_Petrov.

3.4. Удаление всех символов, кроме разрешённых

$username = preg_replace('/[^a-zA-Z0-9_-]/', '-', $username);

Всё, что не является латинской буквой (в любом регистре), цифрой, подчёркиванием или дефисом, заменяется на дефис. Этот шаг гарантирует, что в строке останутся только допустимые символы. Любые «экзотические» знаки, пунктуация, символы других алфавитов (если транслитерация почему-то их пропустила) превратятся в дефисы.

Пример: Ivan_Petrov! → Ivan_Petrov-.

3.5. Сжатие множественных дефисов

$username = preg_replace('/-+/', '-', $username);

Любая последовательность из одного и более дефисов заменяется на один дефис. Предотвращает появление логинов типа user----name.

3.6. Сжатие множественных подчёркиваний

$username = preg_replace('/_+/', '_', $username);

Аналогично предыдущему шагу, но для подчёркивания. Устраняет конструкции вида user___name.

3.7. Удаление дефисов и подчёркиваний в начале и конце

$username = trim($username, '-_');

Функция trim() обрезает указанные символы с обоих концов строки. Логин не должен начинаться или заканчиваться разделителями — это правило Cotonti и общепринятая практика.

Пример: _Ivan-Petrov_ → Ivan-Petrov.

3.8. Проверка на пустую строку

if ($username === '') {
    cot_error($L['logincheck_error_invalidchars'], 'rusername');
    return;
}

Если после всех преобразований от исходной строки ничего не осталось (например, пользователь ввёл только пробелы или спецсимволы), плагин вызывает ошибку через функцию cot_error(). Сообщение берётся из языкового файла плагина. Параметр 'rusername' указывает, что ошибка относится к полю с именем пользователя (в форме регистрации это поле обычно называется rusername). После вызова ошибки выполнение хука прекращается, и Cotonti не допустит регистрацию.

3.9. Ограничение длины до 32 символов

$username = mb_substr($username, 0, 32);

Использование многобайтовой функции mb_substr() гарантирует корректную обрезку строки в кодировке UTF-8 до 32 символов, что соответствует максимальной длине поля user_name в таблице cot_users.

Важное замечание: обрезка выполняется до проверки первого символа и возможного добавления префикса. В текущей реализации это может привести к тому, что префикс user_ будет добавлен уже к обрезанной строке, и итоговая длина может превысить 32 символа. Рекомендуется изменить порядок: сначала проверить первый символ и при необходимости добавить префикс, затем обрезать до 32 символов. Однако текущая версия плагина сохраняет именно такую последовательность.

3.10. Проверка первого символа и добавление префикса

if (!preg_match('/^[a-zA-Z]/', $username)) {
    $username = 'user_' . $username;
}

Если после всех манипуляций логин не начинается с латинской буквы (например, остался только цифровой идентификатор или подчёркивание), к нему добавляется префикс user_. Это гарантирует, что первый символ будет буквой, что является обязательным требованием Cotonti (иначе не пройдёт финальная проверка регулярным выражением).

Пример: 12345 → user_12345.

3.11. Запись обработанного значения в массив

$ruser['user_name'] = $username;

Нормализованный логин помещается обратно в регистрационные данные. Дальнейшие хуки и сама система Cotonti будут работать уже с исправленным значением.

4. Финальная строгая проверка

if (!empty($ruser['user_name']) && 
    !preg_match("/^[a-zA-Z][_a-zA-Z0-9-]*$/", $ruser['user_name'])) {
    cot_error($L['logincheck_error_invalidchars'], 'rusername');
}

Даже после всех преобразований плагин выполняет контрольное сравнение с регулярным выражением, которое точно описывает допустимый формат:

• ^[a-zA-Z] — первый символ обязательно латинская буква;
• [_a-zA-Z0-9-]* — далее любое количество букв, цифр, подчёркиваний или дефисов;
• $ — конец строки.

Если по какой-то причине строка не соответствует шаблону (например, содержит недопустимый символ, пропущенный на этапе очистки, или имеет длину 0), регистрация будет отклонена.

5. Проверка по чёрному списку запрещённых имён

if (!empty($cfg['plugin']['logincheck']['invalidnames'])) {
    $invalidnames = array_map('trim', explode(',', $cfg['plugin']['logincheck']['invalidnames']));
    if (in_array($ruser['user_name'], $invalidnames, true)) {
        cot_error($L['logincheck_error_invalidname'], 'rusername');
    }
}

Плагин позволяет администратору задать список недопустимых логинов через настройки в панели управления. Конфигурационная опция invalidnames хранит строку с перечислением через запятую. При проверке плагин:

• разбивает строку в массив с помощью explode();
• применяет trim() к каждому элементу для удаления возможных пробелов вокруг имён;
• выполняет строгое сравнение (in_array(..., true)) на предмет совпадения с нормализованным логином.

Если логин совпадает с одним из запрещённых, пользователь увидит ошибку с текстом «Пожалуйста, укажите другой логин».

Администратор может добавить в этот список стандартные зарезервированные имена: admin, system, guest, root, support, moderator и любые другие по своему усмотрению.

6. Конфигурация плагина

Управление плагином осуществляется через стандартный конфигурационный файл logincheck.setup.php и интерфейс администрирования Cotonti. В секции [BEGIN_COT_EXT_CONFIG] определена одна настройка:

invalidnames=01:textarea:::Invalid names

Это означает, что в панели управления плагинами будет доступно текстовое поле (textarea) для ввода запрещённых логинов. Подпись к полю локализуется через языковой файл: $L['cfg_invalidnames'].

Языковые файлы плагина (logincheck.ru.lang.php и аналоги) содержат две строки:

• $L['logincheck_error_invalidchars'] — сообщение о недопустимых символах;
• $L['logincheck_error_invalidname'] — сообщение при совпадении с чёрным списком.

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

7. Взаимодействие с транслитерацией Cotonti

Ключевую роль в преобразовании кириллицы играет механизм транслитерации Cotonti. Плагин не содержит собственных таблиц замены, а полностью полагается на системные файлы translit.XX.lang.php. Это обеспечивает единообразие с другими частями системы (например, генерацией алиасов для страниц) и облегчает поддержку: обновление таблиц транслитерации в языковых пакетах автоматически улучшает и работу плагина.

Администратор может модифицировать или дополнять таблицу $cot_translit в соответствующем языковом файле, чтобы адаптировать правила транслитерации под конкретные нужды (например, изменить преобразование «Щ» с «Shch» на «Sch»). Важно соблюдать порядок элементов: более длинные последовательности должны располагаться выше.

Функция cot_translit_encode() статически кэширует загрузку языкового файла (переменная $lang_loaded), поэтому при многократных вызовах внутри одного запроса файл подключается только один раз, что экономит ресурсы.

8. Примеры полного цикла обработки

Ниже приведены примеры того, как плагин преобразует различные входные данные в конечный логин, пригодный для Cotonti.

Пример 1. Кириллица с пробелом

• Ввод пользователя: Иван Петров
• После транслитерации: Ivan Petrov
• Замена пробелов на подчёркивание: Ivan_Petrov
• Очистка недопустимых символов: Ivan_Petrov (изменений нет)
• Сжатие повторов, обрезка краёв: без изменений
• Длина в пределах 32, первый символ — буква → префикс не добавляется
• Результат: Ivan_Petrov

Пример 2. Имя с дефисом и спецсимволами

• Ввод: Анна-Мария!!!
• Транслитерация: Anna-Mariya!!!
• Пробелов нет, очистка: восклицательные знаки заменяются на дефисы → Anna-Mariya---
• Сжатие дефисов: Anna-Mariya-
• Удаление дефиса в конце: Anna-Mariya
• Результат: Anna-Mariya

Пример 3. Только цифры

• Ввод: 12345
• Транслитерация: 12345 (без изменений)
• Очистка: цифры остаются
• Первый символ не буква → добавляется user_
• Результат: user_12345

Пример 4. Имя с несколькими пробелами и смешанными регистрами

• Ввод: John Doe
• Транслитерация: John Doe (латиница не меняется)
• Замена пробелов: все пробельные последовательности заменяются на одиночные подчёркивания → _John_Doe_
• Очистка: допустимые символы остаются
• Удаление подчёркиваний по краям: John_Doe
• Результат: John_Doe

Пример 5. Строка, состоящая только из недопустимых символов

• Ввод: !!!@@@###
• Транслитерация без изменений
• Очистка: все символы заменяются на дефисы → -------
• Сжатие дефисов: -
• Обрезка краёв: пустая строка → ошибка «Логин должен состоять из латинского алфавита...»

Пример 6. Попадание в чёрный список

• Ввод: admin (если в настройках плагина указано admin)
• Все этапы нормализации проходят успешно, логин остаётся admin
• Проверка по чёрному списку находит совпадение → ошибка «Пожалуйста, укажите другой логин»

9. Рекомендации по улучшению и возможные доработки

Несмотря на то, что плагин успешно выполняет свои функции, в текущей версии можно отметить несколько моментов, которые при желании могут быть улучшены:

• Порядок добавления префикса и обрезки длины: как уже упоминалось, обрезка до 32 символов до добавления префикса может приводить к превышению лимита. Рекомендуется поменять шаги местами: сначала добавить user_, затем выполнить mb_substr().
• Расширение чёрного списка системными именами: плагин мог бы автоматически добавлять к пользовательскому списку стандартные зарезервированные имена Cotonti (admin, guest, system и т.д.), чтобы избежать их случайного использования.
• Логирование преобразований: для отладки можно записывать исходное и результирующее значения в лог-файл плагина, что упростит анализ проблем при массовой регистрации.
• Учёт регистра: в текущей реализации регистр сохраняется. Можно добавить опциональное приведение к нижнему регистру для единообразия (например, $username = mb_strtolower($username);).

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

10. Заключение

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

Для установки достаточно поместить файлы плагина в соответствующую директорию plugins/logincheck, активировать его в панели управления Cotonti и, при необходимости, заполнить список запрещённых логинов. Дальнейшая работа полностью автоматизирована и не требует вмешательства.

Таким образом, Logincheck — это незаменимый помощник для любого сайта на Cotonti, где важна чистота базы данных и единообразие пользовательских идентификаторов.