Add --format flag to bin/cluster (console|line|json)

[odahcam]

Problem

The cluster watcher in bin/cluster hard-wires the log formatter based on whether --file is used: ConsoleFormatter for STDOUT, LineFormatter for files. Both are text formats.

Applications shipping logs to a structured-log backend (DigitalOcean App Platform, Datadog, ELK, GCP Cloud Logging, …) need JSON output so context fields (channel, level_name, datetime, custom context like requestId) become first-class queryable fields rather than being buried as a stringified suffix in a text line.

Today the only ways to get JSON are: vendor the binary, replace it with a custom watcher entry point, or post-process logs downstream. Each is a maintenance burden for a 10-line conceptual change.

Proposed change

Add a new --format <console|line|json> flag to bin/cluster. Default behaviour is preserved:

• No --format, no --file → console (current default).
• No --format, --file set → line (current default).
• --format json → Monolog\Formatter\JsonFormatter (one JSON object per line, all fields structured).

The format and transport are now independent: --format json --file path works, --format console to stdout works, etc.

Invalid values throw a clear Invalid --format value 'X'. Valid: console, line, json message.

Backwards compatibility

• All existing invocations behave identically (defaults unchanged).
• Flag is optional with no value when omitted.
• No public PHP API touched — only bin/cluster.

Test plan

Tested locally with examples/cluster/hello-world.php for all three formats and an invalid value:

$ php bin/cluster -w 1 --format json examples/cluster/hello-world.php
{"message":"Starting cluster PID 24857 with 1 workers","context":{},"level":200,"level_name":"INFO","channel":"cluster-24857","datetime":"2026-05-08T04:51:47.131421+00:00","extra":{}}
{"message":"Started cluster worker with ID 1","context":{"id":1,"pid":24862},"level":200,"level_name":"INFO","channel":"cluster-24857",...}

$ php bin/cluster -w 1 --format console examples/cluster/hello-world.php
[2026-05-08T04:51:49.143142+00:00] cluster-24917.INFO: Starting cluster PID 24917 with 1 workers [] []
...

$ php bin/cluster -w 1 --format yaml examples/cluster/hello-world.php
PHP Fatal error:  Uncaught Exception: Invalid --format value 'yaml'. Valid: console, line, json

I can add unit tests if there's a precedent for testing bin/cluster itself — I didn't find one in test/, so left it as a manual exercise consistent with the existing CLI surface.

Why we are filing this

We run a multi-worker ReactPHP cluster and ship logs to DigitalOcean's log explorer, which treats text-suffix JSON as opaque text. Bumping bin/cluster to support JSON output is the smallest correct change and keeps the binary as a single source of truth instead of every consumer maintaining a custom launcher.

[trowski]

Thanks!