> For the complete documentation index, see [llms.txt](https://docs.johncms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.johncms.com/10.0/moduli/ustanovka-modulei.md).

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

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

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

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

* **composer** — `composer require вендор/модуль`. Пакет с типом `johncms-module` остаётся в `vendor/`, система находит его там сама;
* **zip-архив** — через панель администратора или командой; архив распаковывается в `modules/<вендор>/<модуль>/`;
* **вручную** — папка модуля кладётся в `modules/<вендор>/<модуль>/` по FTP.

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

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

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

* **установленные** — те, что работают (или выключены);
* **обнаруженные** — файлы на диске, установка не выполнялась;
* **требующие внимания** — сломанные, несовместимые и те, чья установка не была доведена до конца, с объяснением причины.

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

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

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

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

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

## В консоли

```bash
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   # снять и удалить данные
```

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

```bash
php system/bin/console auth:sync-roles
```

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

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

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

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

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

* **системный модуль** (панель администратора) — иначе включить его обратно будет некому;
* **модуль, от которого зависит другой установленный** — система назовёт, кто именно его держит.

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

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

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

```php
const MODULES_SAFE_MODE = false;
```

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

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