Публичные расширения: точки override и расширения без форкаlink

В SF4 “публичными” стоит считать те точки, которые изначально рассчитаны на проектное расширение и при этом живут в слое проекта, а не в поставке. Самая надёжная и повторяемая схема расширения — это override через {site_dir}/simai.data, когда вы добавляете или переопределяете сущности, сохраняя структуру каталогов и коды.

Что сюда относится на практике:

• Шаблон и области: подключение областей через \SIMAI\Main\IO\IncludeArea::includeTemplateArea("..."), где файл области должен лежать в {site_dir}/simai.data/template/area/<path>/template.php. Это “чистая” проектная точка: добавили папку/файл — подключили вызовом, без изменений поставки.

• Блоки/представления: SF4 умеет работать с “двумя слоями” (системный слой и слой данных сайта) и собирать списки сущностей из обоих. На уровне API это реализовано так, что один и тот же путь в системном слое и в {site_dir}/simai.data рассматривается как пара “база + override”, а метаданные берутся из .description.php внутри папок. Поэтому добавление новых блоков/view в {site_dir}/simai.data — это именно расширение без форка.

• Расширение системы свойств: новые типы/шаблоны свойств и интеграции добавляются через семейство модулей simai.property* (как отдельное расширение, а не правка ядра). Это правильная точка для всего, что связано с типами полей/шаблонами отображения/универсальными свойствами.

• API классов: в проектном коде можно безопасно опираться на классы уровня SIMAI\Main\... — в первую очередь на:

  • SIMAI\Main\Configuration\* (работа с настройками и итоговыми свойствами),
  • SIMAI\Main\IO\IncludeArea (области),
  • SIMAI\Main\Page\Asset и SIMAI\Main\Page\Font (подключение ресурсов и шрифтов по реестру),
  • SIMAI\Main\Block\Section / SIMAI\Main\Block\Edit (слои блоков и режимы редактирования),
  • SIMAI\Main\Utility\* (вспомогательные утилиты).

Внутренности ядра: устройство подсистем без прямых правок (расширяем только через публичные точки)link

К “внутренним подсистемам” SF4 стоит относить то, что является реализацией платформы и обновляется вместе с ядром. Их важно понимать (для диагностики и правильного использования), но не стоит править напрямую.

Что относится к таким внутренностям по реализации библиотечных классов:

• Сбор и хранение итоговых свойств: SIMAI\Main\Configuration\Property — это сессионное хранилище (ключ site_property в $_SESSION), куда складывается итоговый набор свойств (например, уже собранный из уровней site/section/page/user). Дополнительно есть поддержка “вложенных” ключей через запись вида a/b/c (внутри setValue() это раскладывается в массив до глубины 5 уровней). Это мощно, но это именно механизм ядра: проекту лучше использовать его через публичные методы getValue()/setValue(), а не вмешиваться в структуру сессии напрямую.

• Подсистема ассетов: SIMAI\Main\Page\Asset читает системный реестр и подключает ресурсы через \Bitrix\Main\Page\Asset. Важно, что в текущей реализации нет слоя merge с {site_dir}/simai.data для реестра ассетов: это не “override-механизм”, как у блоков, а системный реестр ядра. Поэтому проектная стратегия — подключать свои ресурсы через шаблон, а не пытаться “переопределять” реестр в simai.data.

• Система слоёв для блоков/секций: SIMAI\Main\Block\Section реализует ключевой паттерн SF4 — “системный слой + слой данных сайта” (через SF_DIR и SF_DATA_DIR). Ядро умеет искать директорию в обоих слоях и собирать объединённые списки (в том числе с сортировкой по данным .description.php). Это внутренняя реализация, а публичное расширение здесь — именно добавление сущностей в {site_dir}/simai.data, без правок системного слоя.

• Мастера и actions: мастера и их действия — инфраструктура установки/миграций/обновлений. Проектно расширять их безопаснее через конфигурацию и пакет конкретного мастера (его набор данных), а не через изменение системных действий.

Если коротко: внутренности можно описывать как “как устроено” и “как это используется”, но в документации нужно явно говорить, что правки делаются только в проектном слое и расширениях, иначе обновления SF4 будут постоянно ломать проект.

Разделять явным текстом, что расширяется без форка, а что обновляется с ядромlink

Чтобы в документации SF4 это не выглядело “на словах”, удобно зафиксировать простое правило по путям и ответственности:

• Можно расширять без форка (это проектный контракт):

  • {site_dir}/simai.data/... — шаблон, области, grid/view/block, конфиги проекта, пользовательские ресурсы.
  • расширения через отдельные модули (например, новые типы/шаблоны свойств через simai.property*).

• Нельзя править напрямую (это поставка и внутренняя реализация):

  • /bitrix/modules/simai.framework/...
  • /simai/...
  • системный шаблон (/bitrix/templates/simai.framework как “мостик”)
  • всё закомментированное в проектных файлах считать неиспользуемым (в ваших проектах это “мусор”, а не альтернативный сценарий).

И полезно сразу показывать 2–3 “каноничных” примера расширения, чтобы у разработчика не осталось соблазна “поправить в ядре”:

<?php

use SIMAI\Main\IO\IncludeArea;

// Добавить новую область без форка:
// файл: {site_dir}/simai.data/template/area/sidebar/right/template.php
IncludeArea::includeTemplateArea('sidebar/right');