CLI · Winter Console

The run command

run starts not “a server” but the whole application — everything declared with #[Enable*] attributes on the application class. The web server, background processes, daemons and the scheduler come up with one command and share one lifecycle.

run is the short name of application start: that page also covers the running application’s status, stopping it, and what it will start. php call run --help (or -h) shows the help and starts nothing.

Runtime SwooleDevelopment run devNo web headless

What exactly starts

The composition is determined by the attributes and the components() hook — the command decides nothing for you. The run process is the application itself: it starts every component in a process of its own and watches over them.

Attribute What comes up
#[EnableHttp] The Swoole HTTP server
#[EnableWebSocket(...)] A WebSocket server
#[EnableProcess(...)] A process
#[EnableDaemon(...)] A daemon
#[EnableScheduler] The scheduler for #[Scheduled] tasks

What exactly will start, with which parameters and server settings, is shown by php call application info.

Without #[EnableHttp] the application comes up headless — no HTTP, background components only. That is a legitimate and common mode: a queue, a scheduler and a set of handlers without a single open port.

bash
php call run

What those attributes declare is covered on the Application components page.

Development mode

bash
php call run dev
php call run -w          # the same thing, as a flag
php call run --watcher   # and as an option

There is exactly one difference from a normal start — the watcher is switched on: it follows the project’s files and restarts the application on a change, and keeps an eye on memory along the way.

`dev` is the same Swoole

There is no separate “PHP built-in server” here: run and run dev both bring up the same Swoole server. Only the watcher differs.

So the swoole extension is needed for development too — it is installed once (pecl install swoole) or is already in the image cfg docker creates.

In a container the mode is switched with a variable; the image does not need rebuilding:

bash
docker compose up            # production mode
DEV=true docker compose up   # development: watcher on, opcache off

Address and port

The address is declared next to the component — #[EnableHttp(port: 8080)], #[EnableWebSocket(Chat::class, port: 8001)]. At launch a flag that names the component overrides it:

Option What it sets Default
--http.port= The HTTP server’s port from #[EnableHttp], otherwise 8000
--http.host= The HTTP server’s bind address from #[EnableHttp], otherwise 0.0.0.0
--<name>.port=, --<name>.host= The same for a WebSocket — by the name call app info shows from #[EnableWebSocket]
bash
php call run --http.port=9000
php call run dev --http.host=127.0.0.1 --http.port=9000   # locally only
php call run --http.port=9000 --chat.port=9001            # HTTP and the Chat socket

0.0.0.0 means “on every interface” — that is how a container is visible from outside. For local development, when the server should not be reachable over the network, set --http.host=127.0.0.1 explicitly. :: is every interface over IPv6 and IPv4 at once: what clusters whose pods have IPv6 addresses only ask for. An IPv4 client then reaches the application as its plain address (203.0.113.7), not as ::ffff:203.0.113.7.

A bare --port is not accepted: in an application with an HTTP server and a WebSocket it is unclear whose port it is. Nor is a flag naming no component of the application: a typo must not quietly leave the server on an address nobody asked for. The application does not start, and lists the flags it has:

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

When the web-layer configurer sets the address itself ($server->port(…)), its word is the last — it overrides the flag too, and the log says --http.port=9000 is overridden by ….

The other server parameters are not flags

The worker count, request limits, timeouts and memory are not set on the command line: they live in the SERVER_* variables and in the web layer’s configuration class.

That way they are the same however you start — from a terminal, from compose, from a supervisor — and are not lost when the command is copied. See Web layer configuration and Configuration.

At startup

Before the first request the project is walked, the container is assembled and the route table is built; then a banner is printed with the application’s composition and address. To remove the banner, set WINTER_BANNER=off.

After that the master process forks the workers. What exactly you will see in ps and which process does what is covered in the Console overview and in Key concepts.

Stopping

Ctrl+C or SIGTERM — the application stops every component cleanly: the HTTP server lets its workers finish their current requests, a daemon finishes what it started. In a container the signal reaches the application directly because it is PID 1; no special wrapper is needed for that.

The components always get SIGTERM, whatever the application received: Ctrl+C sends it SIGINT, but a process under the application runs onTerminate(), not onInterrupt(). The start and the end of the stop show in the log:

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

The parentheses give the reason: SIGTERM, SIGINT or critical failure. The details, with the other log lines, are in Components.

SIGHUP (kill -HUP <pid>, docker kill -s HUP <container>) stops nothing: every component reloads in its own way, and the HTTP server restarts its workers gracefully. The log says Application reloading (SIGHUP): N component(s). What each component gets — Signals to the application.

If the application is killed before it can stop its components (kill -9, the OOM killer), they are stopped by the sentinel — a small winter-sentinel process the application starts at boot: SIGTERM, then SIGKILL after 30 seconds. The next php call run then starts. Details — If the application is killed.

From another terminal — php call application stop; where every component stands — php call application status.

Next