Установка дополнений в MODX: ошибки новичков

В MODX Revolution 3.x установка дополнения из репозитория обычно занимает 15–30 минут, если у вас есть доступ к админке, совместимая версия PHP и права на запись в каталоги сайта. Основные ошибки новичков происходят не на кнопке «Установить», а раньше: менеджер не видит пакет, сервер не может подключиться к репозиторию, а после установки сайт продолжает показывать старую версию кэша.

Что подготовить до установки

Инструкция рассчитана на MODX Revolution 3.x. В MODX 2.x названия пунктов и внешний вид менеджера могут отличаться, а совместимость дополнений нужно проверять отдельно.

• Доступ в административную панель MODX с правом управлять дополнениями.
• Резервную копию базы данных и файлов сайта. Минимум — копию каталога с пользовательскими файлами и экспорт базы.
• Версию MODX и PHP. Их можно посмотреть в системной информации или панели хостинга.
• Название дополнения и страницу его разработчика. Сверьте поддерживаемые версии MODX, PHP и список зависимостей.
• Доступ к журналу ошибок PHP и системному журналу MODX, если установка завершится сообщением об ошибке.

Транспортный пакет — архив, который менеджер пакетов MODX скачивает, распаковывает и использует для установки дополнения. В нём могут находиться файлы, настройки, чанки, сниппеты и SQL-операции.

Если дополнение не указало поддерживаемую версию MODX и PHP, установка превращается в эксперимент над рабочим сайтом.

Пошаговая установка из репозитория

1. Проверьте резервную копию. Убедитесь, что архив файлов действительно создан, а база данных экспортирована без ошибок. Не устанавливайте новое дополнение на единственный рабочий экземпляр сайта. Проверка: вы можете назвать место хранения копии и знаете, как восстановить её на тестовом сайте.
2. Сверьте совместимость. На странице дополнения найдите требования к версии MODX, PHP и зависимостям. Отдельно проверьте дату последнего обновления: старый пакет может формально скачиваться, но использовать API или PHP-синтаксис, которых нет в вашей системе. Проверка: версия сайта и PHP попадают в диапазон, указанный разработчиком дополнения.
3. Откройте менеджер дополнений. В административной панели перейдите в раздел Extras → Installer. Если интерфейс отображается частично или пункт не открывается, сначала проверьте журнал ошибок и права пользователя, а не повторяйте установку несколько раз. Проверка: открывается страница установщика со списком пакетов и действиями для загрузки дополнений.
4. Обновите список пакетов. Запустите обновление списка доступных дополнений и дождитесь завершения запроса. Если список пуст, это ещё не доказывает, что репозиторий не содержит нужный пакет: причиной могут быть DNS, исходящие подключения, сертификат или ошибка самого провайдера. Проверка: в менеджере отображается актуальный список или понятное сообщение об ошибке подключения.
5. Найдите дополнение по точному имени. Не выбирайте пакет только по похожему названию. Сравните имя разработчика, описание, поддерживаемую ветку MODX и зависимости. Два пакета с похожими названиями могут решать разные задачи или иметь несовместимые версии. Проверка: карточка пакета совпадает со страницей проекта, а у дополнения есть подходящая версия.
6. Скачайте пакет. Запустите загрузку из карточки дополнения и дождитесь, пока пакет появится в списке загруженных. Не закрывайте вкладку сразу после нажатия кнопки: при медленном сервере архив может ещё сохраняться в хранилище пакетов. Проверка: у пакета появляется действие установки, а не только повторной загрузки.
7. Запустите установку и прочитайте запросы. Нажмите установку, подтвердите зависимости и внимательно прочитайте предупреждения. Если менеджер предлагает установить несколько связанных пакетов, не отменяйте зависимость без понимания последствий. Проверка: установщик сообщает об успешном завершении, а пакет получает статус установленного.
8. Очистите кэш MODX. После установки очистите системный кэш через административную панель. Это нужно, чтобы MODX заново собрал конфигурацию, меню и другие кэшируемые данные. Проверка: в административной панели появляется функциональность дополнения, а страница сайта отдаёт новый результат после обновления.
9. Проверьте работу на отдельном сценарии. Откройте страницу или форму, ради которой ставили дополнение. Посмотрите журнал ошибок, сетевые запросы браузера и логи PHP. Проверка: тестовый сценарий работает, а в логах не появились новые фатальные ошибки.

Частые ошибки новичков

Пакет не находится в репозитории

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

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

Загрузка заканчивается ошибкой

Сообщения вроде «Could not download package», «cURL error» или «Unable to connect» обычно указывают на сетевую проблему, ограничение PHP или недоступность самого репозитория. Сначала проверьте, открывается ли страница репозитория с сервера, а не только с вашего компьютера. Затем сравните требования дополнения с версией PHP и параметрами хостинга.

Установка остановилась на правах доступа

MODX должен иметь возможность записать транспортный пакет, распаковать его и обновить кэш. При нехватке прав появляются сообщения вроде «Permission denied», «Failed to open stream» или «Could not write file». Исправляйте владельца и права через настройки хостинга или администратора сервера, а не выдавайте всему сайту максимальные права.

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

Зависимость не устанавливается

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

После установки сайт показывает старое поведение

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

Если не получилось

• «Package not found». Проверьте имя, источник пакетов и актуальность списка. Если ошибка относится ко всем дополнениям, проверяйте соединение сервера с репозиторием.
• «cURL error» или «Could not resolve host». Проверьте DNS, исходящие HTTPS-подключения и сертификаты на сервере. Эти настройки исправляют на уровне хостинга.
• «Permission denied». Исправьте владельца и права на каталог хранения пакетов и кэш через панель хостинга или с помощью администратора сервера.
• «Dependency not met». Найдите требуемую зависимость в описании пакета, установите совместимую версию и повторите операцию после резервного копирования.
• Белая страница или HTTP 500 после установки. Не удаляйте файлы дополнения вслепую. Откройте PHP-лог и журнал MODX, отключите проблемный пакет безопасным способом и восстановите сайт из копии, если ошибка затронула рабочие страницы.

Что проверить после установки

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

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

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

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