CLI · Winter Console

Команда run

run запускает не «сервер», а приложение целиком — всё, что объявлено атрибутами #[Enable*] на классе приложения. Веб-сервер, фоновые процессы, демоны и планировщик поднимаются одной командой и живут в одном жизненном цикле.

run — короткое имя команды application start: там же — состояние запущенного приложения, его остановка и то, что оно запустит. php call run --help (или -h) показывает справку и ничего не запускает.

Рантайм SwooleРазработка run devБез веба headless

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

Состав определяется атрибутами и хуком components() — команда ничего не решает за вас. Процесс run и есть приложение: он запускает каждый компонент в отдельном процессе и следит за ними.

Атрибут Что поднимется
#[EnableHttp] HTTP-сервер Swoole
#[EnableWebSocket(...)] WebSocket-сервер
#[EnableProcess(...)] Процесс
#[EnableDaemon(...)] Демон
#[EnableScheduler] Планировщик задач #[Scheduled]

Что именно запустится, с какими параметрами и настройками сервера, покажет php call application info.

Если #[EnableHttp] нет, приложение поднимается headless — без HTTP, только фоновые компоненты. Это законный и частый режим: очередь, планировщик и набор обработчиков без единого открытого порта.

bash
php call run

Что объявляют эти атрибуты — на странице Состав приложения.

Режим разработки

bash
php call run dev
php call run -w          # то же самое флагом
php call run --watcher   # и опцией

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

`dev` — это тот же Swoole

Отдельного «встроенного сервера PHP» здесь нет: и run, и run dev поднимают один и тот же Swoole-сервер. Различается только наблюдатель.

Поэтому расширение swoole нужно и для разработки — оно ставится один раз (pecl install swoole) или уже есть в образе, который создаёт cfg docker.

В контейнере режим переключается переменной, пересобирать образ не нужно:

bash
docker compose up            # рабочий режим
DEV=true docker compose up   # разработка: наблюдатель + opcache выключен

Адрес и порт

Адрес объявляется рядом с компонентом — #[EnableHttp(port: 8080)], #[EnableWebSocket(Chat::class, port: 8001)]. При запуске его можно переопределить флагом, который называет компонент по имени:

Опция Что задаёт По умолчанию
--http.port= Порт HTTP-сервера из #[EnableHttp], иначе 8000
--http.host= Адрес привязки HTTP-сервера из #[EnableHttp], иначе 0.0.0.0
--<имя>.port=, --<имя>.host= То же для WebSocket — по имени, которое показывает call app info из #[EnableWebSocket]
bash
php call run --http.port=9000
php call run dev --http.host=127.0.0.1 --http.port=9000   # только локально
php call run --http.port=9000 --chat.port=9001            # HTTP и сокет Chat

0.0.0.0 означает «на всех интерфейсах» — так контейнер виден снаружи. Для локальной разработки, когда сервер не должен быть доступен по сети, задавайте --http.host=127.0.0.1 явно. :: — все интерфейсы сразу по IPv6 и IPv4: так слушают в кластерах, где у подов только IPv6-адреса. IPv4-клиент при этом виден приложению обычным адресом (203.0.113.7), а не в форме ::ffff:203.0.113.7.

Голый --port не принимается: в приложении с HTTP-сервером и WebSocket непонятно, чей это порт. Так же и флаг с именем, которого в приложении нет: опечатка не должна незаметно оставить сервер на чужом адресе. Приложение не стартует и подсказывает, какие флаги у него есть:

text
winter: boot failed — … --port does not say whose port it is: name the component.
This application has: --http.port, --chat.port.

Если конфигуратор веб-слоя сам задаёт адрес ($server->port(…)), его слово последнее — он перекрывает и флаг, а в лог уходит предупреждение --http.port=9000 is overridden by ….

Остальные параметры сервера — не флаги

Число воркеров, лимиты запросов, таймауты и память задаются не в командной строке: они живут в переменных SERVER_* и в классе-конфигураторе веб-слоя.

Так они одинаковы во всех способах запуска — из терминала, из compose, из supervisor, — и не теряются при копировании команды. См. Настройка веб-слоя и Конфигурация.

При старте

Перед первым запросом происходит обход проекта, сборка контейнера и построение таблицы маршрутов; затем печатается баннер с составом приложения и адресом. Убрать баннер — WINTER_BANNER=off.

Дальше мастер-процесс порождает воркеров. Что именно вы увидите в ps и кто из процессов чем занят — разобрано в Обзоре консоли и в Ключевых понятиях.

Остановка

Ctrl+C или SIGTERM — приложение останавливает все компоненты корректно: HTTP-сервер даёт воркерам доработать текущие запросы, демон — доделать начатое. В контейнере сигнал приходит прямо приложению, потому что оно PID 1; специальной обвязки для этого не нужно.

Компоненты при этом всегда получают SIGTERM, что бы ни пришло приложению: Ctrl+C посылает ему SIGINT, но у процесса под приложением сработает onTerminate(), а не onInterrupt(). Начало и конец остановки видны в логе:

text
Application stopping (SIGINT): 3 component(s)
Application stopped in 125 ms

В скобках — причина: SIGTERM, SIGINT или critical failure. Подробно, вместе с остальными строками лога, — в Составе приложения.

SIGHUP (kill -HUP <pid>, docker kill -s HUP <контейнер>) ничего не останавливает: каждый компонент перезагружается по-своему, HTTP-сервер плавно перезапускает воркеры. В логе — Application reloading (SIGHUP): N component(s). Что получает каждый компонент — Сигналы приложению.

Если приложение убито так, что не успело остановить компоненты (kill -9, OOM killer), их останавливает страж — маленький процесс winter-sentinel, который приложение запускает при старте: SIGTERM, через 30 секунд SIGKILL. После этого следующий php call run стартует. Подробно — Если приложение убито.

Из другого терминала — php call application stop; состояние каждого компонента — php call application status.

Дальше