Language: Reference assignment and by-ref parameters

[PurHur]

Category

language

Problem (May 2026 refresh)

VM v1 for by-reference semantics is landed — see docs/capabilities-syntax.md:

Construct	VM	JIT	AOT	Tracker
By-ref parameters function f(&$x)	yes	no	no	this issue / #3161
foreach ($a as &$v)	yes	yes	yes	#1222 ✅
Return-by-ref	no	no	no	deferred

This issue tracks remaining reference gaps: JIT/AOT lowering for by-ref parameters, and deferred return-by-ref / global references.

php-src reference

• Zend/zend_compile.c — zend_compile_param() byRef flag, zend_compile_foreach() ref iterator
• Zend/zend_execute.c — ZEND_RECV, ZVAL_MAKE_REF, argument binding by reference
• Zend/zend_operators.c — foreach by-reference iterator state
• Zend/zend_variables.c — return-by-ref (ZEND_RETURN_BY_REF)

Repro — VM baseline (passes today)

<?php
function inc(int &$n): void { $n++; }
$x = 1;
inc($x);
echo $x, "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro.php'
# prints 2

Repro — JIT gap (this issue + #3161)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php repro.php'

Zend / VM: prints 2.
JIT today: does not preserve alias through compiled call (see capabilities-syntax row).

Foreach by-ref (VM/JIT ✅ per #1222):

<?php
$a = [1, 2, 3];
foreach ($a as &$v) { $v *= 2; }
unset($v);
print_r($a);

Scope (this repo)

Area	Files	Notes
Compiler	lib/Compiler.php	Param::byRef → TYPE_INDIRECT (VM ✅)
VM	lib/VM.php, lib/VM/Context.php	Ref slots / alias model (VM ✅)
JIT	lib/JIT.php	LLVM alloca + pointer alias for by-ref params — #3161
AOT	lib/AOT/	Same ABI as JIT
Tests	test/compliance/cases/ref_param.phpt	VM ✅; add @group llvm JIT case
Deferred	return-by-ref, global refs, arbitrary =&	file child issues if needed

Workers: claim #3161 for JIT/AOT lowering; use this issue for VM regressions + return-by-ref when scoped.

Done when

• VM repro remains green (regression guard)
• JIT repro prints 2 for by-ref param without VM fallback (Language: By-reference parameters JIT/AOT lowering (phase 2 post-#140) #3161)
• AOT linked binary preserves ref semantics
• docs/capabilities-syntax.md — by-ref params JIT/AOT = yes
• ./script/ci-fast.sh --filter ref_param green; LLVM filter for JIT

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter ref_param'
make test-harness ARGS='--filter ref_param'   # LLVM hosts

Dependencies

• Language: Implement foreach (CFG → VM → JIT) #53 ✅ foreach base
• Language: foreach by-reference ($k => &$v) #1222 ✅ foreach by-ref
• Language: By-reference parameters JIT/AOT lowering (phase 2 post-#140) #3161 — JIT/AOT phase 2 (primary worker target)

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 1 Language
• North star: Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492