Установка и удаление модулей

Модуль — это код, который выполняется на сайте с правами сайта. Ставьте только то, чему доверяете.

Откуда берутся модули

Файлы модуля попадают на сайт одним из трёх способов, и системе всё равно, каким именно:

• composer — composer require вендор/модуль. Пакет с типом johncms-module остаётся в vendor/, система находит его там сама;

• zip-архив — через панель администратора или командой; архив распаковывается в modules/<вендор>/<модуль>/;

• вручную — папка модуля кладётся в modules/<вендор>/<модуль>/ по FTP.

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

В панели администратора

Раздел Модули (/admin/modules) показывает три группы:

• установленные — те, что работают (или выключены);

• обнаруженные — файлы на диске, установка не выполнялась;

• требующие внимания — сломанные и несовместимые, с объяснением причины.

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

Чтобы открыть раздел, нужно право system.modules.manage. Ни одна встроенная роль его не несёт: установка модуля — это исполнение чужого кода, и такое право выдают осознанно. Супер-администратору доступно всё и без него.

Установка из файла

Кнопка Установить модуль из файла принимает zip-архив, внутри которого одна папка с файлом module.php. Перед распаковкой архив проверяется: пути, ведущие за пределы модуля, символические ссылки, слишком большой размер, отсутствие манифеста — всё это отклоняется с объяснением, и на диск ничего не попадает.

Если модуль с таким ключом уже установлен, архив считается обновлением: прежняя версия переносится в data/backups/, затем выполняются миграции и хук обновления.

В консоли

php system/bin/console module:list                       # что система знает о модулях
php system/bin/console module:install вендор/модуль       # установить (--demo — с демо-данными)
php system/bin/console module:install --from=архив.zip     # установить или обновить из архива
php system/bin/console module:enable вендор/модуль         # включить обратно
php system/bin/console module:disable вендор/модуль        # выключить, сохранив данные
php system/bin/console module:update вендор/модуль         # после подмены файлов
php system/bin/console module:uninstall вендор/модуль      # снять с сайта, данные оставить
php system/bin/console module:uninstall вендор/модуль --purge   # снять и удалить данные

После установки модуля, объявляющего свои права доступа, выполните:

php system/bin/console auth:sync-roles

Права появляются у ролей только после этого: контейнер собирается до того, как модуль появился, поэтому в момент установки система о его правах ещё не знает.

Что означает каждое действие

Действие	Что происходит с файлами	Что происходит с данными
Установка	остаются на месте	выполняются миграции, запускается install() модуля
Выключение	остаются на месте	таблицы и данные не тронуты, модуль просто не загружается
Обновление	уже заменены	выполняются новые миграции и хук обновления
Удаление	остаются на месте	таблицы и права остаются
Удаление с очисткой	остаются на месте	миграции откатываются, права снимаются (со снимком в data/backups/)

Файлы не удаляются никогда: их принёс composer, архив или человек, и убирает их тот же, кто принёс. Удаление модуля через composer remove предупредит, что данные останутся, и подскажет сначала выполнить module:uninstall --purge.

Что нельзя выключить

• системный модуль (панель администратора) — иначе включить его обратно будет некому;

• модуль, от которого зависит другой установленный — система назовёт, кто именно его держит.

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

Если модуль сломал сайт

В файле config/constants.php есть константа:

const MODULES_SAFE_MODE = false;

Поставьте true — загрузятся только модули, входящие в поставку CMS, а всё установленное дополнительно будет пропущено. Сайт и панель администратора продолжат работать, модуль можно будет удалить, после чего режим выключается обратно.

Список установленного хранится в config/autoload/modules.local.php. Файл генерируется системой, но его можно править руками — это способ вернуть сайт, когда панель недоступна. Учтите, что запись в файле только объявляет модуль установленным: миграции при этом не выполняются, поэтому обычный путь — команда module:install.