DevEx: phpc.json project manifest (entry, includes, public assets)

[PurHur]

Problem

Today each file is compiled in isolation (bin/compile.php file.php or phpc build entry.php). Multi-file apps need documented flags and manual dependency tracking (#59). phpc serve --aot already reads a minimal phpc.json via lib/Web/ProjectManifest.php (binary field only) — but there is no schema, validator, or phpc build --project graph compile.

Goal

phpc.json at project root:

{
  "entry": "public/index.php",
  "binary": ".phpc/bin/app",
  "include_path": ["src"],
  "compile": { "superglobals": "runtime" },
  "assets": ["public/**"]
}

One command builds a deployable binary from the manifest; phpc serve --aot resolves the same paths.

Implementation hints

1. Extend ProjectManifest (lib/Web/ProjectManifest.php) — already walks parents for binary; add entry, include_path, optional assets glob list.
2. phpc build --project [dir] in bin/phpc.php → delegate to bin/compile.php with resolved entry + -o from manifest (until AOT: Project build mode (entry file + dependency graph) #59 multi-TU graph exists, document single-entry limitation).
3. Validator — share schema with DevEx: phpc.json JSON Schema and phpc validate-manifest #263 (phpc validate-manifest); start with JSON Schema in docs/phpc-json-schema.json.
4. Examples — Examples: Minimal phpc.json for 001-SimpleWeb and 002-StaticWeb #274 adds minimal manifests for 001/002; DevEx: phpc.json project manifest (entry, includes, public assets) #106 example target is examples/003-MiniWebApp/phpc.json once Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246 scaffold lands.
5. Serve/CGI — document interaction with Web: CGI/1.1 request driver (stdin/stdout, env, Status line) #50 CGI driver and AOT: Deploy bundle (binary + public assets + phpc.json manifest) #180 deploy bundle.

Tasks

• Schema + validator (DevEx: phpc.json JSON Schema and phpc validate-manifest #263 can land first or together)
• phpc build --project reads manifest, invokes compile with entry path
• ProjectManifest::resolveEntry() for serve-aot docroot scripts
• README + Docs: examples/README — phpc/vm/aot run matrix per example folder #262 examples matrix row for phpc.json

Acceptance criteria

cd examples/001-SimpleWeb   # after #274 manifest exists
phpc build --project .
phpc serve --aot 127.0.0.1:8080 .
curl -s 'http://127.0.0.1:8080/example.php?name=Dev' | grep 'Hello Dev'

Verify in Docker only:

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  ./phpc build --project examples/001-SimpleWeb

Dependencies

• AOT: Project build mode (entry file + dependency graph) #59 multi-file compile graph (full multi-TU — follow-up)
• Language: include/require in JIT and AOT (multi-file applications) #54 include/require in JIT/AOT
• Examples: Minimal phpc.json for 001-SimpleWeb and 002-StaticWeb #274 example manifests

Related

• DevEx: bin/serve.php — local HTTP server for web development #88 serve (closed), Reference app: examples/003-MiniWebApp (router, templates, forms) #67 MiniWebApp, AOT: Deploy bundle (binary + public assets + phpc.json manifest) #180 deploy bundle
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP Phase 3

[PurHur]

Merged #434: phpc build --project [dir] reads entry + binary from phpc.json and invokes compile.php. Pre-build validation via ManifestValidator::validateForBuild. AOT smoke on examples/002-StaticWeb.

Remaining for full #106: multi-TU graph (#59), includes bundling, assets copy, deploy bundle (#180).