# Архітектура

Celena — самописна PHP-CMS без сторонніх фреймворків (без Laravel/Symfony) і без Composer-залежностей у ядрі. Весь код написано на чистому PHP 8.3+ з обовʼязковим `declare(strict_types=1)` та суворою типізацією.

Якщо ви тільки починаєте — прочитайте цю сторінку, потім [Структуру проєкту](/docs/code/structure) та [Життєвий цикл запиту](/docs/code/lifecycle). Для розробки розширень переходьте до розділу [Що таке плагін](/docs/code/plugins-intro).

## Точки входу

| Файл | Призначення |
|------|-------------|
| `index.php` | Фронт сайту — усі публічні запити. |
| `admin.php` | Адмін-панель (тонкий завантажувач, передає керування в `Kernel`). |
| `install.php` | Самовидаляльний майстер встановлення (після встановлення зʼявляється `install.lock`). |
| `bin/celena` | CLI: міграції, плагіни, черга, кеш. |

Усі запити проходять через ядро `Celena\Core\Kernel`:

```
HTTP-запит → index.php → core/bootstrap.php → Kernel::boot()
  → Autoloader → Container → Config → сервіси
  → Router::dispatch(Request) → Middleware → Controller → Response → send()
```

## Шари

Код поділено на чотири шари зі суворим напрямком залежностей:

| Шар | Тека | Залежить від |
|-----|------|--------------|
| Ядро (не знає про домен) | `core/` | лише `core/*` |
| Вбудовані модулі CMS | `modules/` | `core/*` |
| Плагіни (розширення) | `plugins/` | `core/*`, опц. інші плагіни через маніфест |
| Теми (оформлення) | `templates/` | лише теги шаблонізатора |

Ядро не знає про новини, магазин чи форми — воно надає інструменти (роутер, БД, шаблонізатор, хуки), а конкретну функціональність дають модулі та плагіни.

## Простори імен і автозавантаження

PSR-4 через `core/Autoloader.php`. Мапінги:

- `Celena\Core\` → `core/`
- `Celena\Module\<Name>\` → `modules/<Name>/`
- `Celena\Plugin\<Slug>\` → `plugins/<slug>/src/`
- `Celena\Theme\<Slug>\` → `templates/<slug>/`

**Правило: один клас — один файл.** Імʼя файлу збігається з імʼям класу.

## Контракти

- Усюди `declare(strict_types=1)`, типи аргументів і повернення обовʼязкові.
- Будь-яке введення користувача проходить через `Celena\Core\Security\Filter`.
- Будь-яке виведення в HTML — через `e()` (хелпер екранування) або авто-екранування шаблонізатора.
- Робота з БД — лише через `QueryBuilder` або `PDO::prepare`. **Конкатенація значень у SQL заборонена.**

## Хуки (events)

Розширення спілкуються з ядром через систему хуків у стилі WordPress — actions (побічні ефекти) та filters (перетворення значення):

```php
use Celena\Core\Plugin\Hook;

Hook::action('news.published', $news);              // викликати action
Hook::on('news.published', fn($n) => /* ... */);    // підписатися

$title = Hook::filter('news.title', $news['title']); // застосувати фільтри
Hook::addFilter('news.title', fn($t) => trim($t));   // підписатися на фільтр
```

Докладніше — на сторінці [Хуки та події](/docs/code/hooks).

## Кеш

- Кеш даних типово файловий (`storage/cache/data`); опційно APCu/Redis.
- Шаблони компілюються в PHP і кешуються в `storage/cache/tpl/{hash}.php`. Інвалідація — за часом зміни джерела (mtime) і вручну.
