home chevron_right
Чистые пути и хранение настроек/путей

Пути и коды без пробелов/кириллицы; использовать латиницу/подчеркиваниеlink

В SF4 “код” почти всегда становится частью технического идентификатора: имени папки, ключа в конфиге, значения параметра, части URL или пути к include-области. Поэтому базовое правило простое: код должен быть таким, чтобы его можно было безопасно использовать везде — в PHP, в URL, в файловой системе и в конфигурациях.

Практические рекомендации:

  • Используйте латиницу, цифры, дефис - и подчёркивание _.
  • Не используйте пробелы, кириллицу, символы вроде &, ?, #, @ в названиях файлов/папок, кодах блоков/областей.
  • Для “составных” имён выбирайте один стиль и держитесь его в проекте:
    • sidebar/right — как код области (путь внутри area/)
    • section.banner.php — как секционная область
    • layout_type, edit_mode — как коды настроек

Мини-пример “чистого” кода области, который без сюрпризов работает и как путь:

<?php

declare(strict_types=1);

use SIMAI\Main\IO\IncludeArea;

IncludeArea::includeTemplateArea('sidebar/right');

Если вы придерживаетесь чистых кодов, вам проще:

  • переносить сайт между окружениями,
  • поддерживать структуру без “магии” и исключений,
  • избегать ошибок путей из-за экранирования/кодировок.

Все настройки, конфиги и данные должны жить в {site_dir}/simai.data (config/template/grid/include/etc.), ядро /simai не менятьlink

Ключевая идея SF4: ядро обновляется, данные сайта остаются. Поэтому всё, что относится к вашему проекту (кастомизация, настройки, контентные шаблоны, области, блоки/вьюхи), должно жить в слое {site_dir}/simai.data.

Что обычно относится к “проектному слою”:

  • {site_dir}/simai.data/template/** — шаблон, области, панели, стили/скрипты проекта
  • {site_dir}/simai.data/grid/** — проектные блоки/вьюхи и их варианты
  • {site_dir}/simai.data/admin/** — проектные скрипты публичного редактирования (если вы их используете)
  • {site_dir}/simai.data/.site.property.php и /.property.php — настройки уровней (site/section/page)

Что относится к “ядру” и не должно быть местом правок:

  • /simai/** — системные классы, конфиги, действия мастера, ассеты ядра
  • /bitrix/templates/simai.framework — базовый системный шаблон-загрузчик (кастомизация делается не здесь, а в simai.data)

Практическое правило для команды: если вы ловите себя на мысли “сейчас быстро поправлю в /simai или в системном шаблоне” — почти всегда это сигнал, что нужно:

  • либо перенести изменение в simai.data,
  • либо сделать override через предусмотренную точку расширения (область, блок, конфиг).

Проверять пути и размещение по карте структуры SF4 перед правками/добавлениямиlink

Чтобы структура проекта оставалась поддерживаемой, важно не только “куда можно писать”, но и куда именно класть конкретный тип сущности. В SF4 многие механизмы завязаны на соглашения об именах и расположении файлов (области, блоки/вьюхи, property-файлы, проектные админ-скрипты). Ошибка в каталоге или имени часто выглядит одинаково: “ничего не подключилось”.

Мини-чек перед добавлением/переносом файлов:

  • Понимаем, что именно добавляем:
    • область → simai.data/template/area/<код>/template.php
    • секционная область → section.<prefix>.php в нужном каталоге
    • настройки раздела/страницы → /.property.php в каталоге, в правильной ветке (section или page)
    • блок/вьюха → в соответствующий каталог simai.data/grid/... (с соблюдением принятой структуры)
  • Проверяем, что:
    • путь чистый (латиница, без пробелов/кириллицы),
    • имя файла соответствует соглашению,
    • есть права на чтение/запись (если предполагается редактирование из интерфейсов),
    • код/путь совпадает с тем, что используется в вызовах (includeTemplateArea('...'), выбор блока по коду и т.д.)

Если в проекте есть “карта структуры” (описание того, какие каталоги для чего используются), держите её актуальной и используйте как единый ориентир для команды — это резко снижает число “мистических” ошибок, когда файл лежит рядом, но SF4 его не видит из-за несоответствия соглашению.