Language: __halt_compiler() — stop parsing and preserve trailing bytes (Zend zend_compile.c parity)

[PurHur]

Category

language / compiler

Problem

PHP supports __halt_compiler() to terminate compilation and leave trailing bytes in the source file (used by PHAR stubs and some codegen tools). php-parser already parses Stmt\HaltCompiler, but this compiler has no lowering — function_exists('__halt_compiler') is false and scripts using the construct fail at compile time.

Verified May 2026: trailing bytes after halt are parsed as PHP, causing syntax errors on garbage data.

php-src reference

• php/php-src Zend/zend_compile.c — zend_compile_halt_compiler()
• php/php-src Zend/zend_language_scanner.l — T_HALT_COMPILER
• php/php-src ext/phar/phar.c — PHAR stub generation relies on halt compiler semantics

Repro (failure today)

<?php
echo "before\n";
__halt_compiler();
?>
TRAILING_BYTES_SHOULD_NOT_BE_PARSED

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro.php'
# parse/compile error on trailing bytes OR unknown statement (wrong)

php repro.php
# before
# (trailing bytes ignored)

Runtime	Expected
Zend	Compiles; runs echo "before"; ignores trailing bytes
This compiler	Fails to compile or parses trailing garbage

Scope (this repo)

• vendor/ircmaxell/php-cfg / patches — lower Stmt\HaltCompiler to compile-stop marker
• lib/Compiler.php — ignore/reject statements after halt; optionally store remaining bytes
• ext/standard/ — register __halt_compiler() builtin (runtime call may fatal per Zend)
• JIT/AOT: compile-time only — self-host inventory unlikely to hit this in lib/

Done when

• Repro prints before under php bin/vm.php; no parse error on trailing TRAILING_BYTES…
• function_exists('__halt_compiler') returns true
• Direct runtime call __halt_compiler() behavior matches Zend (compile error or fatal as appropriate)
• Compliance PHPT: test/compliance/cases/language/halt_compiler.phpt
• Optional: expose remaining bytes for PHAR tooling (Stdlib: ext/phar — Phar archive API (ext/phar parity) #3436) — not required for initial claim

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php vendor/bin/phpunit --filter halt_compiler'

[PurHur]

claim: worker-lane-c — starting this run

[PurHur]

claim: runforge-worker-lane-c — continuing PR #3489 (rebase + verification this run)

[PurHur]

Update (runforge-worker-lane-c): Rebased PR #3489 onto master, resolved merge conflicts, fixed apply-patches throw-expr overlay duplicate.

Verification (green):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./script/apply-patches.sh >/dev/null && vendor/bin/phpunit test/unit/HaltCompilerVMTest.php test/compliance/VMTest.php --filter halt_compiler'
# OK (2 tests)

php-src: Zend/zend_compile.c — zend_compile_halt_compiler(), T_HALT_COMPILER scanner stop.

[PurHur]

Spec expansion (parity backlog architect — 2026-06-04)

Status probe

__halt_compiler() works on current master (trailing bytes ignored). Remaining gap is the magic constant __COMPILER_HALT_OFFSET__ — tracked in #5455 (phase 2 of this issue).

Repro — halt OK, offset missing

<?php
echo __COMPILER_HALT_OFFSET__, "\n";
__halt_compiler();
TRAILING

Engine	Result
Zend PHP 8.3+	prints int(89) (offset varies by file)
This compiler VM (2026-06-04)	Error: Undefined constant "__COMPILER_HALT_OFFSET__"

./script/docker-exec.sh bash -lc 'php bin/vm.php repro.php'  # fatal on constant
./script/docker-exec.sh bash -lc 'php repro.php'             # int offset

Updated done when

• __halt_compiler() stops parse / ignores trailing bytes
• __COMPILER_HALT_OFFSET__ — see Language: __COMPILER_HALT_OFFSET__ magic constant (phase 2 of #3479, zend_compile.c) #5455
• PHAR stub scripts using both constructs pass compliance PHPT

Worker picking this issue: close halt body here; claim #5455 for the constant.