Application components
A Winter application is not necessarily a web server. It is assembled from components, and the web is only one of five: long-lived processes, supervised worker fleets, a task scheduler and WebSocket servers can run alongside it. Any of them can be the only one.
What components are and why
A component is a self-contained part of the application with its own way of working: the web answers requests, a process runs a loop, a daemon holds a fleet of workers, the scheduler starts tasks by the clock.
The problem. An application rarely has just one shape. A service with an API
almost always needs something else: draining a queue, polling a device, cleaning old
records at night. Usually that is solved from outside — separate scripts under
cron, systemd units, a third-party supervisor. And then one application becomes
several deployments: different startup methods, different configurations, different
logs, with the shared code dragged between them as a package.
The solution. Winter describes the application’s make-up inside the
application. The entry class lists with attributes what it consists of, and
php call run raises all of it together, under one configuration, with a shared
dependency container and shared logs. Need a worker — that is a line in the
manifest, not a new deployment.
The manifest
Everything is declared with attributes on the application class:
<?php
use Flytachi\Winter\Kernel\App\Attribute\EnableDaemon;
use Flytachi\Winter\Kernel\App\Attribute\EnableProcess;
use Flytachi\Winter\Kernel\App\Attribute\EnableScheduler;
use Flytachi\Winter\Kernel\App\Attribute\EnableHttp;
use Flytachi\Winter\Kernel\App\Attribute\EnableWebSocket;
use Flytachi\Winter\Kernel\WinterApplication;
require __DIR__ . '/vendor/autoload.php';
#[EnableHttp] // the HTTP server
#[EnableScheduler] // scheduled tasks
#[EnableProcess(\Main\Process\SnmpPoller::class)] // one worker
#[EnableDaemon(\Main\Process\Emails::class)] // a fleet of workers
#[EnableWebSocket(\Main\ChatSocket::class, port: 8001)] // a WebSocket server
final class Application extends WinterApplication
{
public static function main(array $argv): never
{
parent::run($argv);
}
}That is the whole launcher file. Settings live in ordinary classes the scanner finds —
see Dependency injection and
Web-layer configuration. What attributes cannot express —
conditions, values from the environment, outside programs — is declared in code, in the
components() hook.
The five components
| Attribute | What it raises | Repeatable |
|---|---|---|
#[EnableHttp(port: …)] |
The HTTP server; 0.0.0.0:8000 by default |
no |
#[EnableProcess(Class)] |
One long-lived process | yes |
#[EnableDaemon(Class)] |
A supervised fleet of workers | yes |
#[EnableWebSocket(Class, port: …)] |
A WebSocket server on its own port | yes |
#[EnableScheduler] |
The #[Scheduled] task scheduler |
no |
Repeatable means literally that: several different processes and several different daemons are declared with several lines. One class cannot be declared twice — a process runs as a single instance — and the application refuses to start, saying so.
Every attribute takes supervision parameters: what happens when the component does not start or crashes — see Supervision.
#[EnableProcess(\Main\Process\SnmpPoller::class)]
#[EnableProcess(\Main\Process\Heartbeat::class)]
#[EnableDaemon(\Main\Process\Emails::class)]
#[EnableDaemon(\Main\Process\Webhooks::class)]The HTTP server’s address is declared like a WebSocket’s — next to it:
#[EnableHttp(port: 8080, host: '127.0.0.1')]. At launch the
--http.port / --http.host flags override it,
and the web-layer configurer has the last word.
Its former name, #[EnableWeb], is deprecated and works as #[EnableHttp] without
parameters.
What is not a component
Three attributes look similar but raise nothing:
| Attribute | What it does |
|---|---|
#[EnableAsync] |
Enables proxying of #[Async] methods — see Async calls |
#[EnableCaching] |
Enables caching of methods with #[Cacheable] and its sibling attributes — see Method caching |
#[EnableActuator] |
Adds diagnostic endpoints to the web tier — see Actuator / Health |
Startup
One command raises everything listed in the manifest:
php call run # production mode
php call run dev # development: restart on .php changesThe main process — php call run, PID 1 in a container — is the application: it starts
the components and watches them. Each component, the HTTP server included, runs in a
process of its own: one that crashes comes back by the rules in
Supervision; the application is stopped, they all stop.
php call run ← the application (PID 1)
├── winter-http: manager → Worker 0..N
├── winter-process: Heartbeat
├── winter-daemon: Emails master → worker#1, worker#2
└── …One application, one run
A second php call run of the same application from the same project does not
start:
Application is already running [PID 812] (since 2026-10-29 10:14:03 +05:00). Stop it before starting it again — one application runs once per project (.winter/).
The message opens with the full class name of your application. Two runs would share the
same singleton processes. A run killed without shutting down (kill -9, docker kill)
does not stand in the way of the next — see
If the application is killed.
An application without a web tier
Remove #[EnableHttp] and the application comes up headless: processes, daemons and
the scheduler only.
#[EnableScheduler]
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication { /* ... */ }Such an application still uses the container, the configuration, logging and database access — it simply does not listen on a port. That is the ordinary way to deploy a dedicated queue handler or a nightly routine alongside the main service.
An empty manifest is an error
At least one component has to be declared. An application with no #[Enable*] at
all will not start and says so directly: No components declared, with the list of
available attributes.
Stopping
SIGTERM (docker stop, kill <pid>) or Ctrl+C in a terminal stops the whole
application. Each framework component then gets SIGTERM, whatever the application
itself received: Ctrl+C sends the application SIGINT, but its components are still
stopped with SIGTERM — the one stop signal each of them handles cleanly. That is why a
process under the application runs onTerminate(),
not onInterrupt(). An outside program gets its own stopSignal —
SIGTERM by default too.
The start and the end of a stop show in the log:
Application up: http://0.0.0.0:8000 + [Heartbeat, Emails]
Application stopping (SIGTERM): 3 component(s)
Application stopped in 125 msThe parentheses give the reason: SIGTERM, SIGINT, or critical failure when a
critical component stops the application; the last line then reads
Application stopped (critical failure) in 2.7s. The duration is in milliseconds below a
second and in seconds above. Two more lines take the place of these:
Application reloading.—php call run devrestarts after a code change;Application finished: every component has done its work.— every component of an application without a web tier finished by itself, and it exited.
A stop gives each component its own time: a process its $grace (30 seconds by
default), an outside program its grace, the HTTP server the time for requests in flight
(waiting on a stop). The application
itself waits for its components at most 35 seconds — or 5 seconds more than the
longest of those times, when it exceeds 30. Whatever has not stopped by then gets
SIGKILL, and the log names whose work was cut:
Application stopping (SIGTERM): 3 component(s)
Application stop: not stopped within 35s — killing Emails.
Application stopped (forced) in 35.0sIf any component has $grace = 0 — wait as long as it takes — the application respects
that choice and sets no time of its own.
With priorities the levels stop one after another, and their times add up:
the longest time in Low, plus Normal’s, plus High’s, plus 5 seconds. HTTP on Low (30),
processes on Normal (30) and a database on High with grace: 60.0 make 125 seconds — and
the container’s stop_grace_period must be as long.
A second stop signal — a second Ctrl+C, a second kill — does not wait: the
components left get SIGKILL at once, logged as
Application stop: a second stop signal — killing Emails.
The times nest: a component 30 seconds, the application 35, the container 40. The last
one is yours to set. docker stop waits only 10 seconds by default and then kills the
whole container, so the components’ 30 seconds would never come — that is why the
generated docker-compose.yml has stop_grace_period: 40s. In Kubernetes set
terminationGracePeriodSeconds: 40: the default of 30 cuts the application’s 35-second
budget.
Signals to the application
SIGHUP reloads the whole application and stops nothing. It is sent to the main
process — kill -HUP <pid>, in a container docker kill -s HUP <container> — and each
component reloads in its own way:
| Component | What it gets |
|---|---|
| HTTP server | SIGUSR1 — a graceful restart of its workers: requests in flight are finished |
| Process | onReload() |
| Scheduler | re-reads its schedule |
| Daemon | its own onReload(), and SIGHUP to each worker — their onReload() |
| WebSocket | onReload() — does nothing by default |
Outside program (script(), command()) |
nothing: SIGHUP’s default would end it |
The log says Application reloading (SIGHUP): 4 component(s).
SIGUSR1 and SIGUSR2 sent to the application go to the HTTP server only. To call a
process’s onUser1() / onUser2(), send the signal to the process’s own PID — shown by
php call process <Class> status.
If the application is killed
Components run in process groups of their own and do not die with the application by
themselves. Were the application killed so that it cannot stop them (kill -9, the OOM
killer), they would run on unwatched: the HTTP server would keep its port, and the next
php call run could not start.
So the application first starts a small sentinel process — winter-sentinel in ps.
The sentinel knows the group of every component. If the application is gone without
stopping them, the sentinel writes the line
winter: the application (PID 812) is gone — stopping its components to stderr, sends the components SIGTERM, SIGKILL to whatever is left after 30 seconds, and exits.
The application’s lock is free by then, and the next php call run starts. The sentinel
ignores the stop signals, so Ctrl+C in a terminal does not touch it.
In a container this does not arise: the whole container goes with PID 1. If the sentinel
dies first, the application runs on and logs a warning — from then on nothing stops the
components after a kill -9.
Supervision
What it is. The supervisor is the part of the application that starts its components and watches them: it decides whether to restart a component that crashed, give up on it, or stop the whole application.
The problem. A component that cannot run must neither lie down silently nor be restarted forever. The usual picture without rules: a worker crashes on startup over a configuration error, it is restarted hundreds of times a minute, the log says only “the process exited”, and the application looks alive all the while.
The solution. A component’s life has two phases, with different rules.
launch ──► starting ──(ready)──► running (hours, days…)
│ │
crashed, or not crashed
ready in startTimeout│
│ ▼
▼ restart after 1 → 2 → 4 s,
no retries at most retries within 30 minutesStarting lasts until the component is ready. One that breaks while starting is broken, not unlucky: a retry changes nothing and only hides the error. So there are no retries while starting.
Running begins with readiness. A crash here is a one-off (a dropped connection, memory
ran out), and the component is restarted: after 1 second, then 2, then 4 — at most
retries times within 30 minutes. One that stayed up 30 minutes starts counting afresh.
A restart that breaks while starting is one of those attempts.
The framework tells readiness by itself:
| Component | Ready when |
|---|---|
| HTTP server | It bound its port and started |
| Process | It entered run() — its dependencies are built |
| Scheduler | It started its task loop |
| WebSocket | It bound its port and accepts connections |
| Daemon | All its workers are running |
| Outside program | As soon as it starts — or once its ready check passes |
Parameters
| Parameter | Default | What it sets |
|---|---|---|
critical |
true |
What happens when the component cannot run any more: true stops the application, false leaves the component down while the rest runs on |
retries |
3 |
Restarts after a crash while running, within 30 minutes |
startTimeout |
60 |
Seconds to start; not ready by then is a failure to start. 0 waits for good |
priority |
Priority::Normal |
When the component starts and stops relative to the others — see Priority |
#[EnableHttp(retries: 5)]
#[EnableProcess(PriceImport::class, critical: false, startTimeout: 180)]
#[EnableScheduler(retries: 5)]
#[EnableWebSocket(ChatSocket::class, port: 8001, critical: false)]
#[EnableDaemon(Documents::class, startTimeout: 300)] // a daemon has no retriesA daemon is never restarted. It supervises its own workers and restarts them by its
own policy. When the daemon itself crashes or gives up, only
critical applies.
A critical component that cannot run any more stops the application: the other
components shut down cleanly and php call run exits with code 1. In a container that
shows at once — docker ps reports a restart, Kubernetes CrashLoopBackOff. A
non-critical one is left down as FAILED, and the rest of the application runs on.
What is not a failure
- A stop on request —
stop()from code or the console. The component stays down; see Controlling a running component. That holds even when the process body outlasted itsgraceand was ended by force: a stop on request is not a crash, and the component is not restarted. - Stopping the whole application.
- A process that finished its work:
run()returned. The process is not restarted and leaves no record behind:call application statusshows it as done (COMPLETED), and it can be started again like any process.
Hence the rule: a process meant to run for good must not return from run(). On an error
let it throw — then it has crashed, and the application restarts it. A process that
quietly left its loop counts as one that finished its work.
A scheduler, a WebSocket and a daemon run an endless loop that ends only on a stop. One whose loop ends by itself has crashed.
What it looks like in the log
TickProcess is up.
TickProcess crashed: killed by signal 9; restart 1 of 3 in 1s.
TickProcess is up.
Reports failed: did not start: exit code 1. It is not critical: the application runs on without it.
Importer failed: did not start: was not ready within 60s. It is critical: the application stops.What broke a start — the exception — is logged on a line of its own beside it.
Start and stop order
What it is. By default the application starts every component at once and stops them at once. An order is set when some components stand on others.
The problem. Say a database runs inside the application, as an outside program. If everything starts together, the HTTP server takes requests while the database is still coming up, and the first requests fail. Migrations have no place to go: they belong after the database but before the server. And on a stop the database gets its signal with everyone else, and may go down before the requests that use it have finished.
The solution. Every component has a priority, and the application has two methods: one runs between the database’s start and everyone else’s, the other once everything has stopped.
Priority
There are three priorities. The higher the priority, the longer a component lives: it starts earlier and stops later.
| Priority | Starts | Stops | For |
|---|---|---|---|
Priority::High |
first | last | what the rest stands on: a database, Redis, a local nginx |
Priority::Normal |
after High | in between | the application’s work: processes, daemons, the scheduler. The default |
Priority::Low |
once all is ready | first | what takes outside traffic: HTTP, WebSocket |
Every #[Enable*] and every method of components() takes a priority:
use Flytachi\Winter\Kernel\App\Priority;
#[EnableHttp(port: 8000, priority: Priority::Low)] // traffic once all is ready
#[EnableScheduler] // Normal
final class Application extends WinterApplication
{
protected static function components(Components $components): void
{
$components->command(['bin/postgres.sh'], name: 'postgres',
priority: Priority::High,
ready: ['pg_isready', '-q', '-h', '/run/postgresql'],
stopSignal: SIGINT,
retries: 3);
}
protected static function onStarting(): void
{
Migrations::apply(); // postgres is ready here
}
}Migrations is your project’s own class. How a program’s ready, stopSignal and
retries are set is in Readiness, stop signal, restarts.
A start goes level by level: High → onStarting() → Normal → Low. The
next level starts once every component of the one before it is ready — or settled
where waiting is pointless: a non-critical one failed, a component
runs outside, a program finished its work. Within a
level components start together. A critical component not ready within its
startTimeout stops the application, as without priorities — the next levels never start.
A stop goes the other way: Low → Normal → High. A level gets its signal once the one
before it is fully down: first the way in for traffic closes, then the work stops, then
the database. A second Ctrl+C still kills everything left at once.
The log names each level:
Application starting High: postgres
postgres is up.
onStarting done in 812 ms.
Application starting Normal: Scheduler
Application starting Low: Http
…
Application stopping (SIGTERM): 3 component(s)
Application stopping Normal: Scheduler
Application stopping High: postgres
Application stopped in 1.4scall application status gains a PRIORITY column, and a
component waiting for its level shows why: waits for High to be ready or
waits for onStarting.
Without priorities nothing changes
Every component is Normal unless told otherwise, the HTTP server too. An application
that sets no priority and declares no onStarting() starts and stops everything at once,
as before, and logs nothing more.
onStarting()
A method of the application class that runs once at start: when the High components are ready and the rest have not started. The place for one-off preparation — migrations above all. The container, the database layer and the logger are there.
protected static function onStarting(): void
{
Migrations::apply();
}- An error stops the start. The exception is logged, the next levels do not start,
and the application exits with
1:onStarting failed (exit code 1): the application stops. - It runs in a process of its own. What it opens — connections, timers — is not inherited by the components. Nor does what it puts in a static property or a singleton reach them: hand results on through a database, a file or a cache.
- A stop signal during
onStarting()ends it, and nothing more starts. - When it does not run: on a reload (
SIGHUP) and in console commands. Underphp call run devit runs on every restart after a code change — what it does must be safe to repeat. Migrations are.
With no High components — the database in a container of its own, say — onStarting()
runs right after the boot, before every component.
initdb belongs in the database's start script
pg_isready says only that the server accepts connections, not that the database and the
role exist. Preparing the data directory goes into the start script, as in the official
postgres image, and creating the database and the role at the top of onStarting():
#!/bin/sh
[ -s "$PGDATA/PG_VERSION" ] || initdb -D "$PGDATA"
exec postgres -D "$PGDATA"Keep the database critical (the default): if it never comes up, the migrations fail anyway.
onStopped()
A method of the application class that runs once everything has stopped — the components, the High ones last. It runs in the application’s own process and for at most 5 seconds: it is for something short — a notification, temporary files.
protected static function onStopped(): void
{
Notifier::send('service stopped');
}An exception is logged (onStopped failed) but does not undo the stop: the exit code is
what it would have been without it. Otherwise Docker with restart: on-failure would bring
the container back after an ordinary stop.
Declaring in code
Attributes are static: they take constants only. For everything else there is the
components() hook on the application class.
components()
use Flytachi\Winter\Kernel\App\Components;
#[EnableHttp]
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication
{
protected static function components(Components $components): void
{
// The scheduler runs on worker replicas only.
if (env('APP_ROLE') !== 'web') {
$components->scheduler();
}
// The port comes from the environment.
$components->websocket(\Main\ChatSocket::class, port: (int) env('CHAT_WS_PORT', 8001));
$components
->script('scripts/legacy-sync.php', critical: false)
->command(['node', 'tools/bridge.js'], name: 'bridge');
}
}The hook is called at startup, after the scan — the container is ready. What it declares
adds to the attributes. process(), scheduler(), websocket() and daemon() take what
the attributes of the same name take, supervision parameters included. service() adds a
service — a database, a cache — that knows how to start, be checked
and stop, and what it needs in the image.
A mistake in the hook — a wrong value, one class twice — stops the startup and says
where: Application::components(): retries and startTimeout cannot be negative.
Outside programs
Sometimes a program that has nothing to do with the framework has to run beside the application: an old PHP script, a tool in another language, a bridge to a third-party service. The same supervisor can look after it.
script()
A PHP script run as a program of its own, with the same PHP as the application. It is plain PHP: the framework plays no part in it.
$components->script('scripts/legacy-sync.php', args: ['--batch=500'], critical: false);The path is relative to the project root, or absolute. A missing file stops the startup
with a clear error. Its name in the log is the file name without .php; name sets
another.
command()
Any program on PATH, with its arguments:
$components->command(['node', 'tools/bridge.js'], name: 'bridge', grace: 20.0);A script and a program behave the same:
- they run in the project root with the application’s environment, the variables from
.envincluded; - by default they are ready as soon as they start;
- by default they are not restarted: exit code
0means the work is done, any other a failure, andcriticaldecides what follows; - on a stop they get
SIGTERM, andSIGKILLaftergraceseconds (30 by default); - their output goes to the application’s as it is, and with
outputinto the application’s log.
Readiness, stop signal, restarts
A program the rest stands on — a database, Redis — needs more than “started”: the others
must know when it is ready, it must be stopped with its own signal, and brought back when
it falls. command() and script() take:
| Parameter | Default | What it sets |
|---|---|---|
priority |
Priority::Normal |
Its start and stop level |
ready |
null — ready at once |
How to tell the program is ready: a command that exits 0 once it is (['pg_isready', '-q']), or 'tcp://host:port' that accepts a connection |
alive |
null — not checked |
A check that the program is still alive once started — see alive |
stopSignal |
SIGTERM |
Which signal asks it to stop: SIGINT is PostgreSQL’s fast shutdown |
retries |
0 |
Restarts after a crash within 30 minutes — as for processes, after 1, 2, 4 s |
startTimeout |
60 |
Seconds the ready check has; no effect without ready |
output |
null — output as it is |
How the program’s output becomes the application’s log — see output |
$components->command(['redis-server', 'config/redis.conf'], name: 'redis',
priority: Priority::High,
ready: 'tcp://127.0.0.1:6379',
retries: 3);The application asks the ready check every half second. The check command’s output is
discarded; a command hanging longer than 5 seconds counts as a no. Not ready within
startTimeout is a failure to start: a critical program stops the application
(postgres failed: did not start: was not ready within 60s), a non-critical one is left
down and the next level starts without it.
alive
What it is. A check that a program is still alive and answering after it started.
ready is asked only until the program is ready; alive — for as long as it runs.
The problem. A process can hang without dying: a database stops taking connections, a
service is stuck on a lock. To the application such a process is alive — its PID is there —
and it leaves it be. Requests meanwhile wait and fail on their timeout, and
call application status shows RUNNING.
The solution. The application asks the program a simple question at regular intervals — a command, or a connection to a port. A program that fails to answer many times in a row is taken for hung, stopped step by step and restarted, as one that crashed.
use Flytachi\Winter\Kernel\App\Probe;
$components->command(['bin/postgres.sh'], name: 'postgres',
priority: Priority::High,
ready: ['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres']),
stopSignal: SIGINT,
retries: 3);What alive takes
| Value | What it checks |
|---|---|
null (the default) |
nothing — no check |
['pg_isready', '-q'] |
a command: exit code 0 means alive; default timing |
'tcp://127.0.0.1:6379' |
a port: accepting a connection means alive; default timing |
Probe::command([...], every:, timeout:, failures:) |
a command, with its own timing |
Probe::tcp('127.0.0.1:6379', every:, timeout:, failures:) |
a port, with its own timing (tcp:// may be left out) |
Probe parameters
| Parameter | Default | What it is for |
|---|---|---|
every |
10 |
Seconds between checks. Checks do not overlap: the next starts only once the previous one has ended |
timeout |
5 |
Seconds one check may take. One that has not answered by then is cut off, and that is a failure |
failures |
6 |
Failures in a row that mean “hung”. One check that passes resets the count |
With these values a program is taken for hung after about a minute without a single
answer (failures × every = 6 × 10 s; when timeout is longer than every, timeout
counts instead).
How it works
- Checks start once the program is ready —
everyseconds afterreadypassed (or after the start, withoutready). While it starts, onlyreadyis asked. - Each check is a process of its own, its output discarded; only its exit code is the answer. A port is tried from a process of its own too, so the application never waits for it.
- A failure is logged at once, numbered:
postgres alive check failed (2/6): no answer in 5s.— and shows incall application statusbelow the program’s line:alive check failed 2/6. - A passing check after failures resets the count:
postgres answers its alive check again. failuresfailures in a row — the program hangs:postgres is not answering (6 checks in a row): stopping it with SIGINT.
How a hung program is stopped
Gently first, then harder — within its grace:
| When | What the program gets |
|---|---|
| at once | its own stopSignal — SIGINT, say, PostgreSQL’s fast shutdown |
after grace / 2 |
SIGTERM — if it still runs (logged postgres still running: SIGTERM.) |
after grace |
SIGKILL (postgres still running: SIGKILL.) |
When stopSignal is SIGTERM anyway, the middle step is skipped: SIGTERM, then SIGKILL
after grace. However the program ends — a clean exit with code 0 on its signal among
it — it is a crash: postgres crashed: was not answering; restart 1 of 3 in 1s. From
there on as for any crash: restarted by retries after 1, 2, 4 s, and when they are used
up critical decides. For a database killed with SIGKILL that means crash recovery at its
next start — as after kill -9.
Protection from false alarms
Killing a working program for a slow answer is worse than waiting. So:
- Only failures in a row count. A load peak, a checkpoint, a garbage collection give a failure or two, and the first passing check resets the count.
- A light check.
pg_isreadyonly opens a connection and runs no query: a long export, a heavyCOPY, locked tables do not get in its way — a busy database still answers a connection. - A generous
timeout: 5 seconds for an answer — a slow but live server makes it. - No checks when there is no point: before it is ready, while the application stops, while the program restarts.
- Seen in advance. Every failure is a line in the log. If the checks start to flicker
under load, that shows long before a restart — raise
failuresortimeout. - Off by default. Without
alivea program is not checked at all.
For a heavy database with long exports you can be more careful still:
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
every: 15, timeout: 10, failures: 8), // about two minutes without an answerA check does not see what it does not ask
pg_isready says “alive” of a database that takes connections but cannot run queries
against one stuck table. That is right: restarting a database for one long lock is worse
than waiting. A deeper check of your own (psql -c 'select 1') is possible — but its false
alarms are then yours.
output
What it is. The program’s output read into the application’s log: line by line, each at its own level.
The problem. Unread, a program writes to the application’s output as it is. Its
lines look different from the application’s, LOG_LEVEL does not apply to them, they
reach neither JSON nor the log file. A database error among them looks like any other
message.
The solution. Give the program an output — a class that reads one of its lines and
says what it means. The line then goes through the application’s logger: the channel is
the program’s name (blue), and the brackets hold the PID of the process that wrote it.
use FlytachiWinterKernelAppOutputLine;
use FlytachiWinterKernelAppProgramOutput;
final class RedisOutput implements ProgramOutput
{
public function line(string $line): OutputLine
{
// 12:M 15 Nov 2026 02:10:00.412 # Server initialized
if (preg_match('/^(\d+):\w \S+ \S+ \S+ \S+ ([.*#-]) (.*)$/', $line, $m) !== 1) {
return OutputLine::more($line);
}
$level = match ($m[2]) {
'.' => 'debug',
'-', '*' => 'info',
default => 'warning',
};
return OutputLine::entry($level, $m[3], pid: (int) $m[1]);
}
}$components->command(['redis-server', '--port', '6379'], name: 'redis', output: new RedisOutput());[2026-11-15 02:10:00] [INFO ] -redis- [12]: Server initialized
[2026-11-15 02:10:00] [WARN ] -redis- [12]: Memory overcommit must be enabled!What line() can return:
| Call | What it means |
|---|---|
OutputLine::entry($level, $message, $context, $pid) |
The line starts an entry. A PSR-3 level ('info', 'error'…); $pid — who wrote it, the program itself by default |
OutputLine::more($text, $key) |
The line continues the entry before: with $key, into its context under that key; without, to wherever the line before went |
OutputLine::skip() |
Do not log the line |
- An entry is logged once the next one starts, or the program is quiet for a moment.
So its continuations have time to join it: an error and its
STATEMENTbecome one entry. - Reading never loses output. A line on which
line()threw is logged as it is, atINFO. line()is called in the application’s process, for every line. It must be quick and keep no state between calls.- A program that writes without pause does not hold the supervisor: each look reads a limited portion.
- Sizes are bounded. A line is up to 128 KB, an entry with its continuations up to
3 MB; the rest is cut, and the entry ends with how much:
… (cut: 9.2 MB more). Undercall run dev— 1 MB and 16 MB.
PostgreSQL comes with a parser of its own.
Code only
Outside programs are not controlled with call process: they have no class, and so no
status record. They live exactly as long as the application.
Controlling a running component
While the application runs, it starts the processes — from code in any process as
from the console (call process … start, call daemon … start, call schedule start,
with or without -d).
| Call | What happens |
|---|---|
Class::stop() |
The component stops and stays stopped: the application does not restart it |
Class::dispatch() |
The application starts the component — stopped, failed (FAILED) or done with its work — afresh, its restart count back to zero. Returns the new process’s PID |
Class::relaunch() |
A restart: stop and start again at once. Not counted as a crash |
Class::start() |
For a declared component — refused with ProcessManagedException: it runs in the application’s processes, not in the calling one |
InboxWatcher::stop(); // stopped; the application will not bring it back
$pid = InboxWatcher::dispatch(); // running again, inside the application
InboxWatcher::relaunch(); // a restart, after a settings change for instanceA stop holds for the current run of the application: once the application restarts, everything declared comes up again.
Starting a process that is not declared
A process that is not among the application’s components is started through the application too — it takes it in for one run:
- no retries: once it crashed, it is down;
- never critical: neither a crash nor anything else stops the application;
- done with its work or stopped — the application lets it go;
- crashed —
call application statusshows it asFAILED, with why, until it is started again; - a stop or restart of the application does not bring it back: it is temporary.
A declared component is started with its own parameters (retries, critical,
startTimeout) — as at the application’s start.
That makes it easy to switch on what is not always needed. Say the scheduler is not among the components, and once a month it is switched on for a couple of days:
php call schedule start # the application takes the scheduler in
php call app status # it is in the "Adopted" list
php call schedule stop # and the application lets it goThe same from code: ReportExport::dispatch() in a controller starts the export inside
the application — it shows in call application status, and it stops with the application.
Class::start() of a process that is not declared still runs it in the calling process:
it asks for “run it here”, not “start it in the background”.
Two more cases you need not worry about:
- The component already runs outside the application — started with
call process … start -dbeforecall run, say. The application neither fails nor fights it: it waits for that one to end, then starts its own. - The component or the whole application runs in another environment — its record is
visible through the mounted project’s shared
.winter/, but the process is in another container. Such a record is left alone:stop()andrelaunch()returnfalse, andstart()anddispatch()refuse, pointing to where it runs. Otherwise a second instance would run beside the application — a second scheduler, say, firing every task twice. The record of a container killed without a stop (docker kill, out of memory) and recreated on the same tree does not get in the way: nobody holds its lock, and the component starts. Containers on one machine see that; a macOS host and a container do not see each other’s locks.
What to choose
The five tools are easy to confuse, because all of them “do something in the background”. They separate on the question of when the work should run.
| You need to | Tool |
|---|---|
| Do a piece of work without keeping the client waiting | #[Async] |
| Run one endless loop: listen to a queue, poll a device | A process |
| The same, but in several hands, with crashed ones restarted | A daemon |
| Run on a schedule: every 5 minutes, every night at 3:00 | The scheduler |
| Keep connections to browsers open and send them messages right away | WebSocket |
The boundaries are worth spelling out, because that is where the mistakes happen:
#[Async] is not a background job. The method goes into its own coroutine and
interleaves with the calling code on I/O waits, but the work stays inside the same
worker and lives exactly as long as it does: a restart loses it, it will not move
to another machine, and it has no queue. Good for not making the client wait; not
good for guaranteeing an email is delivered — that needs a process or a daemon with
a queue.
Process versus daemon. A process is one instance; a daemon is several under supervision, with a restart policy and scaling. If the work divides into independent units and one worker is not enough, take a daemon; if the task is one by nature — listening on a single socket, holding a single connection — take a process.
The scheduler versus a process with sleep(). A loop with sleep(300) inside a
process looks like the simple answer, but with it you take responsibility for
keeping a task from overlapping itself, for what happens after a restart, and for
schedules expressed in wall-clock terms. The scheduler already handles all of that.