Структура проекта
Проект Winter плоский: несколько файлов в корне и одна папка под ваш код. Нет
config/, нет routes/, нет обязательного app/.
Раскладку внутри своей папки вы выбираете сами — фреймворк находит классы обходом
каталогов из автозагрузки composer.json, а не по списку в конфиге.
После установки
my-app/
├── bootstrap.php класс приложения: из чего оно состоит
├── call точка входа для всех команд
├── composer.json автозагрузка и зависимости
├── composer.lock зафиксированные версии
├── .env переменные окружения
├── .gitignore
│
├── main/ ваш код, namespace Main\
│ └── MainController.php
│
└── vendor/Это всё, что есть сразу после composer create-project. Остальное появляется по мере
надобности:
| Что | Когда появляется |
|---|---|
.winter/ |
при первом запуске — служебные данные фреймворка, см. ниже |
logs/ |
когда логи пишутся в файл (LOG_OUTPUT=file), см. Логирование |
resources/ |
создаёте вы — под шаблоны, переводы, статику |
Dockerfile, docker-compose.yml, .dockerignore |
php call cfg docker |
каталоги внутри main/ |
создаёте вы или генератор make |
Корень проекта
bootstrap.php
Класс приложения. Объявляет, из чего приложение состоит, и служит точкой входа.
#[EnableHttp]
final class Application extends WinterApplication
{
public static function main(array $argv): never
{
parent::run($argv);
}
}Атрибуты #[Enable*] — единственное место, где перечислен состав приложения. См.
Состав приложения.
Этот файл заодно задаёт корень проекта: фреймворк берёт каталог, в котором лежит
класс приложения, и от него выводит все остальные пути — .env, .winter/,
logs/, resources/, расположение composer.json. Поэтому bootstrap.php лежит в корне, а не в
подпапке.
call
Запускает всё: сервер, консольные команды, генераторы. Внутри — проверка версии PHP,
chdir(__DIR__), подключение bootstrap.php и передача управления классу приложения.
php call run dev # сервер разработки
php call mapping show # список маршрутов
php call make -c .User # создать контроллерchdir внутри означает, что команды работают из любого каталога:
php /path/to/my-app/call run поднимет сервер с правильными путями.
composer.json
Кроме зависимостей задаёт PSR-4 — соответствие пространства имён каталогу:
{
"autoload": {
"psr-4": {
"Main\\": "main/"
}
}
}Один префикс Main\ — не предел. Добавьте свои, и они начнут работать после
composer dump-autoload:
"psr-4": {
"Main\\": "main/",
"Api\\": "api/",
"Admin\\": "admin/"
}Отдельные корни удобны, когда части приложения живут своей жизнью: у публичного API и
у админки разные маршруты, разные middleware и часто разные люди. Сканируются все
корни одинаково: обход берёт именно перечисленные в autoload пути — psr-4, psr-0
и classmap. Новый корень попадает в скан после composer dump-autoload.
.env
Значения, зависящие от окружения. В репозиторий не коммитится — в .gitignore он и
vendor/.
php call cfg env -s # что реально загрузилось
php call cfg env -i # создать .env из шаблона
php call cfg key -g # перевыпустить WINTER_KEYПолный список переменных — на странице Конфигурация.
main/ — ваш код
Единственная папка, которую вы наполняете. Внутри неё структура ваша: фреймворк не
требует ни Controllers/, ни Models/, ни какого-либо другого имени.
main/
├── MainController.php
├── User/
│ ├── UserController.php
│ ├── UserService.php
│ └── UserRepository.php
└── Order/
├── OrderController.php
└── OrderProcess.phpЗдесь классы сгруппированы по предметной области, а не по типу — но раскладка «по
типу» (Controllers/, Services/, Repositories/) работает ровно так же. Разницы
для фреймворка нет: он ищет классы, а не каталоги.
Куда кладёт файлы make
Генератор идёт от пространства имён. Правил всего два.
Указали путь точками — он и решает. Путь ищется среди корней PSR-4, vendor/
исключён:
php call make -c api.user.Profile # main/Api/User/ProfileController.php
php call make -c admin.Report # admin/ReportController.php (если есть корень Admin\)Путь не указали (.Name) — генератор смотрит, нет ли уже привычного каталога.
Берётся первый существующий из списка:
| Тип | Флаг | Ищет каталог (первый существующий) |
|---|---|---|
| Контроллер | -c |
Rests, Rest, Controllers, Controller |
| Middleware | -m |
Middlewares, Middleware, Controllers/Middlewares, Controllers/Middleware, Controller/Middlewares, Controller/Middleware |
| Сервис | -s |
Services, Service |
| Репозиторий | -r |
Repositories, Repository |
| Redis-хранилище | -t |
Stores, Store |
| Сущность | -e |
Entity, Entities |
| DTO | -d |
Dto, DTOs, Entity/Dto, Entity/DTOs, Entities/Dto, Entities/DTOs |
| Процесс | -P |
Processes, Process |
| Демон | -N |
Daemons, Daemon |
| WebSocket | -W |
Sockets, Processes, Process |
| Конфиг БД | -D |
Configs/Databases, Config/Database, Configs, Config |
| Конфиг Redis | -R |
Configs/Redis, Configs, Config |
| Консольная команда | -n |
Cmd |
Ни одного такого каталога нет — файл ляжет в корень PSR-4, то есть прямо в main/.
Создавать каталоги заранее не нужно: достаточно один раз создать тот, который вам
нравится, и генератор будет попадать в него сам.
php call make -c .User # main/UserController.php
mkdir main/Controllers
php call make -c .Order # main/Controllers/OrderController.phpОпция --mvc не ищет, а создаёт: она подставляет каталог по типу
(Controllers/, Services/, Repositories/…) независимо от того, есть он или нет.
Подробности и все флаги — call make.
Что сканируется при старте
Фреймворк не читает список классов из конфига — он обходит файлы. Порядок такой:
- каждый пакет, импортированный через
#[Import], в порядке объявления; - затем код проекта — каталоги из секции
autoloadегоcomposer.jsonи файл с классом приложения (bootstrap.php).
Приложение идёт последним намеренно: там, где вклад пакета и вклад приложения конфликтуют, побеждать должно приложение.
Код проекта — это то, что объявлено в autoload: все пути psr-4 и psr-0 и записи
classmap. Секции autoload-dev и files в скан не входят. В скелете это main/
("Main\\": "main/"). Файл с классом приложения добавляется к ним отдельно, поэтому
классы, объявленные в bootstrap.php, по-прежнему находятся. Так же устроены базовый
пакет в Spring и каталоги ресурсов в Symfony: фреймворк сканирует код приложения, а не
всё, что лежит рядом с ним.
Остальные папки корня — tests/, scripts/, тома данных — в скан не попадают, если не
объявлены в autoload. Тест-класс без dev-зависимостей (composer install --no-dev)
не остановит старт, а код скрипта на верхнем уровне не выполнится при запуске.
В каждом каталоге читаются только файлы .php. Из файла собираются все
объявленные в нём классы, после чего файл подключается. Так находятся контроллеры,
конфигурации, процессы, команды — регистрировать их нигде не требуется.
Без autoload приложение не стартует
Если composer.json нет или в его autoload не объявлено ни одного каталога, старт
останавливается с ScanException. Сообщение подсказывает исправление: добавить
"autoload": {"psr-4": {"Main\\": "main/"}} и выполнить composer dump-autoload.
В скелете эта запись уже есть.
Каталог внутри кода, который нельзя открыть (нет прав, его не отдаёт примонтированный
том), пропускается, а не останавливает старт. Классы из него не регистрируются, и
об этом один раз за запуск процесса пишет предупреждение (WARN, канал sys):
Class scan skipped <dir>: it cannot be opened (permissions?). Its classes are not registered.Предупреждение появляется только при холодном скане: если список классов взят из кеша
di.php, обхода нет.
Из обхода исключены три каталога — это важно, когда проект автозагружается от корня
("App\\": "") и они оказываются внутри сканируемого пути:
| Каталог | Почему |
|---|---|
vendor/ |
Зависимости не участвуют в поиске классов приложения; исключено самим сканером |
.winter/ |
Там лежит сгенерированный код — обход читал бы результат прошлого обхода |
resources/ |
Там лежат шаблоны: PHP-файлы по природе, не классы |
Исключения привязаны не к именам, а к настроенным путям: перенесли ресурсы в
assets/ через pathResource — исключение переедет вместе с ними. В исключённый каталог
сканер не заходит, а совпадение считается по границе папки: исключение vendor не
задевает vendor-tools/.
Шаблоны исключены не для скорости
Сканер ищет объявление класса в каждом .php и подключает файл, где его нашёл. Для
шаблона это означает выполнение: он выведет свою разметку в вывод приложения и
запустит всё, что есть у него на верхнем уровне. Это проверено на живом проекте, а не
предположено.
Поэтому шаблоны держите под resources/. Каталог с шаблонами, положенный внутрь
main/, попадёт под обход.
Отсюда практическое правило: внутри каталогов из autoload должны лежать только
классы приложения. Шаблоны — в resources/, скрипты, дампы и миграционные
однострочники — в папках вне autoload: туда сканер не заглядывает.
Переход с версии до 4.4.1
Раньше обход шёл от корня проекта целиком, и класс находился, где бы ни лежал. Теперь
класс вне каталогов из autoload и вне bootstrap.php не обнаруживается. Перенесите его
в автозагружаемую папку или добавьте его папку в autoload, затем выполните
composer dump-autoload.
.winter/ — служебные данные фреймворка
Всё, что фреймворк пишет для себя, лежит в одной скрытой папке в корне проекта.
Ничего в ней не правят руками и не коммитят: одна строка /.winter в .gitignore и
.dockerignore.
.winter/
├── build/ собирает сам фреймворк, чтобы стартовать быстрее
│ ├── di.php список классов проекта
│ ├── proxy.php список классов с прокси
│ └── proxy/ сгенерированные прокси #[Async] и #[Cacheable]
├── cache/ значения #[Cacheable] в хранилище file
│ └── <имя кэша>/
└── runnable/ состояние запущенных процессов
├── Main.Process.Heartbeat/ запись: PID, состояние, кем управляется
├── Main.Process.Heartbeat.lock блокировка: пока процесс жив, он держит её
├── app/ запись приложения и его компонентов
├── app.Application.lock «одно приложение — один запуск»
├── requests/, replies/ консоль ↔ приложение: start, restart
└── ppa.pool/ загрузка пулов соединений| Папка | Что там | Когда появляется | Можно ли удалить |
|---|---|---|---|
build/ |
список классов и прокси | при старте с DEBUG=false или call di build |
да, в любой момент: call di clean |
cache/ |
кэши #[Cacheable] типа file |
при первой записи в такой кэш | да: call cache clear --all |
runnable/ |
состояние процессов и приложения | при первом запуске процесса или приложения | только когда ничего не запущено |
Папка не переносится: ни параметром, ни переменной окружения. Так все процессы проекта
— консоль на хосте и приложение в контейнере, если проект смонтирован, — видят одни и
те же файлы: на этом построены call process status, call app status и проверка
«приложение уже запущено».
Папка должна быть доступна на запись
Пользователь, от которого работает приложение, должен иметь право писать в .winter/ — в
образе flytachi/winter это winter, uid 1000. Если проект принадлежит другому
пользователю (например, root, а проект смонтирован в контейнер), старт и call di build
останавливаются сразу:
The framework cannot write /app/.winter as this user (winter, uid 1000): it keeps its process records, locks and caches there. Give the user the project folder (chown -R), or create .winter/ owned by it.Исправляется передачей папки этому пользователю: chown -R 1000:1000 <папка проекта>.
При DEBUG=true кеша классов нет вообще
build/ пишется и читается только при DEBUG=false. В отладке каждый старт заново
обходит файлы — новый класс виден сразу, без di build и без «почему мой контроллер
не находится».
Обратная сторона того же: на проде класс, добавленный без пересборки, не появится.
Поэтому di build — шаг сборки образа, а не ручная операция.
Не удаляйте runnable/, пока процессы работают
У работающих процессов пропадут записи — status и stop перестанут их видеть — и
файлы блокировок, после чего можно запустить второй экземпляр того же процесса.
Логи в .winter/ не пишутся: при LOG_OUTPUT=file они идут в каталог LOG_DIR, по
умолчанию logs/ в корне проекта, — его стоит добавить в .gitignore.
resources/ — шаблоны, переводы, статика
Каталога изначально нет; создайте, когда понадобится. Имена подкаталогов — соглашение фреймворка, менять их не нужно.
| Путь | Что там |
|---|---|
resources/views/ |
Шаблоны и макеты для ResponseView |
resources/lang/ |
Словари переводов: ru.php, en.php |
resources/static/ |
Статика, если раздаёте её приложением |
Раздача статики включается явно, в настройке веб-слоя:
public function configureServer(ServerSettings $server, ApplicationArguments $args): void
{
$server->staticPath('resources/static');
}Такие запросы обслуживаются сервером напрямую и в PHP не попадают: middleware, CORS и логирование запросов к ним не применяются.
Файлы контейнера
Команда php call cfg docker добавляет в проект готовую сборку:
my-app/
├── Dockerfile на образе flytachi/winter: vendor/ и код проекта
├── docker-compose.yml порт, монтирование исходников, переключатель DEV
└── .dockerignoreSwoole, расширения, пользователь winter и запуск приложения приходят с образом
flytachi/winter — в проекте их нет.
Режим выбирается переменной: DEV=true docker compose up — разработка с перезапуском
по изменению файлов, docker compose up — рабочий режим с opcache. Как добавить своё
расширение — в cfg docker.
Свои пути
Раскладка по умолчанию выводится из корня, а корень — из расположения класса
приложения. Всё это переопределяется в configure():
protected static function configure(ApplicationArguments $args): void
{
Kernel::init(
pathRoot: __DIR__,
pathResource: __DIR__ . '/assets',
);
}| Параметр | По умолчанию |
|---|---|
pathRoot |
каталог файла с классом приложения |
pathResource |
<root>/resources |
.winter/ и .env в этом списке нет намеренно: служебная папка всегда <root>/.winter,
а .env — всегда <root>/.env, чтобы все процессы проекта находили одни и те же файлы. Переопределять пути по одному, а не всё
сразу — нормально: незаданное считается от заданного.
Дальше
- Конфигурация —
.envи классы-конфигураторы - Состав приложения — атрибуты
#[Enable*] - Быстрый старт — первый маршрут
call make— генераторы и все флаги- Пакеты —
#[Import]и чужой код в обходе