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.
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.
php call runWhat those attributes declare is covered on the Application components page.
Development mode
php call run dev
php call run -w # the same thing, as a flag
php call run --watcher # and as an optionThere 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:
docker compose up # production mode
DEV=true docker compose up # development: watcher on, opcache offAddress 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] |
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 socket0.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:
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:
Application stopping (SIGINT): 3 component(s)
Application stopped in 125 msThe 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
- application — the application’s status, composition and stopping it
- Application components — the
#[Enable*]attributes - Web layer configuration — workers, timeouts, limits
- Installation — the first run
- cfg docker — the image and its startup modes