Плагины MODX и системные события: как настроить без ошибок

В MODX один и тот же плагин может срабатывать при открытии страницы, сохранении ресурса или отправке формы — всё зависит от выбранного системного события. Если выбрать событие наугад, код либо не запустится, либо будет выполняться чаще, чем нужно. Ниже — практический порядок настройки для MODX Revolution 2.8 и 3.x; названия событий и доступные параметры сверяйте с установленной версией.

Сначала определите момент, а не пишите код

Системное событие — точка в работе MODX, в которой система запускает привязанные к нему плагины. Например, событие может происходить при начале обработки запроса или после сохранения ресурса. Плагин — код, который MODX вызывает в этой точке.

До создания плагина ответьте на три вопроса:

• Какое действие должно произойти: изменить вывод страницы, проверить данные или отреагировать на сохранение?
• В какой момент у MODX уже есть нужные вам данные?
• Должна ли логика выполняться на каждом запросе или только в конкретном контексте, шаблоне или ситуации?

У события есть имя, например OnWebPageInit. Регистр и написание важны. Не угадывайте имя по аналогии: откройте список событий в менеджере конкретной установки или документацию своей версии. В MODX 2.x и 3.x набор событий, параметры и поведение отдельных точек могут отличаться.

Хороший выбор события отвечает на вопрос «когда именно?»; проверка внутри плагина отвечает на вопрос «при каких условиях?».

Выберите один из трёх подходов

Плагин на раннем событии

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

Плагин на событии конкретного действия

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

Логика в сниппете или отдельном Extra

Сниппет удобен, когда код вызывается из шаблона или контента в конкретном месте. Отдельный Extra уместен, если функциональность нужно развивать, настраивать или переносить между сайтами как самостоятельный компонент. Цена — дополнительная структура и сопровождение. Не превращайте плагин в универсальный контейнер для всего проекта.

Настройте плагин по шагам

1. Запишите условие запуска. Например: «сработать при сохранении ресурса только в веб-контексте». Если условие нельзя сформулировать, вы пока не знаете, какое событие выбирать. Проверка: в задаче названы и момент запуска, и ограничение.
2. Найдите событие в своей установке. В менеджере откройте создание или редактирование плагина и изучите список доступных системных событий. Сопоставьте его с документацией для вашей версии MODX. Проверка: точное имя события есть в интерфейсе установленной системы и соответствует нужному моменту.
3. Создайте плагин и привяжите только нужное событие. Не отмечайте несколько событий «на всякий случай»: одно действие тогда может вызвать код несколько раз. Проверка: в настройках плагина выбрано только то событие, которое вы собираетесь тестировать.
4. Добавьте ранний выход для неподходящих случаев. Ограничьте выполнение контекстом или другими проверками, если это требуется. Для точных имён параметров события используйте документацию своей версии: состав доступных данных зависит от события. Проверка: при неподходящем условии плагин ничего не меняет.
5. Проверьте успешный и отрицательный сценарии. Запустите действие, которое должно вызвать событие, и похожее действие, при котором плагин должен молчать. Проверка: результат появляется только в первом сценарии; в журнале MODX или журнале PHP нет ошибок.

Что чаще всего ломается

Неверное имя или не то событие

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

Плагин выполняется слишком часто

Код привязан к событию, которое происходит на каждом запросе, хотя нужен только при одном действии. Добавьте проверку условий или перенесите логику на более подходящее событие. Если плагин выполняет тяжёлую работу, посмотрите, сколько раз он запускается за один пользовательский сценарий.

Ожидание не тех данных

Код обращается к параметру, которого у выбранного события нет, или рассчитывает получить его до того, как MODX его подготовил. Не переносите имена параметров из чужого примера без проверки. Сверьте документацию и протестируйте код на установленной версии.

Ошибка в PHP останавливает сценарий

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

Что измерять и где подход ломается

Для простого плагина достаточно проверить число запусков, ожидаемый результат и ошибки. Если код работает на запросах сайта, дополнительно сравните время ответа с выключенным плагином и с включённым на одинаковом сценарии. Зафиксируйте условия: версию MODX, контекст, действие, объём данных и наличие кеша. Без таких условий цифра времени мало что говорит.

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

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

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

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

Системный диспетчер событий — механизм MODX, который вызывает плагины в заданных точках работы системы. Список событий и передаваемые данные зависят от конкретной версии и выбранного события.