README

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

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

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


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

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

Установка

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

Для ИИ-агентов

Навыки к модулю — как устроены настройки, трейты, компоненты и как сделать агент, опцию или ajax-действие по канону — лежат в отдельном репозитории bx-shef/skills. В проект их ставит

npx skills add bx-shef/skills

Команда раскладывает навыки в .agents/skills/ и создаёт skills-lock.json. Его коммитят. Сами навыки в проекте не правят: замечания отправляют отзывом, навык shef-feedback.

Через Composer

composer require bxshef/options

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

Из архива

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

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

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

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

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

С 3.2.0 модуль даёт команду для bitrix.php: после выкладки файлов модулей (git, Composer) она ставит неустановленные модули линейки shef.* и доставляет обновление установленным.

cd /home/bitrix/www/bitrix
php bitrix.php shef:modules:sync                    # план: что поставит и что обновит
php bitrix.php shef:modules:sync --yes              # выполнить
php bitrix.php shef:modules:sync --yes -m shef.currency   # только он и его зависимости

Запускать от пользователя веб-сервера (на BitrixVM — bitrix): файлы, которые раскладывают установщики, должны принадлежать ему. От root команда отказывается (обойти — --allow-root). Для bitrix.php у портала должен быть настроен Composer (документация Bitrix Framework, «Консольные команды»).

Что делает:

ищет модули shef.* в bitrix/modules и local/modules, порядок — по зависимостям (requireModules в .settings.php модуля);
не установлен — ставит его установщиком (DoInstall(), как кнопка «Установить», со всеми проверками: UTF-8, PHP, зависимости и их версии); отказ печатается текстом;
установлен, а файлы новее последней синхронизации — раскладывает файлы установщика (InstallFiles(): стили, скрипты, компоненты) и повторяемые данные (installModuleData(), если он у модуля есть). Замена файлов сама установщик не запускает — без команды портал этого не получит;
нужной зависимости нет (в том числе модуля ядра) — модуль не трогает и говорит, чего не хватает.

Обновление — только файлы и повторяемые данные. Новые таблицы и шаги включения модуля («Проверить и включить» и т. п.) команда не выполняет — смотрите инструкцию обновления модуля.

Первый запуск обновит все установленные модули shef.*: команда ещё не знает, на какой версии их ставили. Файлы модулей (/bitrix/js/shef*, /bitrix/css/shef*, компоненты модулей) раскладываются поверх — правки, сделанные на портале прямо в них, пропадут. Поэтому без --yes команда только показывает план. Модуль, удалённый руками, следующий запуск поставит снова, если его файлы остались на диске.

Код выхода 1 — хоть один модуль не встал, не обновился или заблокирован (нет зависимости). Только модули shef.*: чужим модулям команда установщики не запускает. Сам shef.options ставится первым — из административного раздела или Composer'ом: команда живёт в нём.

Портал из git: раскладка без портала

Если корень сайта лежит в git и выкладывается git reset --hard, файлы, которые установщики кладут вне каталога модуля (/bitrix/css, /bitrix/js, заглушки страниц, компоненты), тоже должны быть в git — ровно такими, какими их запишет установщик. Иначе установка оставит изменённые файлы, и следующий деплой остановится или затрёт новые.

Получать их установкой на стенде не нужно: каждый модуль описывает свою раскладку в install/layout.php (чистая функция: копии каталогов install/ и тексты заглушек), а скрипт собирает её в репозитории без портала, базы и ядра:

php www/bitrix/modules/shef.options/tools/layout.php www            # сверить (код 1 — разошлось)
php www/bitrix/modules/shef.options/tools/layout.php www --write    # записать — и в тот же коммит

Модуль без install/layout.php скрипт называет — его файлы надо снять иначе. После --yes команда shef:modules:sync сама смотрит git status под корнем сайта и печатает файлы, которые разошлись с git; ничего не откатывает и не коммитит. Портал без git — проверки нет.

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

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

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

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

Обновление

Обновление — это повторная раскладка файлов: composer update или распаковка нового архива поверх. Затем — php bitrix.php shef:modules:sync (раздел выше): он доставит то, что раскладывает установщик, этому и всем модулям линейки. Настройки модуля живут в базе, поэтому обновление их не трогает: «Служебный пользователь» останется на месте.

Не правьте .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
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. Чужое не трогается.

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

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

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

История изменений
Installer
Опции настроек модуля
Работа с пользователями
Утилиты
Работа с компонентами
Паттерны
Тестирование
Набор трейтов
Примеры — запускаемые, в том числе на вашем портале

Весь репозиторий — bx-shef/options.

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

MIT, см. LICENSE.

ИП Шевчик И.С., bx-shef.by — вопросы и предложения на offer@bx-shef.by или в задачи репозитория.

bxshef / options

Package info

Security

Statistics