Language: require_once and include_once deduplication

[PurHur]

Problem

VM supports plain include/require (#54 tracks JIT/AOT). Real apps and 003-MiniWebApp load bootstrap files multiple times:

require_once __DIR__ . '/config.php';
require_once __DIR__ . '/config.php'; // must not re-execute

Without once-semantics, side effects (constants, function declarations) double-run and break routers.

Goal

require_once / include_once skip already-loaded absolute paths in VM, JIT, and AOT (per-process for CLI; per-request rules for CGI — coordinate #49).

Implementation hints

VM (lib/VM.php)

1. Add includedOncePaths set on runtime/context (absolute normalized paths).
2. New opcodes or flags on TYPE_INCLUDE: once bit checked before executing file.
3. On hit: push true / no-op return per Zend semantics (document if different).
4. Reset policy: new request in Superglobals::populateFromEnvironment() for CGI (AOT: Per-request superglobal refresh in native binary (not compile-time bake) #201 ✅ GET; POST AOT: RuntimeSuperglobalRefreshTest dual REQUEST_BODY on one binary #257 ✅).

Compiler (lib/Compiler.php)

• Distinguish Include_::TYPE_ONCE vs plain in CFG lowering from php-cfg Include_ node kinds.

JIT / AOT

• Runtime helper php_compiler_include_once(path, already_loaded_table*) in lib/AOT/runtime/ shared with VM
• Language: include/require in JIT and AOT (multi-file applications) #54 must resolve paths at compile time or runtime before once-table works with Language: Magic constants __DIR__, __FILE__, __LINE__ for multi-file apps #85 __DIR__

Lint

• Once includes with __DIR__ concat benefit from Lint: Constant-fold __DIR__ concatenation for include/require graph in phpc lint --all #462 lint graph folding

Tests

• test/compliance/cases/require_once_idempotent.phpt — counter in included file increments once
• test/compliance/cases/require_once_dir.phpt — uses __DIR__

Acceptance criteria

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  php bin/vm.php -r 'require_once "test/fixtures/once_counter.php"; require_once "test/fixtures/once_counter.php";'

Counter side effect runs once. JIT/AOT parity when #54 closes.

Verification (local / Docker only)

./script/ci-local.sh --filter require_once

Dependencies

• Language: include/require in JIT and AOT (multi-file applications) #54 include JIT/AOT (shared path resolution)
• Language: Magic constants __DIR__, __FILE__, __LINE__ for multi-file apps #85 __DIR__ for relative paths
• AOT: Project build mode (entry file + dependency graph) #59 / AOT: Honor phpc.json includes array in phpc build --project #452 ✅ project includes[] — once table must cover manifest-listed files
• Reference app: examples/003-MiniWebApp (router, templates, forms) #67 MiniWebApp config.php bootstrap

Links

• 🗺️ ROADMAP: Compile a small PHP web application (living document) #78 ROADMAP Phase 1 Language