AOT: Dynamic require/include discovery for project build (phase 2 of #154)

[PurHur]

Category

bootstrap | language (AOT project graph)

Problem

#752 ✅ / #59 shipped static project build: phpc.json includes[] + ProjectGraph BFS over literal require paths. 003-MiniWebApp and self-host bundles rely on explicit manifest lists.

Remaining gap: apps that use dynamic includes (require $path, PSR-4 autoload, conditional requires) cannot phpc build --project without manually listing every file. Self-host M4/M5 needs either full graph discovery or documented static bundling policy.

#154 phase 1 (explicit multi-TU link) is largely shipped; this tracks phase 2.

#1803 / #1856 cover phpc.json autoload schema + migrating 003 — this issue is the compiler graph walk that consumes that manifest.

php-src reference

• N/A (tooling) — behavior mirrors Zend autoload + compile-time include resolution patterns used by OPcache preloading
• Compare: php-src ext/opcache preload file list build; PSR-4 equivalent in Composer ClassLoader.php

Repro (failure today)

test/fixtures/aot/projects/psr4_mini/ (to be added) with:

{ "entry": "public/index.php", "autoload": { "psr-4": { "App\\": "src/" } } }

// public/index.php
require __DIR__ . '/../vendor/autoload.php'; // not needed — direct class ref
echo (new App\Greeter())->hi();

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

Expected (after fix): link succeeds; /tmp/psr4_mini prints greeting.
Actual today: unresolved class / missing TU unless src/Greeter.php hand-listed in includes[].

Dynamic require lint:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./phpc lint --project examples/003-MiniWebApp 2>&1 | head -20'
# dynamic require $path should report actionable error (not silent omit)

Goal

phpc build --project optionally discovers PHP files reachable from entry via:

1. Static string require/require_once/include (extend Language: include/require in JIT and AOT (multi-file applications) #54 AOT lowering)
2. phpc.json "autoload": { "psr-4": { "App\\": "src/" } } — compile referenced classes (DevEx: PSR-4 autoload paths in phpc.json project manifest #155)
3. Fail with actionable lint report for truly dynamic paths (require $var)

Scope (this repo)

Piece	File	Notes
Graph walk	lib/AOT/ProjectGraph.php	Extend BFS: literal include edges + autoload class files
Manifest	lib/Web/ProjectManifest.php	Parse autoload.psr-4; validate paths exist
Class discovery	new lib/AOT/AutoloadResolver.php	Map App\Router → src/Router.php (PSR-4)
Compiler	lib/Compiler.php	Record TYPE_INCLUDE literal targets in compile unit metadata
Lint	bin/lint.php, UnsupportedRegistry	phpc lint --project reports unresolved dynamic includes
Link	lib/AOT/Linker.php	Multi-.o already works (#752)
JIT parity	#475, #1770	JIT project graph should share resolver when possible
Tests	test/unit/ProjectGraphTest.php, test/fixtures/aot/projects/psr4_mini/	Static vs dynamic require fixtures

Suggested fixture layout

test/fixtures/aot/projects/psr4_mini/
  phpc.json          # entry + autoload psr-4
  public/index.php   # uses App\Greeter
  src/Greeter.php

Unblock order

#1803 manifest schema → AutoloadResolver → ProjectGraph BFS → psr4_mini fixture → #1856 migrate 003

Lint error shape (actionable)

error: dynamic require at Router.php:42 — add file to phpc.json includes[] or use literal require

Done when

• phpc build --project test/fixtures/aot/projects/psr4_mini links and executes without hand includes[]
• phpc lint --project errors on require $dynamic with file:line + hint
• ./script/ci-local.sh --filter ProjectGraph green (new psr4_mini case)
• AOT: Link multiple translation units into one binary #154 phase 2 row marked ✅; DevEx: phpc.json autoload phase 2 — static class discovery for AOT project build #1803 schema consumed

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./script/ci-local.sh --filter ProjectGraph'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./phpc lint --project examples/003-MiniWebApp'

Dependencies

• AOT: Link multiple translation units into one binary #154 — phase 1 multi-TU link ✅
• DevEx: phpc.json autoload phase 2 — static class discovery for AOT project build #1803 — phpc.json autoload schema
• Language: include/require in JIT and AOT (multi-file applications) #54, Language: JIT include/require compile-time lowering (#54 follow-up) #475 — literal include lowering
• Self-host: Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 M4/M5

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 3 Web AOT
• Parent: AOT: Project build mode (entry file + dependency graph) #59, AOT: Link multiple translation units into one binary #154

[PurHur]

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

[PurHur]

PR #3854: phpc build --project now passes ProjectGraph::resolve() units (PSR-4 + literal includes) to compile.php --include. psr4_static AOT binary prints hi; Psr4StaticAotExecuteTest guards regression. Dynamic require $path lint already covered by PhpcLintProjectTest.

[PurHur]

claim: cursor-agent-lane-b — continuing PR #3854 verification and merge

[PurHur]

Merged via PR #3854 (squash).

Verification (Docker)

```bash
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/unit/Psr4StaticAotExecuteTest.php'

OK (1 test, 6 assertions)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
rm -rf test/fixtures/aot/projects/psr4_static/.phpc
./phpc build --project test/fixtures/aot/projects/psr4_static
test/fixtures/aot/projects/psr4_static/.phpc/bin/app
'

hi

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/unit/ProjectGraphTest.php --filter Psr4'

OK (2 tests, 9 assertions)

```

`phpc build --project` now passes `ProjectGraph::resolve()` units as `--include` so PSR-4 autoload discovery reaches the AOT linker without manual `includes[]`.