DevEx: phpc.json autoload phase 2 — static class discovery for AOT project build

[PurHur]

Category

bootstrap | stdlib (tooling)

Problem

#155 ✅ shipped VM-side PSR-4 autoload parsing in phpc.json for phpc serve. #1762 tracks dynamic require $path discovery for phpc build --project.

There is no middle step: static class references (new Router(), type hints, Router::class) in the entry TU should expand the AOT link graph without hand-maintaining every file in includes[].

003-MiniWebApp today lists explicit includes[] in phpc.json — workable but brittle for larger apps and self-host bundles (#1492).

php-src reference

N/A (build-tooling). Behavioral reference: Composer PSR-4 autoload + static analysis patterns in php-src build scripts.

Repro (failure today)

examples/003-MiniWebApp/phpc.json lists ~15 explicit includes[] entries. Removing a class file from the list but keeping a new ThatClass() reference in public/index.php causes link/compile failure or missing symbol at AOT execute.

Minimal fixture (to add)

test/fixtures/aot/projects/psr4_static/
  phpc.json
  public/index.php   # <?php use App\Greeter; echo (new Greeter())->hi();
  src/Greeter.php    # namespace App; class Greeter { public function hi(): string { return 'hi'; } }

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/compile.php --project test/fixtures/aot/projects/psr4_static -o /tmp/psr4_static 2>&1'

Expected (after fix)	Today
/tmp/psr4_static runs, prints hi	Graph missing src/Greeter.php unless manually in includes[]

Scope (this repo)

Layer	Files	Notes
Manifest	lib/Web/ProjectManifest.php	Reuse #155 PSR-4 prefix map
Graph BFS	lib/AOT/ProjectGraph.php or AutoloadDiscovery.php	Entry → static requires → referenced class names → PSR-4 paths
Compiler metadata	lib/Compiler.php	v1: syntactic scan for new Class, Class::, extends/implements
Lint	bin/lint.php, phpc lint --project	Actionable error for unresolved class → file
Link	lib/AOT/Linker.php	Multi-.o already works (#752)
Tests	test/unit/ProjectGraphTest.php, fixture above
Docs	docs/phpc-json.md	Autoload discovery tier

Done when

• phpc build --project test/fixtures/aot/projects/psr4_static -o /tmp/app links and /tmp/app prints hi
• phpc lint --project reports missing PSR-4 target with class + expected path
• 003-MiniWebApp can drop redundant includes[] rows (follow-up PR, not blocking close)
• ./script/ci-local.sh --filter ProjectGraphTest green (or ci-fast subset)
• Cross-link AOT: Dynamic require/include discovery for project build (phase 2 of #154) #1762 for dynamic require $var tier (out of scope here)

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter ProjectGraphTest'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/compile.php --project test/fixtures/aot/projects/psr4_static -o /tmp/psr4_static && /tmp/psr4_static'

Dependencies

• DevEx: PSR-4 autoload paths in phpc.json project manifest #155 ✅ — manifest autoload schema
• AOT: Link multiple translation units into one binary #154 / AOT: MiniWebApp phpc build --project native link fails on master (post-#568/#734) #752 ✅ — multi-TU link
• AOT: Dynamic require/include discovery for project build (phase 2 of #154) #1762 — dynamic require tier (phase 2)
• Language: PHP namespaces (namespace, use, qualified names) #84 — namespaces in compiler ✅

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 3 · Self-host Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 · examples/003-MiniWebApp/phpc.json