DevEx: PSR-4 autoload paths in phpc.json project manifest

[PurHur]

Problem

#106 defines phpc.json for binary / serve --aot, but multi-file apps (#67, #210) need PSR-4 autoloading (App\Router in src/Router.php). Today contributors must manual require every file or rely on host PHP spl_autoload only at compile time.

Without a manifest autoload story, examples/003-MiniWebApp cannot use namespaced src/ cleanly.

Goal

Manifest keys:

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

phpc serve / bin/vm.php project mode resolves classes before compile/run.

Implementation hints

Phase A — VM serve (compile-time)

1. Extend lib/Web/ProjectManifest.php to parse autoload + includes.
2. Before Runtime::parseAndCompile, register a compile-time autoloader:
   • Map App\ prefix → src/ relative to project root
   • require_once on class file when referenced (host PHP is fine for discovery)
3. includes: require_once each path in order (for config.php constants).

Phase B — AOT (harder)

• AOT: Project build mode (entry file + dependency graph) #59 project build must walk discovered classes or explicit includes list
• AOT: Link multiple translation units into one binary #154 multi-object link needs symbol table across units
• Document: v1 may require includes listing all src/*.php until static analysis exists

Phase C — Docs + example

• docs/phpc-json.md schema
• Wire Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246 skeleton with "autoload": { "App\\": "src/" }

Tasks

• Schema doc in repo (docs/phpc-json.md)
• VM: register PSR-4 autoload before compile in bin/serve.php / phpc serve
• includes array loaded once per request
• phpc lint respects autoload when linting public/index.php
• AOT: compile discovered classes or require graph (AOT: Project build mode (entry file + dependency graph) #59, AOT: Link multiple translation units into one binary #154)
• Example in examples/003-MiniWebApp

Acceptance criteria

{ "autoload": { "psr-4": { "App\\": "src/" } } }

./phpc serve 127.0.0.1:8080 examples/003-MiniWebApp
curl 'http://127.0.0.1:8080/index.php'

App\Router resolves without manual require in public/index.php.

Verification (local only)

./script/ci-local.sh --filter ProjectManifest
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev ./phpc lint examples/003-MiniWebApp/public/index.php

Dependencies

• DevEx: phpc.json project manifest (entry, includes, public assets) #106 phpc.json manifest (binary/public subset exists)
• Language: PHP namespaces (namespace, use, qualified names) #84 namespaces in compiler (for AOT compile of namespaced classes)
• Language: include/require in JIT and AOT (multi-file applications) #54 include/require in JIT/AOT
• Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246 MiniWebApp skeleton

Related

• AOT: Project build mode (entry file + dependency graph) #59 project build mode
• AOT: Link multiple translation units into one binary #154 multi-unit AOT link

Files

• lib/Web/ProjectManifest.php, bin/serve.php, bin/phpc.php, docs/phpc-json.md