Web: JIT/AOT mode for bin/serve.php (compile per script on first request)

[PurHur]

Problem

bin/serve.php always uses VM (Runtime → lib/VM.php). Dev servers for Zend PHP often use OPcache; we have JIT (#153 cache) but no serve integration.

Contributors benchmarking 001-SimpleWeb cannot compare VM vs JIT latency under real HTTP without manually invoking bin/jit.php per script. 003-MiniWebApp phpc serve --jit remains blocked on project includes (#475, #1770) even after OOP compliance lands.

Goal

phpc serve --jit 127.0.0.1:8080 examples/001-SimpleWeb

Compiles .php scripts with bin/jit.php on first hit, caches (#153), falls back to VM on compile error. Output must match VM for the same request (superglobals, headers, static files).

Blocker matrix (May 2026)

Blocker	Issue	Status	Unblocks
Static include in JIT	#475	open	flat examples 001
Project graph JIT	#1770	open	003 multi-file
Runtime superglobals in JIT	#49	partial	per-request $_GET/$_POST
On-disk JIT cache	#153	open	warm second request
Serve tests in CI	#234	closed	local ci-local.sh

Not required for North Star 1 — VM + AOT execute already green (#1044 ✅).

Implementation hints

Area	Files	Notes
CLI	bin/phpc.php, bin/serve.php	--jit flag; document in phpc serve --help
Request path	lib/Web/DevServer.php	On cache miss: bin/jit.php compile → store artifact
Superglobals	lib/Web/Superglobals.php, lib/JIT/SuperglobalInit.php	Repopulate per request before JIT entry — verify not baked sg_* (#49)
Static assets	existing static handler	Unchanged — only .php hits JIT
Errors	serve 500 mapping #152	JIT compile failure → VM fallback or 500 with PHP_COMPILER_DEBUG
Project mode	lib/Web/ProjectManifest.php	Defer until #1801 (phpc build --project --jit)

Cache directory layout (v1)

.phpc/jit-cache/<sha256(realpath+mtime)>.so   # or internal JIT artifact format

Invalidate when source file mtime changes.

Tests

• test/unit/ServeJitTest.php — @group llvm + @group serve
• First request slower than second (loose timing or compile-count hook)
• Body matches VM for examples/001-SimpleWeb/example.php?name=Dev
• Skip entire class when LlvmToolchain::isReady() false (same as Testing: JIT smoke for phpc build --project on 003-MiniWebApp #587)

Acceptance criteria

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  vendor/bin/phpunit --group serve --filter ServeJit

Second request to same script is faster than first; HTML output matches VM.

Verification (local / Docker only)

./script/ci-local.sh --filter ServeJit

Do not require GitHub Actions.

Dependencies

• Web: Runtime-populated superglobals for JIT and AOT (per-request $_GET/$_POST) #49 runtime superglobals
• JIT: On-disk compile cache for warm requests #153 on-disk JIT cache
• CI: Run JIT compliance tests in CI (fix LLVM skip in PHPUnit) #98 JIT tests green (LLVM 9)
• Language: JIT include/require compile-time lowering (#54 follow-up) #475 / JIT: Project include lowering for 003-MiniWebApp (phpc serve --jit blocked on #475) #1770 before 003 serve --jit
• CLI: phpc build --project --jit for MiniWebApp graph #1801 optional project JIT CLI parity

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 (Phase 3 polish / performance)
• Performance Performance: Reduce JIT compile-time overhead (target under 50ms cold start) #94 cold-start target
• Docs Docs: JIT run-matrix parity — capabilities-syntax web rows + examples/README (#1770) #1792 run-matrix parity when landed

[PurHur]

Implementation expansion (batch 24)

Architecture

Add a JitServeRuntime (name TBD) beside VM serve path:

phpc serve --jit
  → DevServer::handleConnection()
    → Superglobals::populateFromRequest()   # #49
    → JitServeRuntime::runScript($path)     # cache lookup → compile → call native entry
    → emit HTTP response (headers from context)

Step-by-step

1. bin/phpc.php — parse --jit flag on serve subcommand; pass to bin/serve.php via $argv or env PHP_COMPILER_SERVE_JIT=1.
2. bin/serve.php — after resolving docroot (Web: phpc serve uses phpc.json "public" as docroot when serving a project #443 ✅), branch:
   • default: existing Runtime / VM loop
   • --jit: JitServeRuntime with per-request superglobal refresh before calling compiled code (same order as AOT refresh in superglobals_refresh.c)
3. lib/Serve/JitServeRuntime.php (new) — responsibilities:
   • getOrCompile(string $absolutePhpPath): callable — mtime/hash key under .php-compiler-cache/ (JIT: On-disk compile cache for warm requests #153)
   • On miss: invoke same pipeline as bin/jit.php (Compiler → JIT::compile() → load .so/bitcode)
   • On compile failure: log to stderr, fall back to VM for that script (document in README)
4. Cache invalidation — compare filemtime($path) + PHP_COMPILER_BUILD_ID constant (add in lib/version.php or composer script)
5. Concurrency — flock on cache dir per script path; serve is single-threaded today but document future workers
6. Tests — extend ServeTest (not llvm): second GET to same script should not re-parse (optional timing assertion); separate @group llvm test that --jit output matches VM for examples/001-SimpleWeb/example.php

Files to touch

File	Change
bin/phpc.php	--jit flag
bin/serve.php	branch + docroot unchanged
lib/Runtime.php	extract shared bootstrap if needed
lib/JIT.php	expose compile-to-callable helper
test/real/ServeTest.php	optional --jit parity case

Verification (local / Docker)

make docker-build-22
# VM baseline
./phpc serve 127.0.0.1:8089 examples/001-SimpleWeb &
curl -s 'http://127.0.0.1:8089/example.php?name=Dev'
# JIT serve (after implementation)
./phpc serve --jit 127.0.0.1:8090 examples/001-SimpleWeb &
curl -s 'http://127.0.0.1:8090/example.php?name=Dev'
./script/ci-local.sh --filter ServeTest

Blockers (do not start before)

• CI: Run JIT compliance tests in CI (fix LLVM skip in PHPUnit) #98 — JIT compliance must execute in ci-local.sh (guard CI: ci-local.sh fail when LLVM present but JIT compliance 100% skipped #250 ✅)
• JIT: On-disk compile cache for warm requests #153 — on-disk cache (can land minimal version in same PR as Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207)

Non-goals

• AOT per-request recompile (use phpc serve --aot instead)
• GitHub Actions workflow