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

Установка

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

Требования

Требование Значение
PHP 8.4 или выше
Composer 2.x
Расширения ext-pcntl, ext-posix, ext-fileinfo
Для веб-приложения ext-swoole

Веб-слой работает только на Swoole

Winter не использует встроенный сервер PHP. Если приложение объявляет #[EnableWeb], запуск требует расширение Swoole и без него откажется стартовать:

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

Это касается и режима разработки — он отличается только наблюдением за файлами, сервер тот же самый.

Приложению без веба — только процессы, демоны или планировщик — Swoole не обязателен.

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

Расширение Зачем
ext-pdo Доступ к базе данных
ext-simplexml Разбор XML в теле запроса
ext-bcmath, ext-decimal Точные числовые типы при привязке параметров
ext-shmop Передача данных между процессами в Swoole-режиме

Проверка окружения

php -v покажет версию, php -m — список расширений. Отсутствие swoole в этом списке — самая частая причина, по которой первый запуск не удаётся.

Два пути

Путь Когда
Готовый каркас — create-project Новый проект; нужен работающий скелет за одну команду
С нуля — require winter-kernel Встраивание в существующий проект, своя раскладка, или желание понимать каждый файл

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

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

Всё. Composer после установки сам выполняет storage init и cfg init, поэтому каталоги и .env со свежим WINTER_KEY уже на месте.

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

Дальше можно не читать

Если каркас подошёл, переходите к Быстрому старту. Раздел ниже — для тех, кому нужно собрать проект руками или понять, из чего он состоит.

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

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

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

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

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

bash
mkdir main

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

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

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

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

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] — на странице Состав приложения.

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

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

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);
bash
chmod +x call

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

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

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

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

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

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

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

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

Генератор создаст рабочую заготовку — её достаточно, чтобы проверить, что всё собралось.

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

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

Каталоги resources/ для шаблонов и переводов появятся, когда понадобятся.

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

bash
php call run dev

Сервер слушает порт 8000 на всех интерфейсах — откройте http://localhost:8000.

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

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

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

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

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

bash
composer install
chmod +x call

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

php call run dev

Ключ у каждой установки свой

WINTER_KEY не переезжает из чужого проекта или из репозитория — генерируйте его на месте. Файл .env по той же причине не коммитится.

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

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

bash
php call cfg completion -i

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

bash
php call cfg docker

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

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

Дальше