Кастомний модуль Craft CMS: де логіка проєкту ламається
Штатна модель Craft CMS розрахована на передбачувані сутності: записи, категорії, поля, права за ролями. Поки проєкт живе в цих рамках, усе працює без втручання в ядро.
Проблеми починаються там, де бізнес-логіка перестає бути типовою — і це не про «мало плагінів», а про те, що сама модель даних не описує реальні відносини.
Перше вузьке місце — нестандартна логіка прав. Вбудовані ролі оперують розділами й групами записів, але не відповідають на питання вигляду «редактор бачить лише свої матеріали всередині свого підрозділу» або «погоджувач може правити поле, але не публікувати».
Починаються обхідні шляхи через костильні перевірки в шаблонах, і кожне нове правило доводиться вписувати вручну в десяток місць.
Друге — зв'язки між сутностями. Коли запис має посилатися на кілька пов'язаних об'єктів з різними типами відносин і умовами відображення, штатних полів Relations не вистачає: втрачається контекст зв'язку, з'являються дублі, а вибірки стають важкими.
Те саме з інтеграціями з внутрішніми системами — складом, CRM, білінгом: обмін потребує проміжної логіки, якої в CMS просто немає.
Кастомний модуль Craft CMS вирішує це на рівні архітектури: власні таблиці та сервіси для зв'язків, окремий шар правил доступу, обробники подій для інтеграцій. Ядро залишається недоторканим — оновлення CMS не ламають вашу логіку. Розбираємо, як це закривається на практиці.
Що дає модуль: швидкість, відмовостійкість, контроль
Нестандартна логіка, розмазана по шаблонах і плагінах, дає три типові проблеми: важкі запити на публічних сторінках, відмови при оновленні ядра і непрозорі права доступу. Винесення цієї логіки в окремий модуль Craft CMS вирішує їх на рівні архітектури, а не точковими правками.
Швидкість відгуку
Модуль реєструє власні маршрути і сервіси, тому важкі вибірки йдуть з шаблонів у контрольований шар з кешуванням і лінивим завантаженням зв'язків. На практиці час відповіді каталогу і особистих кабінетів падає в рази, а пікові навантаження перестають упиратися в рендер шаблону.
Усунені класи відмов
Логіка в модулі не залежить від структури шаблонів і порядку плагінів — оновлення ядра або зміна теми її не ламають.
Окремо закривається клас відмов, пов'язаних з гонками при записі: транзакції та черги виносять важкі операції з користувацького запиту, і частково застосованих змін у базі не залишається.
Передбачуваність оновлень
Модуль ставиться і оновлюється як окремий пакет з міграціями схеми і версіонуванням. Оновлення ядра перестає бути подією з ручною перевіркою кожного шаблону: несумісність виявляється на етапі міграцій, а не на проді.
Контроль доступу
Права описуються декларативно — за ролями, розділами і окремими діями, а не розкиданими перевірками в шаблонах. Це дає єдину точку аудиту: видно, хто і що може, і будь-яка зміна політики доступу проходить рев'ю, а не правиться в десяти місцях.
Ефект накопичується: чим більше нестандартних сценаріїв живе в модулі, тим менша поверхня для регресій при кожному релізі.
Формати реалізації: вбудований модуль, плагін, зовнішній сервіс
У Craft CMS кастомна логіка живе в трьох різних місцях, і вибір між ними визначає, як проєкт буде супроводжуватися далі.
Вбудований модуль — це код усередині проєкту: він бачить моделі, події та черги ядра напряму, ставиться разом із застосунком і не потребує окремого релізного циклу.
Плагін — самостійний пакет із власним життєвим циклом: його можна перевикористовувати між проєктами та оновлювати незалежно, але кожне звернення до внутрішніх API Craft потрібно тримати в сумісних межах.
Зовнішній сервіс виносить логіку за межі застосунку і спілкується з ним по мережі — це знімає навантаження з PHP-процесів, але додає мережеву відмову, затримку та окремий контур розгортання.
| Варіант | Коли підходить | Обмеження архітектури |
|---|---|---|
| Вбудований модуль | Логіка специфічна для одного проєкту, потрібен прямий доступ до подій і моделей ядра | Живе тільки в цьому проєкті, оновлюється разом із ним, перевикористати в іншому сайті не можна |
| Плагін | Функціональність повторюється на кількох проєктах або потрібна ізоляція версій | Потребує стабільного публічного API, при мажорному оновленні Craft потрібно підтримувати сумісність |
| Зовнішній сервіс | Важкі обчислення, інтеграції, робота із зовнішніми системами та власними даними | Мережева відмова та затримка, окремі доступи, логування й моніторинг, синхронізація стану |
На практиці межі часто комбінують: модуль тримає бізнес-правила та події, зовнішній сервіс забирає важке, а плагін з'являється, коли рішення довело цінність і його пора переносити між проєктами.
Ми фіксуємо цей вибір на етапі проєктування — від нього залежать схема розгортання, стратегія оновлень і те, скільки коштує підтримка через рік.
Етапи впровадження: від аудиту логіки до передачі команді
Роботу починаємо з аудиту логіки: розбираємо, як задача вирішується зараз — плагінами, ручними операціями редактора або правками в шаблонах. На цьому кроці фіксуємо точки, де логіка дублюється, і місця, які ламаються при оновленні ядра. Результат аудиту — карта залежностей і список того, що модуль має взяти на себе.
- Аудит поточної логіки. Збираємо реальні сценарії роботи редакторів і адміністраторів, дивимося, які дані та події зачіпає задача. Визначаємо межі модуля: що переходить у нього, що залишається в ядрі.
- Проєктування схеми модуля. Описуємо структуру: сутності, поля, зв'язки, права доступу за ролями. Окремо проєктуємо міграції — щоб структура даних розгорталася на будь-якому середовищі однією командою.
- Налаштування та збірка. Реалізуємо логіку, виносимо конфігурацію у файли проєкту, підключаємо модуль без правок ядра. Так оновлення платформи не затирає доопрацювання.
- Перевірка сценаріїв. Проганяємо модуль на реальних даних і граничних випадках: порожні вибірки, масові операції, одночасна робота кількох редакторів. Кожен сценарій закриваємо тестом.
- Приймання на стенді. Показуємо роботу на копії бойового контенту, звіряємо поведінку з вихідною логікою. Правки вносимо до викату, а не після.
- Передача команді. Віддаємо документацію щодо структури та налаштувань, інструкцію для редакторів, порядок відкату. Проводимо розбір із вашими розробниками, щоб модуль можна було розвивати без нас.
Кожен етап закінчується артефактом, який можна перевірити: карта залежностей, схема даних, набір тестів, інструкція з експлуатації. Так на виході ви отримуєте не «чорну скриньку», а передбачуваний компонент із зрозумілою зоною відповідальності.
Що замовник отримує на руки: конфігурації, схеми, регламенти
Передаємо не «працюючий код на нашому сервері», а комплект, з яким ваша команда або інший підрядник продовжить роботу без нас. Нижче — що саме фіксується в передачі за кастомним модулем.
- Конфігурації модуля — файли налаштувань з описом усіх параметрів: які поля та типи контенту модуль реєструє, які події перехоплює, які значення за замовчуванням. Налаштування винесені з коду, тому поведінка змінюється правкою конфігурації, а не доопрацюванням.
- Схеми зв'язків — карта того, як модуль взаємодіє з ядром системи, іншими модулями та зовнішніми сервісами: точки розширення, порядок викликів, місця, де логіка залежить від сторонніх даних.
- Політики доступу — матриця прав за ролями: хто бачить розділи модуля, хто змінює налаштування, хто лише читає дані. Окремо описано перевірки на стороні сервера, щоб права не обходилися через прямий запит.
- Міграції та структура даних — сценарії зміни схеми сховища з версіонуванням, щоб оновлення не ламало вже накопичені записи та коректно відкочувалося.
- Документація модуля — призначення, публічні методи, приклади викликів, обмеження та відомі припущення. Достатньо, щоб новий розробник розібрався без листування з автором.
- Регламенти оновлення та відкату — порядок викочування змін, перевірки перед релізом, точки повернення до попередньої версії та умови, за яких відкат запускається автоматично.
- Інструкція з експлуатації — типові операції: увімкнення та вимкнення модуля, ротація ключів, читання логів, реакція на збої зовнішніх сервісів.
Комплект закриває головний ризик кастомної розробки — залежність від одного виконавця. Будь-який інженер, знайомий зі стеком, піднімає модуль на чистому середовищі за документацією та продовжує розвиток. Опишіть задачу — повернемося з оцінкою та планом передачі.
Кейс: як модуль прибрав ручні операції та прискорив відгук
Замовник — мережа з кількох десятків регіональних представництв — вів каталог товарів і залишки на Craft CMS. Контент-менеджери оновлювали ціни та наявність вручну: вивантаження з облікової системи надходило файлом, далі порядкове перенесення, звірка, публікація. На піку — кілька сотень правок на день, і кожна помилка в залишках потрапляла на вітрину.
Ми розібрали вузьке місце: проблема була не в обсязі даних, а у відсутності шару між обліковою системою та редактором.
Зібрали кастомний модуль, який приймає вивантаження за розкладом, зіставляє записи за зовнішнім ідентифікатором і оновлює поля через штатний API Craft — без прямих запитів до бази та без обходу кешу.
Конфлікти версій (хто правив останнім) модуль вирішує за міткою часу і пише їх у журнал, а не «мовчки» перезаписує.
Що було до і що стало після
| Метрика | До | Після |
|---|---|---|
| Оновлення каталогу | вручну, раз на добу | за розкладом, кожні 15 хвилин |
| Правок руками на день | кілька сотень | одиниці (лише нестандартні випадки) |
| Помилки в залишках | регулярні, ловилися постфактум | відсікаються на прийманні даних |
| Відгук вітрини на зміну | години | хвилини |
Окремо закрили відкат: кожне оновлення пише знімок змінених записів, тому невдале вивантаження можна скасувати однією операцією, не відновлюючи базу повністю. Ручні операції з процесу пішли — менеджери займаються контентом, а не звіркою таблиць.
Чим кастомний модуль відрізняється від плагіна з маркетплейсу?
Плагін з маркетплейсу — це готове рішення під типовий сценарій: форма зворотного зв'язку, простий імпорт, базова інтеграція. Поки завдання збігається з тим, що автор заклав у плагін, усе працює передбачувано.
Проблема починається там, де бізнес-логіка відходить убік: потрібен нестандартний розрахунок, власна схема прав доступу, зв'язка кількох сутностей в один процес. Тоді плагін або не закриває завдання, або закриває його частково — і навколо нього починають рости обхідні рішення.
Кастомний модуль пишеться під конкретний процес, тому контроль логіки залишається за командою, а не за стороннім автором. Ми самі визначаємо структуру даних, порядок операцій, точки розширення і те, як модуль поводиться при помилках.
Це принципова різниця: у плагіні ви приймаєте чужі рішення як даність, у модулі — проєктуєте їх під своє завдання.
Залежності — друге джерело ризиків. У плагіна завжди є ланцюжок: автор, його строки підтримки, сумісність з актуальною гілкою CMS, сторонні бібліотеки всередині.
При оновленні ядра такий ланцюжок рветься в найнезручніший момент, і ви або чекаєте патч від автора, або заморожуєте оновлення. Кастомний модуль ми тримаємо на підтримуваних інтерфейсах ядра і оновлюємо разом з ним — без очікування третьої сторони.
Звідси й різний клас ризиків при оновленні CMS. Плагін може зламатися на мажорному апдейті, і полагодити його без доступу до вихідників не можна. Модуль ми супроводжуємо самі: бачимо, що змінилося в ядрі, і правимо точково, не торкаючись решти системи.
Тому для процесів, які дають бізнесу перевагу, модуль майже завжди вигідніший — ви не ділите контроль над логікою з чужою командою.
Технічні сумніви: оновлення, безпека, відкат
Кастомний модуль живе в кодовій базі проєкту, а не в ядрі системи, тому оновлення CMS його не ламають: розширення підключаються через штатні точки розширення, а не правкою вендорних файлів.
Під час мажорного оновлення ми проганяємо модуль на тестовому стенді з копією бойових даних — якщо контракт точок розширення змінився, адаптація займає години, а не тижні переписування з нуля.
Доступи розмежовуємо за ролями та правами всередині самої CMS: контент-менеджер бачить лише свої розділи, адміністратор — налаштування модуля, зовнішні інтеграції ходять за окремими ключами з обмеженим набором операцій.
Усі дії з даними пишуться в журнал — видно, хто і коли змінював запис, це ж допомагає під час розбору інцидентів.
Що буде, якщо оновлення CMS все-таки зламає модуль?
Оновлення ставимо спочатку на копію бойового середовища, а не на прод. Якщо модуль не проходить перевірки, реліз CMS відкочується на попередню гілку, а модуль адаптується окремо — бойовий сайт у цей час працює без простою.
Перед кожним оновленням знімаємо знімок бази та файлів, тому повернення до робочого стану займає хвилини.
Як відкотити зміни, які вніс модуль?
Зміни контенту версіонуються: у кожного запису зберігається історія ревізій, і будь-яку можна відновити точково, не відкочуючи все інше.
Для змін схеми даних готуємо зворотні міграції — вони виконуються тією ж командою розгортання, що й прямі, і перевіряються на стенді до продакшену.
Модуль сумісний із сторонніми розширеннями?
Так, якщо вони використовують штатні точки розширення, а не перевизначають ядро. Конфлікти зазвичай виникають на рівні спільних таблиць або перехоплення одних і тих самих подій — такі місця ми виявляємо на етапі проєктування і розводимо за пріоритетами обробки. Перед впровадженням проганяємо сценарій із повним набором розширень замовника.
Хто має доступ до сервера та бази після здачі?
Доступи залишаються у замовника: ми працюємо через окремі облікові записи з обмеженими правами та журналюванням, а не через спільний адміністративний вхід.
Це означає, що при зміні підрядника або інженера доступ відкликається однією операцією, без ризику втратити контроль над системою.
Обговоримо задачу: повернемося з оцінкою та планом
Щоб повернутися з оцінкою та планом, а не із загальними словами, нам потрібен мінімум вхідних даних щодо задачі.
Кастомний модуль Craft CMS майже завжди виростає з конкретного вузького місця: нестандартний розрахунок знижок, синхронізація каталогу із зовнішньою системою, ролі та права, яких немає в базовому наборі, або власний тип контенту зі складною логікою публікації.
Чим точніше ви опишете, що зараз відбувається і що має відбуватися, тим менше припущень ми закладемо в оцінку.
Для старту достатньо такого:
- опис бізнес-процесу: хто і що робить, де зараз ламається або робиться вручну;
- приклади даних: вивантаження, скриншоти адмінки, зразки полів і зв'язків між сутностями;
- як задача вирішується сьогодні — зовнішнім сервісом, таблицями, роботою менеджера;
- вимоги до доступів: які ролі мають бачити й змінювати дані, що лише читати;
- інтеграції: з чим модуль обмінюється даними і в який бік;
- обмеження: терміни, прив'язка до релізів, що не можна ламати в поточному сайті;
- контакт людини, яка прийме роботу й підтвердить логіку.
У відповідь ми повертаємо оцінку та план: розбивку на етапи з трудозатратами, чернетку технічного завдання, схему даних і точок інтеграції, список ризиків і припущень, а також порядок викатки — спочатку на тестовому середовищі, потім на бойовому з можливістю відкату.
Якщо під час розбору випливають неочевидні залежності, фіксуємо їх окремо, щоб старт робіт не перетворився на перегляд термінів.
Опишіть задачу у вільній формі — цього достатньо, щоб повернутися з оцінкою та планом.
