AOT: Honor phpc.json includes array in phpc build --project

[PurHur]

Problem

docs/phpc-json.schema.json and ManifestValidator accept an optional "includes": ["src/helpers.php", ...] array, but phpc build --project only compiles the manifest entry script today. Extra PHP files listed in includes are validated on disk yet not linked into the AOT binary.

MiniWebApp (#246, #67) and multi-file apps need either:

• explicit manifest paths before AOT: Project build mode (entry file + dependency graph) #59 full dependency graph, or
• working include/require lowering (Language: include/require in JIT and AOT (multi-file applications) #54).

Without this, contributors must manually merge helpers into one file or wait for #154 multi-TU linking.

Goal

When phpc.json contains includes, phpc build --project compiles entry + each include path into one deployable binary (v1: static list only; no dynamic include $path).

{
  "entry": "public/index.php",
  "binary": ".phpc/bin/app",
  "includes": ["src/Router.php", "config.php"]
}

Implementation hints

1. ProjectManifest::resolveIncludePaths(string $projectDir, ?array $manifest): string[] — map includes[] to absolute files; error if missing.
2. bin/phpc.php build --project — pass include list to bin/compile.php (or new --includes flag).
3. bin/compile.php / lib/AOT/ — v1 may concatenate compile units if AOT: Link multiple translation units into one binary #154 not ready; document limitation in manifest README.
4. phpc lint --project — already walks literal includes; align path resolution with build.
5. Tests: test/unit/ProjectManifestTest.php + AOT fixture test/fixtures/aot/cases/manifest_includes.phpt.

Acceptance criteria

• phpc build --project examples/003-MiniWebApp (once skeleton exists) produces a binary whose entry calls code from includes without manual merge
• Validator + build share the same path resolution rules
• script/capability-matrix.php --check unchanged unless new builtins

Verification (local / Docker only)

make docker-build-22
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  ./script/ci-local.sh --filter manifest_includes

No GitHub Actions required.

Dependencies

• DevEx: phpc.json project manifest (entry, includes, public assets) #106 / DevEx: phpc.json JSON Schema and phpc validate-manifest #263 manifest schema (closed)
• Language: include/require in JIT and AOT (multi-file applications) #54 include/require in JIT/AOT (full graph)
• AOT: Project build mode (entry file + dependency graph) #59 project build dependency graph
• AOT: Link multiple translation units into one binary #154 link multiple translation units

Related

• DevEx: PSR-4 autoload paths in phpc.json project manifest #155 PSR-4 autoload (orthogonal)
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP Phase 3 Web AOT