Начало работы

Структура проекта

Проект Winter плоский: несколько файлов в корне и одна папка под ваш код. Нет config/, нет routes/, нет обязательного app/. Раскладку внутри своей папки вы выбираете сами — фреймворк находит классы обходом каталогов из автозагрузки composer.json, а не по списку в конфиге.

Ваш код main/Служебное .winter/Сканируется autoload · bootstrap.phpНе сканируется vendor · .winter · resources

После установки

text
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

Класс приложения. Объявляет, из чего приложение состоит, и служит точкой входа.

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 и передача управления классу приложения.

bash
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 — соответствие пространства имён каталогу:

composer.json
{
  "autoload": {
      "psr-4": {
          "Main\\": "main/"
      }
  }
}

Один префикс Main\ — не предел. Добавьте свои, и они начнут работать после composer dump-autoload:

composer.json
"psr-4": {
  "Main\\":  "main/",
  "Api\\":   "api/",
  "Admin\\": "admin/"
}

Отдельные корни удобны, когда части приложения живут своей жизнью: у публичного API и у админки разные маршруты, разные middleware и часто разные люди. Сканируются все корни одинаково: обход берёт именно перечисленные в autoload пути — psr-4, psr-0 и classmap. Новый корень попадает в скан после composer dump-autoload.

.env

Значения, зависящие от окружения. В репозиторий не коммитится — в .gitignore он и vendor/.

bash
php call cfg env -s     # что реально загрузилось
php call cfg env -i     # создать .env из шаблона
php call cfg key -g     # перевыпустить WINTER_KEY

Полный список переменных — на странице Конфигурация.

main/ — ваш код

Единственная папка, которую вы наполняете. Внутри неё структура ваша: фреймворк не требует ни Controllers/, ни Models/, ни какого-либо другого имени.

text
main/
├── MainController.php
├── User/
│   ├── UserController.php
│   ├── UserService.php
│   └── UserRepository.php
└── Order/
  ├── OrderController.php
  └── OrderProcess.php

Здесь классы сгруппированы по предметной области, а не по типу — но раскладка «по типу» (Controllers/, Services/, Repositories/) работает ровно так же. Разницы для фреймворка нет: он ищет классы, а не каталоги.

Куда кладёт файлы make

Генератор идёт от пространства имён. Правил всего два.

Указали путь точками — он и решает. Путь ищется среди корней PSR-4, vendor/ исключён:

bash
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/. Создавать каталоги заранее не нужно: достаточно один раз создать тот, который вам нравится, и генератор будет попадать в него сам.

bash
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.

Что сканируется при старте

Фреймворк не читает список классов из конфига — он обходит файлы. Порядок такой:

  1. каждый пакет, импортированный через #[Import], в порядке объявления;
  2. затем код проекта — каталоги из секции 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):

text
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.

text
.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/ Статика, если раздаёте её приложением

Раздача статики включается явно, в настройке веб-слоя:

php
public function configureServer(ServerSettings $server, ApplicationArguments $args): void
{
  $server->staticPath('resources/static');
}

Такие запросы обслуживаются сервером напрямую и в PHP не попадают: middleware, CORS и логирование запросов к ним не применяются.

Файлы контейнера

Команда php call cfg docker добавляет в проект готовую сборку:

text
my-app/
├── Dockerfile             на образе flytachi/winter: vendor/ и код проекта
├── docker-compose.yml     порт, монтирование исходников, переключатель DEV
└── .dockerignore

Swoole, расширения, пользователь winter и запуск приложения приходят с образом flytachi/winter — в проекте их нет.

Режим выбирается переменной: DEV=true docker compose up — разработка с перезапуском по изменению файлов, docker compose up — рабочий режим с opcache. Как добавить своё расширение — в cfg docker.

Свои пути

Раскладка по умолчанию выводится из корня, а корень — из расположения класса приложения. Всё это переопределяется в configure():

bootstrap.php
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, чтобы все процессы проекта находили одни и те же файлы. Переопределять пути по одному, а не всё сразу — нормально: незаданное считается от заданного.

Дальше