Концепции

Templite опирается на четыре ключевые концепции. Они влияют на структуру кода, расширение CMS и производительность.

Блочная архитектура

Что такое блок

Блок — переиспользуемая единица контента (hero-баннер, преимущества, форма обратной связи, галерея). У блока есть:

• slug — уникальный идентификатор (hero-banner, латиница нижнего регистра через дефис)
• block_type_id — категория блока (4 варианта, см. ниже)
• Поля — типизированные поля, хранятся в БД (таблица block_fields)
• Шаблон — template.blade.php рядом с файлами блока
• Стили — style.scss (опционально)
• JavaScript — script.js (опционально)
• Метаданные — block.json (slug, name, type, description, version)
• source — отметка в БД о том, где живёт код блока: database, file или vendor

Жизненный цикл блока

1. Создание блока (через UI «Блоки» или вручную в файловой системе).
2. Описание полей (через UI или REST API). Поля сохраняются в таблицу block_fields.
3. Написание Blade-шаблона и стилей.
4. Размещение блока на странице (через конструктор страниц или API).
5. Рендер: BlockRenderer находит шаблон через BlockRegistry, валидирует его (BladeSecurityValidator), рендерит с пятью переменными.
6. Автоматическая обёртка в <div class="cms-block cms-block--{slug}" data-block="{slug}" data-block-id="..."> (если no_wrapper != true).
7. Кэширование результата (включается на уровне page_blocks.cache_enabled).
8. Инвалидация кэша при изменении блока, связанной страницы или глобальных настроек.

Переменные в шаблоне блока

В Blade-шаблон блока передаются ровно пять переменных:

Переменная	Содержимое
$fields	Значения полей блока, обёрнутые в FieldsBag (см. ниже)
$actions	Привязанные actions блока
$page	Модель текущей страницы
$global	Значения глобальных настроек
$block	Модель самого блока (Block Eloquent)

FieldsBag — обёртка над массивом полей. Для несуществующего ключа возвращает пустой FieldsBag, а не null. Это безопасно для @foreach и обычного вывода без @isset.

Типы блоков

block_type_id	Тип
1	Контент
2	Медиа
3	Навигация
4	Формы

Тип используется для фильтрации и группировки в админке. Логика рендера от типа не зависит.

---

Принцип трёх источников

Блоки, компоненты, actions и шаблоны страниц могут жить в нескольких физических локациях. При совпадении слагов CMS использует реализацию с высшим приоритетом источника: app > storage > vendor.

Реальные пути отличаются по типу сущности:

Сущность	app (высший)	storage (средний)	vendor (низший)
Блок	app/Blocks/<slug>/	storage/cms/blocks/<slug>/	Регистрация через ServiceProvider пакета
Компонент (PHP-класс)	app/View/Components/Cms/<Name>.php	—	—
Компонент (Blade)	—	storage/cms/components/<slug>/index.blade.php	packages/templite/cms/resources/views/components/*.blade.php
Action	app/Actions/<Name>.php	storage/cms/actions/<Name>.php	Регистрация через ServiceProvider
Шаблон страницы	—	storage/cms/templates/<slug>/template.blade.php	—

TIP

Кастомный код, который должен попасть в Git, кладите в app/. Контент и быстрые правки через UI попадают в storage/cms/. Все системные блоки и компоненты, поставляемые CMS, живут в vendor/.

Примеры

• Заменить блок hero-banner из пакета: создать app/Blocks/hero-banner/ с тем же слагом — BlockRegistry будет использовать его.
• Переопределить встроенный компонент <x-cms::image>: положить свой класс в app/View/Components/Cms/Image.php.
• Свой action для формы: создать app/Actions/SendContactForm.php, имплементировать BlockActionInterface.

Внимание: cms:make-* команды

Команды cms:make-block, cms:make-action, cms:make-component (без флага --storage) создают файлы в app/Cms/..., что не соответствует путям runtime-резолверов из таблицы выше. С флагом --storage команды создают файлы в storage/cms/... — этот путь корректный. Если используете make-команды без --storage, перенесите получившиеся файлы вручную в нужную папку (app/Blocks/, app/Actions/ и т.д.).

---

API-first

Все операции с контентом CMS идут через REST API под префиксом /api/. Аутентификация — Laravel Sanctum:

• Админка использует guard manager и session-based auth (cookie + CSRF).
• Публичные пользователи сайта используют отдельные guards (web, cabinet и пользовательские) и могут логиниться через /api/cms/user-auth/{guard}/login.

Те же эндпоинты используются:

• Самой админкой (рендерится поверх API)
• MCP-сервером (управление CMS из AI-агентов)
• Внешними интеграциями

См. REST API для подробностей.

---

Кэш и производительность

Кэш блоков

Кэширование рендера каждого блока на странице управляется флагом cache_enabled в таблице page_blocks (по умолчанию — включено). Кэш инвалидируется при сохранении блока, страницы или связанных глобальных настроек.

Скомпилированные ассеты страниц

У каждой страницы есть связанные assets (CSS, JS), которые собираются командой cms:compile-assets. Шаблон страницы получает их через переменную $assets (css, js, cdn_css[], cdn_js[]).

Серверная компиляция SCSS

SCSS-стили блоков компилируются на сервере через scssphp и кэшируются. Командой cms:compile-assets можно явно пересобрать все страничные ассеты, командой cms:cache-clear — очистить кэш.

Redis

По умолчанию используется для сессий, кэша Laravel и очередей. Конфигурируется через REDIS_* в .env. Для разработки можно переключить на file/array драйверы.

Целостность кода

Templite валидирует код перед загрузкой:

• BladeSecurityValidator — проверяет каждый шаблон блока при рендере на запрещённые конструкции.
• ActionCodeValidator — проверяет PHP-код action при загрузке из файла, плюс контролирует SHA-256 хэш файла против сохранённого в БД.

Это защита от подмены файлов на диске вне CMS.

Очистка кэша

docker exec templite-app php artisan cms:cache-clear

См. Artisan и безопасность для полного списка cleanup-команд.

---

Связанные разделы

• Блоки
• Шаблоны
• Компоненты и библиотеки
• Actions
• REST API