Background components

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.

Manifest #[Enable*] attributesStartup php call runWithout web yes

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:

bootstrap.php
<?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.

php
#[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:

bash
php call run       # production mode
php call run dev   # development: restart on .php changes

The 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.

text
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.

bootstrap.php
#[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:

text
Application up: http://0.0.0.0:8000 + [Heartbeat, Emails]
Application stopping (SIGTERM): 3 component(s)
Application stopped in 125 ms

The 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 dev restarts 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:

text
Application stopping (SIGTERM): 3 component(s)
Application stop: not stopped within 35s — killing Emails.
Application stopped (forced) in 35.0s

If 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.

text
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 minutes

Starting 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
php
#[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 retries

A 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 its grace and 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 status shows 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

text
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:

bootstrap.php
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:

text
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.4s

call 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.

bootstrap.php
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. Under php call run dev it 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/postgres.sh
#!/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.

bootstrap.php
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()

bootstrap.php
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.

php
$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:

php
$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 .env included;
  • by default they are ready as soon as they start;
  • by default they are not restarted: exit code 0 means the work is done, any other a failure, and critical decides what follows;
  • on a stop they get SIGTERM, and SIGKILL after grace seconds (30 by default);
  • their output goes to the application’s as it is, and with output into 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
php
$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.

php
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

  1. Checks start once the program is ready — every seconds after ready passed (or after the start, without ready). While it starts, only ready is asked.
  2. 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.
  3. A failure is logged at once, numbered: postgres alive check failed (2/6): no answer in 5s. — and shows in call application status below the program’s line: alive check failed 2/6.
  4. A passing check after failures resets the count: postgres answers its alive check again.
  5. failures failures 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_isready only opens a connection and runs no query: a long export, a heavy COPY, 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 failures or timeout.
  • Off by default. Without alive a program is not checked at all.

For a heavy database with long exports you can be more careful still:

php
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
  every: 15, timeout: 10, failures: 8),   // about two minutes without an answer

A 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.

main/Services/RedisOutput.php
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]);
  }
}
php
$components->command(['redis-server', '--port', '6379'], name: 'redis', output: new RedisOutput());
text
[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 STATEMENT become one entry.
  • Reading never loses output. A line on which line() threw is logged as it is, at INFO.
  • 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). Under call 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
php
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 instance

A 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 status shows it as FAILED, 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:

bash
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 go

The 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 -d before call 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() and relaunch() return false, and start() and dispatch() 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.

Next

  • Processes — one long-lived worker
  • Daemons — a supervised fleet of workers
  • Scheduler — tasks on a schedule
  • WebSocket — lasting connections to browsers
  • Async calls — not making the client wait for a slow operation
  • Key ideas — how this executes in a resident application