Свой компонент для MODX: какой подход выбрать

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

Сначала определите, что именно вы называете компонентом

В MODX этим словом часто называют четыре разных решения. Они решают разные задачи и имеют разную цену поддержки.

• Сниппет — PHP-логика, которую можно вызвать из ресурса или другого элемента MODX. Подходит для выборки данных, расчёта, формирования списка или интеграции без отдельного интерфейса.
• Плагин — обработчик системных событий. Он реагирует на сохранение ресурса, загрузку страницы, авторизацию пользователя или другое событие, если нужная точка расширения есть в MODX.
• Расширение менеджера — отдельная страница, дерево, форма или панель внутри административной части. Это вариант для операторов, редакторов и менеджеров.
• Extra-компонент — устанавливаемый пакет с моделями данных, процессорами, контроллерами менеджера, лексиконами, разрешениями и ресурсами. Он объединяет несколько предыдущих частей в самостоятельный продукт.

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

¹ Extra-компонент — расширение MODX, которое устанавливается через транспортный пакет и может включать код, схему данных, настройки, lexicon-строки и элементы интерфейса.

Главный вопрос не в том, умеет ли MODX выполнить ваш PHP-код. Вопрос в том, сможете ли вы обновить, ограничить и удалить этот код через полгода.

Четыре подхода и их цена

Подход 1: сниппет для узкой задачи

Сниппет — хороший старт, когда входные данные приходят из параметров вызова, ресурсов MODX или заранее известных настроек. Например, сайт должен показать связанные материалы, посчитать стоимость доставки или отправить данные во внешний сервис.

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

Что проверить перед выбором

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

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

Подход 2: плагин для реакции на событие

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

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

Когда плагин превращается в плохой выбор

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

Подход 3: отдельная страница менеджера

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

Такой вариант оправдан, если операций мало, структура данных уже живёт в MODX или внешней системе, а интерфейс не должен становиться универсальной системой управления. Доступ к странице нужно связать с разрешениями пользователей, а опасные действия — защитить подтверждением и понятным результатом операции.

Не прячьте бизнес-логику в JavaScript панели. Интерфейс может отправить запрос напрямую, но проверка прав, валидация и изменение данных должны выполняться на сервере. Административная форма не является границей безопасности.

Подход 4: полноценный extra-компонент

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

Из чего состоит минимальная архитектура

• Модель данных — таблицы, связи, поля и правила удаления. Схема должна быть описана так, чтобы установщик мог создать её на чистом проекте.
• Процессоры — серверные операции менеджера: создание, чтение, изменение, удаление, импорт и другие действия. Каждый процессор должен проверять входные данные и права.
• Контроллеры интерфейса — страницы и формы менеджера. Они не должны самостоятельно дублировать правила валидации из серверного слоя.
• Лексикон — строки интерфейса и сообщения об ошибках. Это упрощает перевод и замену текста без поиска по PHP-файлам.
• Разрешения и политики — кто видит раздел, кто может изменять записи, кто запускает импорт или удаление.
• Транспортный пакет — способ установки и обновления расширения на другом окружении.

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

Когда что выбирать

Выбор можно сделать по четырём вопросам.

1. Нужна только обработка входных данных. Начните со сниппета, если нет собственного состояния и интерфейса.
2. Логику нужно запускать при событии MODX. Используйте плагин, но оставьте в нём только связку с событием.
3. Нужна одна административная операция. Делайте расширение менеджера, если отдельная модель и сложные права не нужны.
4. Функциональность будет жить, обновляться и расширяться. Сразу проектируйте extra-компонент с транспортной установкой и версией пакета.

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

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

Логика хранится только в админке

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

Права проверяются только в интерфейсе

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

Схема данных меняется вручную

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

Компонент зависит от конкретного проекта

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

Не учитывается версия MODX

MODX Revolution 2.8.x и 3.x нельзя считать одной и той же средой. Меняются требования к PHP, структура кода, совместимость расширений и поведение отдельных частей менеджера. Зафиксируйте целевую ветку в документации компонента и тестируйте установку на чистом экземпляре именно этой версии.

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

Составьте короткую карту функциональности: сущности, операции, события, роли и внешние зависимости. Затем соберите самый маленький рабочий прототип. Если он помещается в один сниппет и не требует собственной модели, не усложняйте решение. Если уже появились записи, права, импорт и несколько административных экранов, закладывайте extra-компонент сразу и проверяйте его установку на чистом MODX 3.x.

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