Плагины в MODX: типичные ошибки и способы их найти
Плагин MODX может отработать без единой ошибки, но не изменить страницу, сработать дважды или замедлить админку. Разбираем частые проблемы с событиями, кэшем, контекстами и параметрами на MODX Revolution 2.8.x и MODX 3.x.
Плагин MODX чаще ломается не из-за PHP-синтаксиса, а из-за неверного системного события, кэша или ожидания, что один и тот же код одинаково работает в админке и на сайте. В результате обработчик молча не запускается, срабатывает дважды или добавляет к странице старый результат. Ниже — практический разбор для MODX Revolution 2.8.x и MODX 3.x: как отличить эти случаи, что проверять первым и чем платить за каждый способ исправления.
Сначала определите, что именно должен делать плагин
Плагин MODX — это PHP-код, привязанный к системному событию. Он не вызывается по URL, как сниппет, и не выводит результат на странице только потому, что вы создали объект в админке. Событие должно произойти, а код должен получить нужные параметры.
Системное событие — точка в жизненном цикле MODX, к которой подключается плагин: например, открытие страницы, сохранение ресурса или обработка запроса.[1]
Перед отладкой зафиксируйте три вещи:
- где должен работать код: сайт, админка или оба интерфейса;
- на каком событии он должен запускаться;
- какой результат ожидается: изменение данных, добавление HTML, редирект, запись в журнал или вызов другого сервиса.
Если плагин «не работает», сначала проверяйте не PHP-код, а цепочку «событие → привязка → параметры → кэш». В MODX проблема обычно находится именно в ней.
Ошибка 1. Плагин создан, но не привязан к событию
Создание плагина в разделе «Элементы» не запускает его автоматически. После сохранения нужно открыть вкладку с системными событиями и добавить хотя бы одно событие. Без этой связи MODX не знает, когда выполнять код.
Частая ошибка — выбрать событие с похожим названием. Например, код, который должен менять HTML перед отправкой браузеру, привязывают к событию, срабатывающему при инициализации страницы. Такие события находятся в разных местах жизненного цикла запроса и передают разные параметры.
| Задача | Что проверить | Цена ошибки |
|---|---|---|
| Изменить страницу перед отправкой | Событие получает текущий вывод и позволяет передать изменённый результат дальше | Код отработит, но HTML не изменится |
| Обработать сохранение ресурса | В параметрах события доступен сохраняемый ресурс | Плагин сработает не в тот момент или не найдёт данные |
| Добавить проверку запроса | Код подключён к событию обработки запроса, а не к событию рендера | Проверка будет слишком поздней |
| Изменить админскую форму | Событие относится к менеджеру, а не к публичной части сайта | На сайте всё работает, но в админке изменений нет |
Для проверки временно добавьте запись в журнал MODX в самом начале обработчика. Не оставляйте подробное логирование включённым на рабочем сайте: большой поток событий быстро увеличивает файл журнала.
Ошибка 2. Перепутаны плагины, сниппеты и чанки
Сниппет вызывается из шаблона или другого кода, а плагин ждёт системное событие. Если вставить логику плагина в сниппет и не вызвать его, она не выполнится. Обратная ситуация тоже типична: разработчик рассчитывает на вызов сниппета, но пишет код в плагине и не привязывает его к событию.
Ориентир простой:
- нужен результат в конкретном месте шаблона — обычно подходит сниппет;
- нужно реагировать на сохранение, авторизацию или обработку запроса — нужен плагин;
- нужен повторяемый фрагмент разметки — используйте чанк, а не обработчик события.
Не превращайте плагин в универсальный контейнер для всей бизнес-логики. Подписка на несколько десятков событий усложняет порядок выполнения, а изменение одного участка может повлиять на unrelated-код в другом разделе сайта.
Ошибка 3. Код подписан на слишком раннее или слишком позднее событие
У события есть не только название, но и момент выполнения. На ранней стадии в объекте запроса ещё может не быть данных ресурса, а на поздней стадии HTML уже может быть отправлен или заменён другим обработчиком.
Например, фильтр доступа, который должен остановить запрос, нельзя строить как замену готового HTML. А обработчик, добавляющий метатег в итоговую страницу, не должен рассчитывать на параметры формы сохранения ресурса.
Как проверять порядок выполнения
- Зафиксируйте событие. Запишите его точное имя и область работы: сайт или менеджер. Проверка: в настройках плагина видно нужное событие, а не только имя, похожее по смыслу.
- Проверьте параметры события. На тестовом стенде выведите в журнал только имена ключей из массива параметров, без паролей и пользовательских данных. Проверка: вы видите, какие значения реально передаются на этой версии MODX.
- Сравните момент изменения. Если меняете HTML, проверьте, что обработчик получает итоговый вывод и передаёт изменённую строку дальше. Проверка: изменение видно в исходном коде страницы, а не только в отладочном сообщении.
- Уберите лишние подписки. Оставьте одно событие, на котором задача решается напрямую. Проверка: действие выполняется один раз при одном запросе или сохранении.
Названия и доступные параметры событий могут различаться между MODX Revolution 2.8.x и MODX 3.x. Для рабочего проекта сверяйте выбранное событие с документацией и тестируйте код на той версии, где он будет запущен.
Ошибка 4. Плагин срабатывает дважды
Двойной запуск часто принимают за проблему в PHP-коде. На практике причина бывает в двух привязках, повторном запросе из браузера или в том, что один плагин вызывает логику, уже подключённую к другому событию.
Добавьте в журнал временную метку, имя события и идентификатор объекта, который обрабатываете. Если записи отличаются событиями, код действительно запускается дважды в разных точках. Если события одинаковые, ищите повторную привязку или второй запрос.
Особенно опасен повторный запуск для обработчиков сохранения: они могут дважды отправить уведомление, создать дубликат записи или перезаписать поле. Для таких операций заранее решите, по какому признаку повтор можно распознать. Не полагайтесь только на глобальную переменную: она не защищает от повторного запуска в следующем HTTP-запросе.
Ошибка 5. Кэш скрывает правильный результат
Вы изменили плагин, обновили страницу, но видите старый HTML. Это не доказывает, что код не выполнился. В MODX результат может приходить из кэша ресурса, кэшируемого сниппета или внешнего кэша веб-сервера и CDN.
Проверяйте проблему по слоям:
- очистите кэш MODX через админку или штатную команду, принятую в вашей установке;
- временно отключите кэширование конкретного ресурса, если это безопасно для тестового стенда;
- проверьте заголовки ответа и кэш браузера;
- сделайте повторный запрос с параметром, который исключает сохранённую копию на прокси, если такая схема разрешена вашей инфраструктурой.
На продакшене не оставляйте отключённое кэширование «для надёжности». Оно может увеличить нагрузку на PHP и базу данных, а ошибка в логике всё равно останется.
Ошибка 6. Плагин не учитывает контекст и режим запроса
Один сайт MODX может обслуживать несколько контекстов, например публичную часть, API и отдельный кабинет. Плагин, который без проверки меняет все запросы, способен добавить служебный HTML в JSON-ответ или применить правила сайта к административной панели.
Проверяйте контекст, тип запроса и наличие ожидаемого объекта до изменения данных. Если код должен работать только на сайте, не запускайте его в менеджере. Если обработчик меняет вывод, убедитесь, что ответ действительно HTML, а не JSON, файл или служебный ответ.
Для AJAX-запросов и API особенно важны побочные эффекты: случайный вывод предупреждения или HTML превращает корректный JSON в невалидный ответ. Такой дефект может быть незаметен в браузере, но сразу проявиться в JavaScript-клиенте.
Ошибка 7. В коде нет защиты от пустых параметров
На тестовой странице нужный ресурс, пользователь или поле почти всегда есть. На реальном сайте запрос может прийти без идентификатора, с удалённым объектом или с пустым значением формы. Доступ к вложенному параметру без проверки превращается в предупреждение или фатальную ошибку.
Минимальная защита выглядит так: сначала проверить, что параметр существует и имеет ожидаемый тип, затем получить объект и только после этого менять его поля. Для пользовательских данных дополнительно нужны проверка прав, валидация и экранирование при выводе. Эти задачи нельзя заменять проверкой «поле не пустое».
Что выбрать для исправления
| Подход | Когда использовать | Чем платите |
|---|---|---|
| Исправить привязку к событию | Код не запускается или получает не те параметры | Нужно разобраться в жизненном цикле запроса |
| Перенести код в сниппет | Нужен управляемый вызов и возвращаемый результат в шаблоне | Придётся явно вызывать сниппет в каждом нужном месте |
| Разделить один плагин на несколько | Обработчик делает разные задачи на разных событиях | Появится больше элементов и тестов |
| Оставить логику в плагине | Нужно централизованно реагировать на системное событие | Ошибки в привязке и порядке выполнения сложнее заметить |
Что ломается первым
На небольшой визитке большинство ошибок проявится сразу. На магазине или портале проблемы возникают под нагрузкой: плагин выполняется на каждом запросе, делает запрос к базе или обращается к внешнему API. Страница становится медленнее, а при недоступности внешнего сервиса перестаёт отвечать вся цепочка.
Не выполняйте тяжёлые операции в событии, через которое проходит каждый просмотр страницы. Если действие не нужно пользователю в текущем запросе, вынесите его в очередь или отдельный процесс. В любом случае измеряйте время обработки, число запросов к базе и количество записей в журнале. Числа до и после снимайте на одинаковом стенде: с той же версией PHP, базой, объёмом данных и уровнем параллельных запросов.
Что делать дальше
Создайте тестовую копию сайта и заведите для каждого плагина короткую карточку: версия MODX, событие, контекст, входные параметры, ожидаемый результат и условия, при которых обработчик не должен запускаться. Затем проверьте четыре сценария — обычный запрос, пустой параметр, повторное выполнение и очищенный кэш.
После этого посмотрите в продакшене на время ответа, количество ошибок PHP и частоту срабатывания обработчиков. Отдельно проверьте документацию по системным событиям именно для установленной ветки MODX. Инвалидация кэша и устройство менеджера — отдельные темы; здесь важнее сначала восстановить предсказуемую цепочку запуска.
Примечание. Примеры и рекомендации рассчитаны на MODX Revolution 2.8.x и MODX 3.x. Точные доступные события и параметры зависят от версии, дополнений и конфигурации проекта.
Логотип и фирменный стиль: Три концепции разного характера, палитра с обоснованием, проверка на читаемость в малом размере и в один цвет.
Спросить за 60 ₽Источники: MODX Documentation: Plugins, MODX Documentation: System Events
Частые вопросы
Почему плагин MODX сохранён, но не запускается?
Как понять, что плагин сработал дважды?
Почему после исправления плагина на странице остаётся старый результат?
Можно ли использовать один плагин для сайта и админки?
Что будет, если плагин обращается к отсутствующему параметру?
Подойдут ли эти рекомендации для другой версии MODX?
Материал носит информационный характер и подготовлен редакцией «Агентуры». Он не является офертой, рекламой или индивидуальной консультацией. Упомянутые продукты, компании и торговые знаки принадлежат их правообладателям. Перед принятием решений, влекущих юридические или финансовые последствия, обратитесь к профильному специалисту.