# Операции и состояния модуля

← [К разделу «Модули»](README.md)

Управляемый модуль проходит состояния `available`, `enabled` и `disabled`.
Наличие папки ещё не означает, что код активен.

## Операции в панели управления

| Операция | Что происходит |
| --- | --- |
| Установить | Проверяются зависимости, применяются миграции и install-handler, синхронизируются права, модуль включается. |
| Обновить | Выполняются новые миграции и update-handler; enabled/disabled сохраняется. |
| Выключить | Маршруты, меню и контекстные хуки отключаются; таблицы и настройки сохраняются. |
| Включить | Проверяются зависимости, затем снова подключаются runtime-вклады. |
| Деинсталлировать | Проверяются зависимые модули и типы полей, выполняется uninstall, удаляются данные, настройки, секреты и права. |
| Переустановить | Полностью удаляет модуль с его данными и сразу выполняет чистую установку. |
| Восстановить | Повторяет оборванную операцию; уже применённые миграции пропускаются по журналу. |
| Удалить файлы | После деинсталляции физически удаляется разрешённый административный модуль или составной пакет. |

Все изменяющие операции требуют CSRF и административного права. На production
они выполняются из **Система → Модули**, CLI не требуется.

## Зависимости

```php
'requires' => array('commerce', 'users'),
```

- установка и включение невозможны без установленных и включённых зависимостей;
- выключение или деинсталляция блокируются активными зависимыми модулями;
- порядок установки определяет менеджер модулей;
- циклические зависимости недопустимы.

## Выключенный модуль

Чтобы существующие данные не стали нечитаемыми, остаются общие config/settings,
файлы и сервисы верхнего уровня, определения событий и обработчики типов полей.
Не подключаются административные и публичные маршруты, меню, assets и
контекстные обработчики из секций `admin`/`public`.

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

## Ограничения удаления

Деинсталляция остановится, если:

- от модуля зависит другой включённый пакет;
- его тип поля используется хотя бы в одной рубрике;
- uninstall-handler завершился ошибкой.

Физическое удаление файлов является отдельной операцией. Оно разрешено только
для деинсталлированного модуля с `package.removable = true`. Допустимы два
защищённых корня: `<admin-directory>/modules/<Folder>` для самостоятельного
административного модуля и `modules/<code>` для составного пакета. Вместе с
папкой очищаются секреты, настройки, ledger миграций и записи состояния модуля.
Путь проверяется через `realpath`; удалить родительский каталог или встроенный
раздел ядра этим действием нельзя.

## Переустановка и частичная ошибка

`reinstall` вызывает полную деинсталляцию и удаляет пользовательские данные
модуля. Перед ним нужен backup. Если операция оборвалась, модуль получает
состояние `dirty`; runtime не подключается до успешного восстановления.

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