CLI: phpc fcgi — long-lived FastCGI worker entry (wraps #173)

[PurHur]

Category

runtime / tooling (web deploy)

Problem

#173 tracks the FastCGI protocol adapter (record loop, param mapping, nginx/php-fpm compatibility). #2397 tracks 009-FastCGIWeb deploy smoke after the adapter lands.

There is no focused issue for the user-facing CLI that operators run in production:

phpc fcgi --project examples/009-FastCGIWeb
# or: php bin/fcgi.php …

Without a CLI issue, adapter work in #173 risks landing as an internal library with no documented flags, env, or phpc doctor row.

php-src reference

• sapi/fpm/fpm/fpm_main.c — php-fpm worker loop (behavioral reference, not code port)
• main/fastcgi.c — FastCGI record I/O in php-src
• sapi/cgi/cgi_main.c — CGI param mapping (reuse patterns from this repo’s bin/cgi.php)

Repro (today)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./phpc fcgi --help'

This compiler: subcommand missing or stub — operators cannot start a FastCGI worker via phpc.

Goal

1. phpc fcgi subcommand in bin/phpc.php → lib/Cli/PhpcFcgi.php (name TBD)
2. bin/fcgi.php thin entry for packaged deploy trees (mirror bin/serve.php / bin/cgi.php)
3. Flags: --project / manifest path, listen socket or stdin/stdout FastCGI mode (document v1 scope)
4. phpc doctor --gates + docs/local-ci-matrix.md row after CI: FASTCGI_SMOKE_GATE opt-in in ci-local after #173 lands #1899 smoke exists
5. examples/009-FastCGIWeb/README.md documents production invocation

Scope (v1)

In scope	Out of scope
Wrap #173 adapter; map FastCGI params → CGI superglobals	Full Zend php-fpm feature parity
Run AOT binary from phpc.json build.output	In-process JIT per request (#207)
Health route parity with 009 (ok + PATH_INFO diagnostics)	Windows IIS FastCGI

Implementation hints

Piece	Path	Notes
Adapter	lib/Web/FastCgi*.php (#173)	Reuse CGI overlay from deploy-smoke (#665, #718)
CLI	lib/Cli/PhpcFcgi.php, bin/fcgi.php	Mirror PhpcServe / PhpcCgi patterns
Deploy	phpc deploy tree	Optional public/fcgi.php shim — coordinate #635 ✅
Test	test/unit/FastCgiIntegrationTest.php	@group serve; blocked until #173
CI	#1899	FASTCGI_SMOKE_GATE — not #2369 (009 VM/AOT example smokes)

Done when

• phpc fcgi --help documents flags and links Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173 / Docs: Production deployment guide (nginx + AOT binary + CGI/FastCGI) #445
• With adapter green: phpc fcgi --project examples/009-FastCGIWeb serves health ok via FastCGI client test (local loopback)
• Harness verify (no GitHub Actions):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./phpc fcgi --help'
# after #173:
./script/docker-exec.sh -- bash -lc 'FASTCGI_SMOKE_GATE=1 ./script/ci-local.sh'

Dependencies

• Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173 — protocol adapter (blocker)
• Examples: 009-FastCGIWeb minimal fixture for phpc deploy + FastCGI adapter #2331 ✅ — 009 fixture
• CI: FASTCGI_SMOKE_GATE opt-in in ci-local after #173 lands #1899 — opt-in CI smoke (follows CLI + adapter)
• Testing: 009-FastCGIWeb phpc fcgi deploy smoke after #173 lands #2397 — deploy smoke (after this + Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173)
• Docs: Production deployment guide (nginx + AOT binary + CGI/FastCGI) #445 — production nginx doc

De-duplication

Issue	Relationship
#173	Protocol implementation — this issue is CLI/DevEx wrapper only
#2369	Promotes 009 VM/AOT example smokes — not FastCGI protocol
#1899	CI gate for adapter integration — lands after #173 + CLI

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 3 — Web AOT
• Epic product path: compile small web app without Zend at runtime

[PurHur]

claim: cursor-agent-lane-a — starting this run