Разработка кастомного плагина MODX: от события до продакшена

Кастомный плагин MODX: где ломается логика сайта

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

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

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

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

Что меняется после внедрения: эффект в цифрах

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

Автоматизация забирает повторяющиеся действия: пересчёт остатков, простановку связанных полей, генерацию адресов страниц, выгрузку в смежные системы. Ручных правок в типовом потоке становится на 80–90% меньше, а там, где раньше требовался доступ к редактированию, остаётся только контроль результата.

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

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

Эффект от внедрения снимаем до и после на реальном потоке данных — по журналу событий, а не по ощущениям команды. Метрики проверяемы на стенде, поэтому результат не приходится принимать на слово.

Варианты реализации: плагин, сниппет, правка ядра

MODX почти любую доработку позволяет сделать несколькими способами, и выбор тут не про «как быстрее написать». Событийная модель даёт точки вмешательства в системные процессы, сниппеты закрывают логику вывода, ядро формально открыто для правок — но каждая ветка оставляет разный след в поддержке.

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

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

Этапы разработки: от схемы событий до выката

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

1. Аудит сайта — инвентаризация точек вмешательства: действующие плагины, сниппеты, настройки контекста, шаблоны. На выходе карта: что переиспользуем, что переопределяем, что трогать нельзя.
2. Схема событий и данных — список событий, приоритеты обработчиков, затрагиваемые таблицы и поля, поведение при частичном сбое. Согласуется до первой строки кода.
3. Прототип — минимальный плагин с одним обработчиком на тестовой копии: проверяем, что событие наступает в нужный момент, данные приходят полными, админка и публичная часть не деградируют.
4. Проверка на копии сайта — разворачиваем копию с сопоставимым объёмом данных и прогоняем сценарии: публикация, редактирование, удаление, права доступа, пакетные операции.
5. Проверка отказов — недоступность внешнего сервиса, повторный вызов события, массовый импорт. Плагин не должен блокировать сохранение документа.
6. Выкат на рабочий сайт — по шагам: резервная копия, сброс кэша и скомпилированных шаблонов, включение плагина, наблюдение за журналом ошибок в первые сутки.
7. Передача — репозиторий, описание событий и настроек, инструкция по откату на предыдущую версию.

Состав поставки: код, схемы, регламенты, документация

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

• Передача кода — репозиторий с полной историей, доступы оформлены на заказчика, развёртывание на чистом контуре воспроизводится по инструкции.
• Схема событий и зависимостей — какие события MODX перехватывает плагин, в каком порядке срабатывают обработчики, что изменится при отключении любого из них.
• Документация на плагин — назначение, настройки, точки расширения, известные ограничения; читается без переписки с нами.
• Регламент обновлений — порядок работ при обновлении ядра или соседних плагинов: что проверяем, на каком окружении и как возвращаемся к предыдущей версии.
• Журнал изменений — что и зачем менялось в каждом релизе и какие правки затронули поведение на боевом контуре.
• Инструкции для команды — включение и отключение плагина, где смотреть логи, что делать при типовых сбоях.
• Набор проверок — набор тестов и чек-лист приёмки, по которым принимающая сторона сама подтверждает работоспособность после обновления.

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

Кейс: синхронизация каталога с внешней системой

Что было до внедрения

Каталог клиента — 12 400 позиций, а прайс поставщика приходил файлом дважды в день. Менеджер переносил его руками: полная сверка занимала 3-4 часа, а позиции, которых не было в новой выгрузке, оставались с прошлого прогона. Цены на сайте отставали до 20 часов, остатки расходились — по внутренним замерам 6-7% товаров показывались доступными при пустом складе. Каждую неделю это давало одну-две отмены уже оплаченных заказов и разбор с клиентом.

Что изменили и что получилось

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

Метрики до и после разошлись заметно: полный проход каталога занимает 40 секунд, обмен запускается каждые 15 минут и переносит только изменения. Доля ручных операций упала со 100% до нуля, расхождения остатков — ниже 0,5%, цена на сайте обновляется в пределах десяти минут после правки у поставщика. Отмены по причине «нет в наличии» прекратились, а журнал обмена отвечает на вопрос, что и когда менялось: при спорной ситуации видно источник данных и время записи.

Чем обработчик на событии отличается от вызова в шаблоне?

Обработчик события — это плагин, который подписывается на системное событие и вызывается самим ядром в момент, когда событие произошло. Вызов в шаблоне — сниппет, вставленный в конкретное место шаблона или чанка: логика исполняется там, где её поставил верстальщик, и только на тех страницах, где этот шаблон применён.

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

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

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

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

Технические сомнения: что уточняем перед стартом

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

Кто отвечает за поддержку кастомного кода?

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

Какие доступы нужны на старте?

Тестовый контур, копия базы, доступ к админке, файловой структуре и логам. Всё воспроизводим на копии: если сценарий ломается, живой сайт остаётся нетронутым.

Как тестируется логика плагина?

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

Возьмётесь доработать чужой плагин?

Сначала аудит: фиксируем зависимости от версии CMS и сторонних дополнений, затем вносим правки, сохраняя текущее поведение. Рискованные участки переписываем постепенно, а не одним изменением.

Обсудим задачу: что уточнить перед оценкой

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

• Точки расширения: на какие события подписывается плагин, в каком порядке они срабатывают относительно штатной логики и что происходит при откате операции.
• Ожидаемое поведение: что именно плагин меняет в выводе или в данных, какие сценарии считаются корректными, а какие — ошибкой.
• Состояние проекта: актуальная ветка MODX, набор сниппетов, чанков, шаблонов и уже установленных дополнений — чтобы не конфликтовать с существующей логикой.
• Интеграции: внешние сервисы, направления обмена, форматы данных и периодичность вызовов.
• Нагрузка: объём контента, число одновременных операций, где нужны кэширование и отложенная обработка.
• Доступы: тестовый контур, репозиторий, права на выкладку и на чтение конфигураций.
• Критерии приёмки: какие проверки должны проходить на тестовом контуре до переноса на боевой.

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