# shef.options

> фундамент: настройки, трейты, компоненты

Служебный модуль Битрикс24 «коробки». Пользовательских экранов не даёт и
штатное поведение платформы не меняет — это фундамент, на который опираются
остальные модули линейки: слой настроек, базовые классы, трейты, абстракции и
интерфейсы.

Ставится один раз и дальше не требует внимания. Если на портале стоит любой
другой модуль `shef.*`, этот уже нужен.

# Что нужно для установки

| | |
|---|---|
| PHP | 8.2 и выше |
| Главный модуль Битрикс | 22.600.300 и выше |
| Кодировка портала | **только UTF-8** |
| Расширение PHP | `mbstring` |

Портал в CP1251 модуль установить не даст и скажет об этом прямо. Это
сознательное ограничение: поставиться и выдать вместо русского текста мусор
хуже, чем не поставиться.

# Установка

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

## Через Composer

```bash
composer require bxshef/options
```

Модуль развернётся в `bitrix/modules/shef.options/` сам — отдельно ничего
настраивать не нужно.

## Из архива

Скачайте `shef.options.zip` со страницы релиза и распакуйте в `bitrix/modules/`
вашего портала. Внутри архива лежит готовый каталог `shef.options/`, поэтому
после распаковки должно получиться `bitrix/modules/shef.options/` — именно
через точку.

## Дальше — в административном разделе

1. **Настройки → Marketplace → Установленные решения** → найти «[SH] Настройки»
   → **Установить**.
2. Дождаться сообщения «Модуль успешно установлен».
3. Открыть настройки модуля: **Настройки → Настройки продукта → Настройки
   модулей → [SH] Настройки**.
4. Заполнить **«Служебный пользователь»** — это пользователь с правами
   администратора, которого не уволят. Другие модули линейки работают от его
   имени. Как минимум подойдёт пользователь с ID 1.
5. **Сохранить.**

Без четвёртого шага модуль формально стоит, но смежные модули будут работать от
пользователя по умолчанию — это почти всегда не то, что нужно.

# Кто видит модуль

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

Чтобы открыть настройки кому-то ещё: **Настройки → Пользователи → Группы
пользователей** → нужная группа → вкладка **Доступ** → уровень доступа к модулю
«[SH] Настройки».

Если сотрудник говорит, что не видит модуль в списке — начинать надо отсюда, а
не с переустановки.

# Обновление

Обновление — это повторная раскладка файлов: `composer update` или распаковка
нового архива поверх. Настройки модуля живут в базе, поэтому обновление их не
трогает: «Служебный пользователь» останется на месте.

> **Не правьте `.settings.php` на портале.** Это файл модуля, и раскладка
> перетирает его — и `composer update`, и распаковка архива одинаково. Всё, что
> вы там допишете, исчезнет при следующем обновлении без предупреждения.

# Если что-то пошло не так

**Модуля нет в списке решений.** Проверьте, что каталог называется ровно
`bitrix/modules/shef.options` — через точку, строчными. Через дефис или с
заглавными буквами Битрикс его не найдёт.

**Установка отказывается и пишет про UTF-8.** Портал работает в CP1251. Модуль
такие порталы не поддерживает.

**Сотрудник не видит модуль в настройках.** Права. См. раздел «Кто видит
модуль» выше.

**Настройки открылись, но без оформления.** Стили лежат в
`/bitrix/css/shef.options/admin-options.css`. Откройте этот адрес в браузере:
если 404 — файлы не разложились, переустановите модуль; если отдаётся, а
страница всё равно «голая» — это кеш, нужен Ctrl+F5 или сброс автокеширования
в настройках главного модуля. Путь вида `/bitrix/cache/js/s1/...` в консоли
браузера — верный признак, что вы смотрите на кеш.

**Модуль удалили, и смежные модули сломались.** Так и будет: они на него
опираются. Поставьте обратно либо, если модуль отключён намеренно, сделайте
заглушку на вызов:

```php
<?php
if(!\Bitrix\Main\ModuleManager::isModuleInstalled('shef.options'))
{
	class Events
	{
		public static function __callStatic(string $name, array $arguments): mixed
		{
			return null;
		}
	}

	return;
}
```

# Удаление

Удаление из административного раздела убирает только свои файлы — подкаталоги
`shef.options` и `shef-options` в `/bitrix/css` и `/bitrix/js`. Чужое не
трогается.

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

# Документация

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

* [История изменений](https://github.com/bx-shef/options/blob/main/CHANGELOG.md)
* [Installer](https://github.com/bx-shef/options/blob/main/docs/2_installer.md)
* [Опции настроек модуля](https://github.com/bx-shef/options/blob/main/docs/3_options.md)
* [Работа с пользователями](https://github.com/bx-shef/options/blob/main/docs/4_security.md)
* [Утилиты](https://github.com/bx-shef/options/blob/main/docs/5_utils.md)
* [Работа с компонентами](https://github.com/bx-shef/options/blob/main/docs/6_components.md)
* [Паттерны](https://github.com/bx-shef/options/blob/main/docs/7_pattern.md)
* [Тестирование](https://github.com/bx-shef/options/blob/main/docs/8_tests.md)
* [Набор трейтов](https://github.com/bx-shef/options/blob/main/docs/9_traitlist.md)
* [Примеры](https://github.com/bx-shef/options/blob/main/examples/README.md) — запускаемые, в том числе на вашем портале

Весь репозиторий — [bx-shef/options](https://github.com/bx-shef/options).

# Лицензия и поддержка

MIT, см. [LICENSE](https://github.com/bx-shef/options/blob/main/LICENSE).

ИП Шевчик И.С., [bx-shef.by](https://bx-shef.by/) — вопросы и предложения на
offer@bx-shef.by или в [задачи репозитория](https://github.com/bx-shef/options/issues).

::note
Источник: [options/README.md](https://github.com/bx-shef/options/blob/main/README.md) — правки туда, сайт пересобирается сам.
::