Структура каталогів

Concept Core не нав’язує жодну структуру каталогів. Розташування усіх папок — включно з src, config, storage, database — можна змінити на свій смак у bootstrap/paths.php і в PSR-4 автозавантаженні composer.json.

Concept Skeleton постачає готовий каркас із розкладкою src/App/ (component-ready). Нижче — рекомендована коренева структура проєкту та три поширені підходи до організації коду всередині src. Це орієнтири, а не обов’язковий стандарт.

Рекомендована коренева структура

Відповідає Concept Skeleton і ключам у bootstrap/paths.php:

project/
├── public/                      # document root: index.php, assets, vendor/
│   ├── index.php
│   ├── assets/
│   └── vendor/
├── bootstrap/
│   ├── app.php
│   ├── paths.php
│   └── providers/               # app.php, console.php
├── bin/console.php
├── config/                      # PHP-конфіг + config/{dev,production}/
├── routes/                      # маршрути (підключаються з config)
├── resources/
│   ├── lang/validator/          # PathName::VALIDATOR_TRANSLATIONS
│   └── views/
│       ├── errors/fallback/     # PathName::ERRORS_FALLBACK_VIEWS
│       └── frontend/
├── database/
│   ├── migrations/              # PathName::MIGRATIONS
│   └── seeders/                 # PathName::SEEDERS
├── storage/
│   ├── logs/                    # PathName::LOGS
│   └── cache/                   # PathName::CACHE
├── src/                         # PathName::SRC — код застосунку
├── tests/
├── .env.example
└── composer.json

Шлях до кожного з цих каталогів задається в paths.php через константи PathName (PathName::CONFIG, PathName::SRC, PathName::LOGS тощо). Ядро звертається до них через PathManager::get(PathName::…), а не через жорстко прошиті рядки. Наприклад, код можна тримати в app/ замість src/ — достатньо змінити значення для PathName::SRC і namespace у Composer.

Concept Skeleton за замовчуванням

Стартовий шаблон використовує component-ready розкладку: спільний код у src/App/, глобальні маршрути в routes/web.php, landing-шаблони в resources/views/frontend/. Компоненти (src/Components/) додаються за потреби.

src/App/
├── Controllers/              # Concept\App\Controllers\* (IndexController)
└── Extensions/Twig/          # Concept\App\Extensions\Twig\*

routes/web.php                # глобальні маршрути + middleware стек
resources/views/frontend/     # @frontend/… — landing, спільні сторінки

Composer (skeleton):

"autoload": {
    "psr-4": {
        "Concept\\": "src/",
        "Database\\Seeders\\": "database/seeders/"
    }
}

paths.php: повний набір ключів PathName (деталі). Провайдери вже підключені в bootstrap/providers/ — див. Налаштування.

Організація коду в каталозі src

Окрім розкладки skeleton (src/App/), можна обрати шарову MVC або модульні компоненти. Усі три варіанти сумісні з Concept Core.

1. Шарова MVC (package by layer)

Класична шарова архітектура (layered architecture): код групується за типом (контролери, моделі, запити), а не за модулем. У PHP-спільноті це часто називають package by layer — протилежність до «package by feature».

Шари лежать безпосередньо в каталозі з кодом (наприклад src/), без проміжних папок на кшталт App чи Components:

src/
├── Controllers/       # Concept\Controllers\*
├── Models/            # Concept\Models\*
├── Requests/          # FormRequest, DTO-запити
├── Validation/
│   └── Rules/
├── Extensions/
│   └── Twig/
├── Services/          # опційно: бізнес-логіка
└── Middlewares/       # опційно: HTTP middleware

Namespace відповідає PSR-4: при "Concept\\": "src/" клас src/Controllers/HomeController.php має namespace Concept\Controllers, а не Concept\App\Controllers.

Коли обирати: невеликі застосунки, один домен, мало модулів; команда звикла до класичного MVC (Symfony 2–4, ранній Laravel).

Мінуси: при зростанні проєкту складно знайти «все про замовлення» — файли розкидані по шарах.

Composer (приклад):

"autoload": {
    "psr-4": {
        "Concept\\": "src/"
    }
}

paths.php: PathName::SRC => 'src' (деталі).

2. Компоненти (модульний моноліт)

Модульний моноліт з підключаємими компонентами: спільне ядро застосунку + ізольовані функціональні модулі. Це поєднання package by feature (всередині кожного компонента) і шарів MVC. Підтримується системою компонентів Concept Core.

src/
├── App/                          # спільний код застосунку
│   ├── Controllers/              # глобальні контролери
│   ├── Models/                   # BaseModel, спільні трейти
│   ├── Requests/
│   ├── Validation/Rules/
│   ├── Extensions/Twig/
│   └── Services/
└── Components/                   # функціональні модулі
    ├── AuthAdmin/
    │   ├── AuthAdminComponent.php
    │   ├── routes.php
    │   ├── Controllers/
    │   ├── Models/
    │   ├── Requests/
    │   ├── Dto/
    │   ├── Middlewares/
    │   ├── Commands/
    │   ├── Services/
    │   ├── Enums/
    │   ├── Extensions/
    │   ├── Views/                # Twig модуля (@auth-admin/…)
    │   ├── Assets/               # JS/CSS → public через CLI
    │   └── Database/
    │       ├── Migrations/
    │       └── Seeders/
    ├── UserCabinet/
    └── ProjectManager/

Кожен компонент — клас, що напряму реалізує ComponentInterface (migrationPaths(), viewPaths(), seeders(), commands(), assets(), providers() тощо). Активні модулі перелічуються в config/components.php або config/{env}/components.php. Компоненти можуть мати власні маршрути, views, міграції, сидери, CLI-команди та assets. Каталог App — для спільних речей (базові моделі, Twig extensions, правила валідації). Покроковий приклад — AuthAdmin.

Коли обирати: кілька підсистем (адмінка, кабінет, публічна частина), потрібно вмикати або вимикати модулі через конфіг, різні команди працюють над окремими компонентами.

Порівняння

Views, lang, storage

Шляхи налаштовуються в paths.php через константи Concept\Core\Foundation\PathName. Ядро звертається до них через PathManager::get(PathName::…).

Повний перелік ключів — у таблиці PathName. Міграції та сидери окремих компонентів реєструються через migrationPaths() і seeders() класу компонента, а не через глобальні PathName::MIGRATIONS / PathName::SEEDERS.

Що обрати

• Concept Skeleton — швидкий старт: HTTP + Twig, src/App/, готові провайдери; компоненти додаються за потреби.
• Шарова MVC — простий старт без App/, один домен, мало модулів.
• Компоненти — кілька підсистем, потрібна ізоляція модулів і підтримка ядра Concept.

Структуру можна змінити в будь-який момент: оновіть paths.php, composer.json і конфіг.

Далі: життєвий цикл запиту та налаштування точок входу.