Хуки и доработки ядра DLE: типичные ошибки

В DLE одна правка в engine может работать месяцами, а после обновления исчезнуть вместе с исправленным файлом. Хуки снижают этот риск, но только если вы понимаете, в какой момент они вызываются, какие данные получают и что произойдёт при повторном запуске. Ниже — практический разбор для DLE 17.x и близких веток: названия событий и структура конкретной сборки могут отличаться, поэтому перед изменениями сверяйте их с документацией и файлами своей версии.

Главная ошибка — считать ядро единственным местом для правки

В DLE обычно смешивают три разных типа изменений:

• изменение внешнего вида и вывода — шаблон, CSS, JavaScript;
• добавление поведения — хук, плагин или отдельный обработчик;
• изменение логики самого движка — правка файлов в engine.

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

Доработка считается безопасной не тогда, когда она работает на тестовом сайте, а тогда, когда её можно повторно установить после обновления DLE.

Хук^[1] — точка в коде движка, где система передаёт управление пользовательскому обработчику. Хук не меняет файл, в котором объявлен: он позволяет подключить дополнительную логику до, после или во время определённого действия — если конкретное событие это допускает.

Четыре подхода к одной доработке

До начала работы сформулируйте результат, а не способ: «добавить метку к материалу», «проверить роль пользователя», «изменить вывод списка». После этого сравните варианты.

Хук не заменяет отдельный модуль

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

Так код проще отключить и протестировать. Кроме того, ошибка в обработчике не будет блокировать весь сценарий сохранения материала.

Прямая правка ядра: когда она оправдана

Иногда в нужном месте нет события, а изменение должно происходить до формирования результата. Тогда создайте отдельную копию изменяемого файла, сохраните исходник и оформите разницу как патч. Не ограничивайтесь комментарием «изменено под клиента»: через полгода он не объяснит, зачем появилась каждая строка.

Перед обновлением DLE полезно составить список изменённых файлов и проверить их сравнением с чистой версией той же редакции. Не сравнивайте файлы с другой версией движка: в результате смешаются ваши изменения и штатные изменения разработчиков.

Типичные ошибки при работе с хуками

1. Событие выбрано по названию, а не по месту вызова

Похожее название не означает одинаковый контекст. Одно событие может выполняться при открытии страницы, другое — только при сохранении данных, третье — в административной части. В обработчике могут отсутствовать идентификатор материала, объект пользователя или уже подготовленный текст.

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

• при каком запросе оно срабатывает;
• какие аргументы передаются и можно ли их менять;
• сколько раз событие вызывается за один запрос;
• что произойдёт, если обработчик вернёт пустое значение или изменённую строку.

Если точное имя события не подтверждается документацией вашей версии DLE или поиском по исходникам, не подставляйте похожее название. Сначала найдите реальный вызов в установленной сборке.

2. Обработчик выполняется повторно

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

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

3. Логика попадает в каждый запрос

Файл, подключаемый из общей инициализации DLE, может выполняться на страницах сайта, в AJAX-запросах, RSS и административной части. Запрос к внешнему API или тяжёлый SQL в таком месте увеличивает задержку даже там, где функция не нужна.

Ограничивайте обработчик по контексту: типу запроса, модулю, наличию нужного параметра и правам пользователя. Проверка должна происходить до обращения к базе или внешнему сервису.

4. В обработчике нет проверки входных данных

Данные из GET, POST, cookie и пользовательского текста нельзя считать безопасными только потому, что их передал внутренний экран DLE. Проверяйте тип и формат значения, используйте штатные механизмы экранирования и параметры запросов, а HTML выводите только после корректной обработки для конкретного контекста.

Отдельно проверьте права: скрытие кнопки в шаблоне не запрещает прямой запрос к обработчику. Авторизация должна выполняться на сервере.

5. Ошибка в хуке ломает основной сценарий

Если обработчик работает при сохранении материала, исключение или неверное изменение переменной может оборвать сохранение. На тестовой копии включите журналирование ошибок, а на рабочем сайте не выводите трассировку посетителю.

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

Как проверять доработку перед публикацией

1. Соберите карту изменений. Запишите версию DLE, список файлов, таблиц и настроек, которые затрагивает решение. Проверка: другой разработчик может понять, что нужно перенести на чистый стенд.
2. Сделайте резервную копию. Нужны файлы сайта и база данных, а не только архив изменённого PHP-файла. Проверка: резервную копию удалось развернуть на отдельной среде.
3. Проверьте обычный сценарий. Откройте страницу гостем и авторизованным пользователем, создайте и измените тестовый материал, повторите отправку формы. Проверка: нужное действие выполняется один раз, а штатные операции не изменились.
4. Проверьте границы. Используйте пустое значение, длинную строку, неверный идентификатор и пользователя без нужной роли. Проверка: запрос получает отказ или безопасный результат, а не предупреждение PHP и не белую страницу.
5. Сравните производительность. Замерьте время ответа и количество запросов к базе до и после изменения на одинаковом стенде. Проверка: изменение не добавляет тяжёлую операцию в каждый запрос без необходимости.
6. Проведите пробное обновление. На копии сайта установите целевую версию DLE и повторите тесты. Проверка: хук подключается, модуль открывается, а список ручных правок содержит только необходимые отличия.

Что ломается первым после обновления

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

Отдельный риск — изменения шаблона. После обновления в нём может появиться новый обязательный тег или измениться набор доступных переменных. Проверяйте не только PHP-ошибки, но и HTML, права пользователя, формы, RSS, пагинацию и кэш.

Кэширование — смежная тема: здесь важно только помнить, что успешное выполнение хука не гарантирует немедленное обновление уже сохранённого результата. После публикации проверьте страницу без кэша и обычным посетителем.

Когда выбрать каждый подход

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

Хороший критерий простой: после удаления вашей доработки DLE должен возвращаться к исходному поведению одним понятным действием. Если для этого приходится вспоминать десяток ручных правок, решение уже слишком хрупкое.

Что сделать дальше

Создайте тестовую копию сайта, зафиксируйте точную версию DLE и найдите реальный участок вызова нужного события в исходниках своей сборки. Затем оформите доработку как отдельный пакет или патч, добавьте сценарии проверки и сохраните результат в системе контроля версий. В проде после публикации смотрите не только журнал PHP-ошибок, но и время ответа, число запросов к базе, повторные записи и ошибки формы.

^[1] В разных системах словом «хук» называют и событие, и подключаемый обработчик. Для DLE важно проверять не термин из чужого примера, а конкретную точку вызова в вашей версии движка.