Розробка кастомного плагіна 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, набір сніпетів, чанків, шаблонів і вже встановлених доповнень — щоб не конфліктувати з наявною логікою.
• Інтеграції: зовнішні сервіси, напрямки обміну, формати даних і періодичність викликів.
• Навантаження: обсяг контенту, кількість одночасних операцій, де потрібні кешування та відкладене оброблення.
• Доступи: тестовий контур, репозиторій, права на викладку та на читання конфігурацій.
• Критерії приймання: які перевірки мають проходити на тестовому контурі до перенесення на бойовий.

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