Свой компонент для MODX: как заложить основу без переделок

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

Сначала решите, что именно вы строите

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

Зафиксируйте минимальный состав до разработки:

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

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

Разделите код, данные и файлы

Располагайте файлы расширения в его собственных каталогах, а не в системных директориях MODX. Для компонента обычно разделяют серверную часть в core/components/имя_компонента и публичные файлы в assets/components/имя_компонента. В первой держат код и служебные ресурсы, во второй — то, что должно быть доступно сайту, например стили и скрипты. Конкретную структуру каталогов выберите под тип расширения и отразите в пакете.

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

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

Проверка хорошей структуры проста: компонент можно установить на чистую копию сайта, и ему не нужны файлы или ручные настройки, о которых знает только разработчик.

Соберите установку как часть продукта

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

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

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

Настройки и доступы — не мелочи

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

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

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

Что проверить до передачи компонента

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

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

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

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

Не используйте в примерах имена API, которые не сверили с документацией именно для своей версии. MODX Revolution 2.x и 3.x — не одно и то же окружение для разработки расширений. Если компонент должен работать на обеих ветках, проверьте совместимость каждого используемого класса и способа сборки отдельно и опишите результаты тестов. Не объявляйте поддержку старой версии только потому, что пакет удалось установить.

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

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

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