Свой компонент для MODX: рабочие приёмы из практики

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

Сначала определите границы компонента

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

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

Компонент — это не папка с файлами. Это договорённость о том, кто владеет данными, где лежит логика и как её безопасно обновлять.

В примерах ниже речь о MODX Revolution 2.8.x. Перед выпуском проверяйте совместимость с конкретной версией MODX и установленного xPDO: устройство менеджера и детали пакетов могут различаться, особенно при переходе на MODX 3.

Разделяйте точки входа и логику

У компонента обычно есть несколько способов попасть в одну и ту же операцию: страница менеджера, сниппет на сайте, плановая задача. Если в каждом месте повторить работу с данными, со временем обработчики начнут вести себя по-разному.

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

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

Выберите способ запуска по задаче

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

Схема данных: меньше магии, больше миграций

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

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

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

Настройки, языки и интерфейс менеджера

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

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

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

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

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

Порядок проверок перед выпуском:

1. Установите пакет на чистую копию сайта с той же версией MODX, что и целевая среда.
2. Проверьте основной сценарий через каждую точку входа компонента.
3. Повторите установку или обновление и убедитесь, что данные не дублируются и не исчезают.
4. Войдите пользователем с ограниченными правами и попробуйте выполнить защищённое действие.
5. Посмотрите журнал ошибок после успешного сценария и после намеренно некорректного ввода.

Где подход ломается

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

Вторая граница — совместимость. Пакет, который без проверки переносится с MODX 2.8.x на MODX 3, нельзя считать проверенным только потому, что он устанавливается. Сверьте требования зависимостей и инструкции по миграции в документации именно для используемых версий. Отдельно проверьте менеджерский интерфейс, загрузку пакета xPDO и установочные сценарии.

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

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

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

Термин: процессор в MODX — обработчик запроса компонента, который выполняет действие и возвращает результат; это не то же самое, что сниппет, который обычно используют для вывода на странице.