Установка

Winter — библиотека, а не каркас с обязательной структурой. Проект собирается из нескольких файлов, и ниже разобран каждый: что он делает и почему нужен. Если разбирать не хочется — первая же команда на этой странице даёт работающий проект.

Требования

`call run` with a web tier needs ext-swoole (pecl install swoole).

Остальные расширения ставятся под конкретные задачи:

Три пути

Готовый каркас

composer create-project flytachi/winter my-app
cd my-app
php call run dev

Composer после установки сам доводит проект до рабочего состояния — это видно в его выводе:

> @php call storage init
|	 storage ..................................................... [CREATED]
|	 storage/cache ............................................... [CREATED]
|	 storage/logs ................................................ [CREATED]
> chmod -R 777 storage
> @php call cfg init
|	 .env ........................................................ [CREATED]
|	 Old key    (empty)
| [✓] WINTER_KEY generated and saved to .env
|	 New key    bf4ee7d770a565c21598e57e87d46fde6637c0181cac13f4c37fd7b4c194c652

Каталоги созданы и доступны на запись, .env на месте, ключ — свой, а не общий с чужим проектом. Ставить и настраивать больше нечего.

В каркасе ровно то же, что собирается вручную ниже: bootstrap.php с классом приложения, файл call, PSR-4 Main\ → main/, готовый MainController и monolog/monolog в require-dev — чтобы логи было куда писать сразу.

Через Docker, если PHP нет

create-project — тоже PHP-программа, но запустить её можно в одноразовом контейнере: образ несёт PHP внутри, а проект остаётся у вас в примонтированном каталоге.

docker run --rm -v "$PWD":/app -w /app composer:2 \
  create-project flytachi/winter my-app --ignore-platform-reqs

--ignore-platform-reqs нужен потому, что ядро требует ext-pcntl и ext-posix — они нужны работающему приложению, а не установщику, и в рабочем образе они есть.

Дальше проект поднимается своим контейнером, где Swoole уже собран, а консольные команды выполняются тем же одноразовым способом. Подробно, с командами — в Быстром старте.

Сборка проекта с нуля

1. Каталог и зависимость

mkdir my-app && cd my-app
composer require flytachi/winter-kernel

2. Каталог кода и автозагрузка

Winter ничего не навязывает: каталог и пространство имён выбираете вы — дальше в примерах это main/ и Main\.

mkdir main

Теперь свяжите их в composer.json:

{
  "autoload": {
      "psr-4": {
          "Main\\": "main/"
      }
  },
  "require": {
      "php": ">=8.4",
      "flytachi/winter-kernel": "^4.0"
  }
}

composer dump-autoload

3. Класс приложения — bootstrap.php

Это единственный файл настройки. Он подключает автозагрузчик и объявляет, из чего состоит приложение:

<?php

declare(strict_types=1);

use Flytachi\Winter\Kernel\App\Attribute\EnableWeb;
use Flytachi\Winter\Kernel\WinterApplication;

require __DIR__ . '/vendor/autoload.php';

#[EnableWeb]
final class Application extends WinterApplication
{
  public static function main(array $argv): never
  {
      parent::run($argv);
  }
}

Хуков, которые нужно переопределять, здесь нет — всё остальное живёт в обычных классах, которые находит сканер. Что можно объявить помимо #[EnableWeb] — на странице Состав приложения.

Каталог этого файла становится корнем проекта: от него отсчитываются .env, storage/, resources/ и начало обхода файлов.

4. Файл запуска — call

Через него идут все команды, включая запуск сервера:

#!/usr/bin/env php
<?php

if (PHP_VERSION_ID < 80400) {
  echo "Please use PHP version 8.4 or higher. Current: " . PHP_VERSION . "\n";
  exit(1);
}

chdir(__DIR__);
require './bootstrap.php';

Application::main($argv);

chmod +x call

chdir() здесь обязателен: он привязывает относительные пути — .env, storage/, resources/ — к каталогу проекта, а не к тому, откуда вы вызвали команду.

5. Окружение и каталоги

php call cfg init       # .env из шаблона + свежий WINTER_KEY
php call storage init   # служебные каталоги внутри storage/

Получившийся .env минимален:

WINTER_KEY=<сгенерированный ключ>
TIME_ZONE=UTC
DEBUG=true

Остальные переменные — база, логи, параметры сервера — добавляются по мере надобности, см. Конфигурацию.

6. Первый контроллер

php call make -c .Main   # → main/MainController.php

Генератор создаёт рабочую заготовку: метод hello() с атрибутом #[RequestMapping] без аргументов. Такой атрибут монтирует метод по имени класса и отвечает на все основные HTTP-методы — проверить можно, не открывая файл:

php call mapping show

 | [ Routes (5) ]
|	 GET     /main                                 → Main\MainController::hello
|	 POST    /main                                 → Main\MainController::hello
|	 PUT     /main                                 → Main\MainController::hello
|	 PATCH   /main                                 → Main\MainController::hello
|	 DELETE  /main                                 → Main\MainController::hello
| [ Routes ]

Что получилось

my-app/
├── bootstrap.php     — класс приложения: из чего оно состоит
├── call              — точка входа для всех команд
├── composer.json     — автозагрузка и зависимости
├── .env              — окружение
├── main/             — ваш код
└── storage/          — служебные каталоги

Каталог resources/ для шаблонов и переводов появится, когда понадобится. Что за что отвечает — Структура проекта.

Первый запуск

php call run dev

Сервер слушает порт 8000 на всех интерфейсах.

Слово dev включает наблюдение за файлами: при изменении любого .php приложение перезапускается само. В рабочем режиме запускают без него — php call run.

Адрес и порт переопределяются флагами:

php call run dev --port=9000
php call run dev --host=127.0.0.1 --port=9000   # только локально

Что делает cfg init

Команда одна, а действий несколько — их стоит знать, потому что одно из них необратимое.

Склонировали существующий проект

После git clone каркас уже есть, но всё, что не попадает в репозиторий, нужно создать заново:

composer install

php call cfg env -i       # создать .env, если его нет
php call cfg key -g       # сгенерировать свой WINTER_KEY
php call storage init     # создать каталоги внутри storage/

php call run dev

Право на исполнение у call хранится в самом репозитории, так что chmod +x обычно не нужен. Если файл всё же пришёл без него — например, через архив, — верните бит: chmod +x call.

Пакеты по надобности

В ядре нет ни слоя базы данных, ни клиента Redis: они живут отдельными пакетами и ставятся, когда нужны. Ядро подхватывает их само — ничего включать не требуется.

composer require flytachi/winter-ppa      # база: репозитории, сущности, миграции
composer require flytachi/winter-redis    # Redis: сторы, хеши, списки, стримы
composer require flytachi/jwt             # JWT и JWKS

Пока пакет не установлен, команды, которым он нужен, не падают со стеком, а объясняют, чего не хватает:

 | [!] The 'db' command needs the database layer, which is not installed.
| [i] Add it with:  composer require flytachi/winter-ppa

Что дальше — PPA, Redis, Экосистема.

Что ещё пригодится сразу

Автодополнение в терминале — подсказки по командам и их аргументам:

php call cfg completion -i

Конфигурация Docker — Dockerfile, docker-compose.yml и каталог docker/ с точкой входа под Swoole:

php call cfg docker

Режим выбирается переменной DEV, и по умолчанию она выключена:

docker compose up            # рабочий режим
DEV=true docker compose up   # разработка: перезапуск при изменении файлов

Дальше

• Быстрый старт — первый маршрут за пять минут
• Структура проекта — что за что отвечает
• Состав приложения — веб, процессы, демоны, планировщик
• Конфигурация — переменные окружения