vm: lower by-ref/named/spread calls to dedicated ByExprs opcodes

Previously, function/method calls whose argument shape required
the full ctx.Call binding pipeline (by-ref params, named args,
spread) were lowered to OP_CLASS_CONST / OP_TRY_FINALLY — generic
AST.Run() delegation that ran the entire runnableFunctionCall /
runObjectFunc / runnableFunctionCallRef node as one opaque step.

Replace that with three dedicated opcodes that hand the raw
argument-expression list to ctx.Call:

  - OP_CALL_USER_BY_EXPRS:    foo($a, $b, ...)
  - OP_OBJECT_CALL_BY_EXPRS:  $obj->method($a, $b, ...)
  - OP_CALL_INDIRECT_BY_EXPRS: $f($a, $b, ...)

The arg expressions live in a new Function.SubArgs slice (parallel
to SubASTs / SubFns) so the opcode only carries the SubArgs index.
At runtime, each handler resolves its callable (same CallableCache
hookup as OP_CALL_USER, same ResolveCallable as OP_CALL_INDIRECT,
same method-lookup as OP_OBJECT_CALL) then calls ctx.Call(...,
exprs, ...), which evaluates each expression with by-ref binding,
named-arg reordering, and spread expansion — the path the AST
runner's runnableFunctionCall.Run already takes.

For OP_OBJECT_CALL_BY_EXPRS, extract a sibling helper
CallInstanceMethodByExprs in core/compiler/dispatch.go that
mirrors CallInstanceMethod byte-for-byte; only the terminal call
switches from ctx.CallZVal to ctx.Call so by-ref params bind
correctly. The __call magic-method fallback still uses ZVal args
(the magic array needs them), so the helper evaluates exprs
up-front for that branch only.

emit_call.go's emitFunctionCall and emitFunctionCallRef, and
emit_object.go's emitObjectFuncCall, now route the
by-ref/special-args/writable-arg cases through these opcodes
instead of emitCallViaAST. Stmt-context drops the result with
OP_POP; OP_REFRESH_SLOTS follows each call so subsequent slot-
cache reads see any caller-local mutations from a by-ref param.

Smoke tests pass: sort/array_pop/preg_match by-ref builtins,
user-function by-ref params, closure by-ref params, instance
method by-ref params, mixed named+positional+spread args,
array_walk by-ref callback, __call fallback, nullsafe with
spread args.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: MagicalTux

core/compiler/dispatch.go

@@ -614,6 +614,153 @@ func CallInstanceMethod(ctx phpv.Context, obj *phpv.ZVal, name phpv.ZString, arg
 	return ctx.CallZVal(ctx, method.Method, args, objBound)
 }
 
+// CallInstanceMethodByExprs is the by-AST-expression variant of
+// CallInstanceMethod. Used by OP_OBJECT_CALL_BY_EXPRS for method calls
+// whose argument shape needs the full ctx.Call binding pipeline
+// (by-ref parameters, named arguments, spread). The dispatch logic
+// mirrors CallInstanceMethod byte-for-byte; only the terminal call
+// switches from ctx.CallZVal to ctx.Call so the binding layer sees the
+// raw argument expressions.
+//
+// The __call magic-method fallback still needs ZVal args (it builds
+// a magic array), so this evaluates exprs up-front for that branch
+// only — by-ref binding doesn't apply through __call anyway, since
+// the user wrote `__call($name, $args)` with the args array.
+func CallInstanceMethodByExprs(ctx phpv.Context, obj *phpv.ZVal, name phpv.ZString, exprs []phpv.Runnable) (*phpv.ZVal, error) {
+	zobj, ok := obj.Value().(*phpobj.ZObject)
+	if !ok {
+		if zo, ok := obj.Value().(phpv.ZObject); ok {
+			m, mok := zo.GetClass().GetMethod(name)
+			if !mok {
+				return nil, phpobj.ThrowError(ctx, phpobj.Error,
+					fmt.Sprintf("Call to undefined method %s::%s()", zo.GetClass().GetName(), name))
+			}
+			return ctx.Call(ctx, m.Method, exprs, zo)
+		}
+		return nil, fmt.Errorf("CallInstanceMethodByExprs: receiver is not a ZObject")
+	}
+
+	class := zobj.GetClass()
+	method, ok := class.GetMethod(name)
+	if !ok {
+		if cm, hasCall := class.GetMethod("__call"); hasCall {
+			args, err := evalExprArgs(ctx, exprs)
+			if err != nil {
+				return nil, err
+			}
+			a := phpv.NewZArray()
+			for _, sub := range args {
+				a.OffsetSet(ctx, nil, sub.Dup())
+			}
+			return ctx.CallZVal(ctx, cm.Method, []*phpv.ZVal{name.ZVal(), a.ZVal()}, zobj)
+		}
+		return nil, phpobj.ThrowError(ctx, phpobj.Error,
+			fmt.Sprintf("Call to undefined method %s::%s()", class.GetName(), name))
+	}
+
+	if method.Modifiers.Has(phpv.ZAttrAbstract) || (method.Empty && method.Class != nil && method.Class.GetType() != phpv.ZClassTypeInterface) {
+		return nil, phpobj.ThrowError(ctx, phpobj.Error,
+			fmt.Sprintf("Cannot call abstract method %s::%s()", method.Class.GetName(), method.Name))
+	}
+
+	methodNotVisible := false
+	var visErrMsg string
+	if method.Modifiers.Has(phpv.ZAttrPrivate) {
+		callerClass := ctx.Class()
+		methodClass := method.Class
+		if callerClass == nil || methodClass == nil || callerClass.GetName() != methodClass.GetName() {
+			methodClassName := class.GetName()
+			if methodClass != nil {
+				methodClassName = methodClass.GetName()
+			}
+			scope := "global scope"
+			if callerClass != nil {
+				scope = "scope " + string(callerClass.GetName())
+			}
+			methodNotVisible = true
+			visErrMsg = fmt.Sprintf("Call to private method %s::%s() from %s", methodClassName, method.Name, scope)
+		}
+	} else if method.Modifiers.Has(phpv.ZAttrProtected) {
+		callerClass := ctx.Class()
+		if callerClass == nil {
+			methodNotVisible = true
+			visErrMsg = fmt.Sprintf("Call to protected method %s::%s() from global scope", class.GetName(), method.Name)
+		} else if !callerClass.InstanceOf(method.Class) && !method.Class.InstanceOf(callerClass) && !callerClass.InstanceOf(class) && !class.InstanceOf(callerClass) {
+			protectedVisible := false
+			if method.Class != nil {
+				rootClass := method.Class
+				for rootClass.GetParent() != nil {
+					if pm, ok := rootClass.GetParent().GetMethod(method.Name); ok && pm.Modifiers.Has(phpv.ZAttrProtected) {
+						rootClass = rootClass.GetParent()
+					} else {
+						break
+					}
+				}
+				if callerClass.InstanceOf(rootClass) {
+					protectedVisible = true
+				}
+			}
+			if !protectedVisible {
+				methodNotVisible = true
+				visErrMsg = fmt.Sprintf("Call to protected method %s::%s() from scope %s", class.GetName(), method.Name, callerClass.GetName())
+			}
+		}
+	}
+	if methodNotVisible {
+		if cm, hasCall := class.GetMethod("__call"); hasCall {
+			args, err := evalExprArgs(ctx, exprs)
+			if err != nil {
+				return nil, err
+			}
+			a := phpv.NewZArray()
+			for _, sub := range args {
+				a.OffsetSet(ctx, nil, sub.Dup())
+			}
+			return ctx.CallZVal(ctx, cm.Method, []*phpv.ZVal{name.ZVal(), a.ZVal()}, zobj)
+		}
+		return nil, phpobj.ThrowError(ctx, phpobj.Error, visErrMsg)
+	}
+
+	if method.Modifiers.IsStatic() {
+		m := phpv.BindClassLSB(method.Method, class, class, true)
+		m.Attributes = method.Attributes
+		return ctx.Call(ctx, m, exprs, nil)
+	}
+
+	var objBound phpv.ZObject = zobj
+	if method.Class != nil {
+		if kin := zobj.GetKin(string(method.Class.GetName())); kin != nil {
+			objBound = kin
+		}
+	}
+	if len(method.Attributes) > 0 {
+		wrapped := &phpv.MethodCallable{
+			Callable:   method.Method,
+			Class:      class,
+			Attributes: method.Attributes,
+			AliasName:  string(method.Name),
+		}
+		return ctx.Call(ctx, wrapped, exprs, objBound)
+	}
+	return ctx.Call(ctx, method.Method, exprs, objBound)
+}
+
+// evalExprArgs evaluates each AST argument expression to a ZVal,
+// stopping at the first error. Used only by the __call magic-method
+// fallback paths in CallInstanceMethodByExprs, which need ZVal args
+// to build the magic array.
+func evalExprArgs(ctx phpv.Context, exprs []phpv.Runnable) ([]*phpv.ZVal, error) {
+	out := make([]*phpv.ZVal, 0, len(exprs))
+	for _, e := range exprs {
+		v, err := e.Run(ctx)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, v)
+	}
+	return out, nil
+}
+
 // EvalBinop computes the result of a binary operator with full PHP
 // semantics. The VM uses this so its arithmetic / bitwise / compare /
 // concat opcodes match the AST runOperator path byte-for-byte.

core/vm/function.go

@@ -24,6 +24,13 @@ type Function struct {
 	SubFns      []*Function     // direct-call targets (resolved at emit time)
 	SubClosures []phpv.Runnable // *ZClosure templates referenced by OP_MAKE_CLOSURE
 	SubASTs     []phpv.Runnable // delegated AST nodes (class const, static, …)
+	// SubArgs holds per-call-site argument expression lists for the
+	// "ByExprs" call opcodes (OP_CALL_USER_BY_EXPRS, OP_CALL_INDIRECT_BY_EXPRS,
+	// OP_OBJECT_CALL_BY_EXPRS). The runtime passes args[idx] to ctx.Call,
+	// which evaluates each expression in caller scope with full by-ref /
+	// named / spread support — the path the AST runner's
+	// runnableFunctionCall.Run takes. Indexed by the opcode's B field.
+	SubArgs [][]phpv.Runnable
 	LocsSparse  []LocEntry      // sorted by PC
 	TryHandlers []TryHandler
 	NumParams   int

core/vm/opcode.go

@@ -412,6 +412,30 @@ const (
 	// while delegating only the per-iteration write.
 	OpAssignWritable
 
+	// OP_CALL_USER_BY_EXPRS is the by-ref / named / spread variant of
+	// OP_CALL_USER. A = const-pool ZString function name (with the same
+	// CallableCache hookup OP_CALL_USER uses); B = SubArgs index of the
+	// arg-expression list. The handler resolves the callable then calls
+	// ctx.Call(ctx, callable, exprs, nil), which evaluates each arg
+	// expression with by-ref binding, named-arg reordering, and spread
+	// expansion. Pushes the result on top of the stack. No args are
+	// pushed beforehand — the expressions live in fn.SubArgs.
+	OpCallUserByExprs
+
+	// OP_CALL_INDIRECT_BY_EXPRS is the by-ref / named / spread variant
+	// of OP_CALL_INDIRECT. A = SubArgs index of the arg-expression list.
+	// The callable is at the top of the stack (already emitted as a
+	// native expression); the handler pops it, resolves it via
+	// ResolveCallable, then calls ctx.Call. Pushes the result.
+	OpCallIndirectByExprs
+
+	// OP_OBJECT_CALL_BY_EXPRS is the by-ref / named / spread variant of
+	// instance method calls. A = const-pool ZString method name; B =
+	// SubArgs index of the arg-expression list. The receiver is at the
+	// top of the stack; the handler pops it, resolves the method, then
+	// calls ctx.Call with the receiver as $this. Pushes the result.
+	OpObjectCallByExprs
+
 	// Sentinel — keep last.
 	opLast
 )
@@ -541,4 +565,7 @@ var opNames = [...]string{
 	OpFinallyEnd:          "FINALLY_END",
 	OpForeachStepPush:     "FOREACH_STEP_PUSH",
 	OpAssignWritable:      "ASSIGN_WRITABLE",
+	OpCallUserByExprs:     "CALL_USER_BY_EXPRS",
+	OpCallIndirectByExprs: "CALL_INDIRECT_BY_EXPRS",
+	OpObjectCallByExprs:   "OBJECT_CALL_BY_EXPRS",
 }

core/vm/vm.go

@@ -709,6 +709,76 @@ func (f *Frame) runUntilError(ctx phpv.Context) (retVal *phpv.ZVal, finished boo
 			}
 			f.push(res)
 
+		case OpCallUserByExprs:
+			// By-ref / named / spread variant. A = const-pool name idx,
+			// B = SubArgs index of the argument-expression list. The
+			// callable is resolved at runtime (with CallableCache reuse)
+			// then handed to ctx.Call which evaluates each expression
+			// with full binding semantics.
+			name, ok := f.fn.Consts[ins.A()].(phpv.ZString)
+			if !ok {
+				return nil, false, fmt.Errorf("vm: OP_CALL_USER_BY_EXPRS name const is %T not ZString", f.fn.Consts[ins.A()])
+			}
+			nameIdx := ins.A()
+			var callable phpv.Callable
+			if int(nameIdx) < len(f.fn.CallableCache) {
+				callable = f.fn.CallableCache[nameIdx]
+			}
+			if callable == nil {
+				c, err := ctx.Global().GetFunction(ctx, name)
+				if err != nil {
+					return nil, false, err
+				}
+				callable = c
+				if f.fn.CallableCache == nil {
+					f.fn.CallableCache = make([]phpv.Callable, len(f.fn.Consts))
+				}
+				if int(nameIdx) < len(f.fn.CallableCache) {
+					f.fn.CallableCache[nameIdx] = callable
+				}
+			}
+			argsIdx := int(ins.B())
+			if argsIdx >= len(f.fn.SubArgs) {
+				return nil, false, fmt.Errorf("vm: OP_CALL_USER_BY_EXPRS SubArgs index %d out of range", argsIdx)
+			}
+			res, err := ctx.Call(ctx, callable, f.fn.SubArgs[argsIdx], nil)
+			if err != nil {
+				return nil, false, err
+			}
+			if res == nil {
+				res = phpv.ZNULL.ZVal()
+			}
+			f.push(res)
+
+		case OpCallIndirectByExprs:
+			// A = SubArgs index. Callable expression already on top of
+			// stack. Pop it, resolve via ResolveCallable, then dispatch
+			// via ctx.Call so by-ref / named / spread args bind through
+			// the standard call-binding pipeline.
+			callable := f.pop()
+			c, this, err := compiler.ResolveCallable(ctx, callable)
+			if err != nil {
+				return nil, false, err
+			}
+			argsIdx := int(ins.A())
+			if argsIdx >= len(f.fn.SubArgs) {
+				return nil, false, fmt.Errorf("vm: OP_CALL_INDIRECT_BY_EXPRS SubArgs index %d out of range", argsIdx)
+			}
+			exprs := f.fn.SubArgs[argsIdx]
+			var res *phpv.ZVal
+			if this != nil {
+				res, err = ctx.Call(ctx, c, exprs, this)
+			} else {
+				res, err = ctx.Call(ctx, c, exprs, nil)
+			}
+			if err != nil {
+				return nil, false, err
+			}
+			if res == nil {
+				res = phpv.ZNULL.ZVal()
+			}
+			f.push(res)
+
 		// --- return --------------------------------------------------
 		case OpRet:
 			v := f.pop()
@@ -969,6 +1039,44 @@ func (f *Frame) runUntilError(ctx phpv.Context) (retVal *phpv.ZVal, finished boo
 			}
 			f.push(res)
 
+		case OpObjectCallByExprs:
+			// By-ref / named / spread variant. A = const-pool method
+			// name idx, B = SubArgs index, C != 0 marks nullsafe. The
+			// receiver is on top of stack; the call dispatch goes
+			// through CallInstanceMethodByExprs which mirrors
+			// CallInstanceMethod but uses ctx.Call so by-ref params
+			// bind correctly.
+			receiver := f.pop()
+			if ins.C() != 0 && (receiver == nil || phpv.IsNull(receiver)) {
+				f.push(phpv.ZNULL.ZVal())
+				break
+			}
+			if receiver == nil || receiver.GetType() != phpv.ZtObject {
+				typeName := "null"
+				if receiver != nil {
+					typeName = receiver.GetType().TypeName()
+				}
+				name, _ := f.fn.Consts[ins.A()].(phpv.ZString)
+				return nil, false, phpobj.ThrowError(ctx, phpobj.Error,
+					fmt.Sprintf("Call to a member function %s() on %s", string(name), typeName))
+			}
+			name, ok := f.fn.Consts[ins.A()].(phpv.ZString)
+			if !ok {
+				return nil, false, fmt.Errorf("vm: OP_OBJECT_CALL_BY_EXPRS name const is %T not ZString", f.fn.Consts[ins.A()])
+			}
+			argsIdx := int(ins.B())
+			if argsIdx >= len(f.fn.SubArgs) {
+				return nil, false, fmt.Errorf("vm: OP_OBJECT_CALL_BY_EXPRS SubArgs index %d out of range", argsIdx)
+			}
+			res, err := compiler.CallInstanceMethodByExprs(ctx, receiver, name, f.fn.SubArgs[argsIdx])
+			if err != nil {
+				return nil, false, err
+			}
+			if res == nil {
+				res = phpv.ZNULL.ZVal()
+			}
+			f.push(res)
+
 		// --- foreach -------------------------------------------------
 		case OpForeachInit:
 			src := f.pop()

core/vm/vmcompiler/emit.go

@@ -19,6 +19,7 @@ type emitter struct {
 	subFns      []*vm.Function
 	subClosures []phpv.Runnable
 	subASTs     []phpv.Runnable
+	subArgs     [][]phpv.Runnable
 	tryHandlers []vm.TryHandler
 
 	locs []vm.LocEntry
@@ -131,6 +132,17 @@ func (e *emitter) astIndex(r phpv.Runnable) uint16 {
 	return idx
 }
 
+// subArgsIndex registers a call-site argument expression list in the
+// SubArgs table. Used by the "ByExprs" call opcodes which hand the raw
+// AST argument expressions to ctx.Call so the binding layer can apply
+// by-ref / named / spread semantics. No dedup — each call site gets
+// its own slot.
+func (e *emitter) subArgsIndex(args []phpv.Runnable) uint16 {
+	idx := uint16(len(e.subArgs))
+	e.subArgs = append(e.subArgs, args)
+	return idx
+}
+
 // localIndex returns the local-table index for the named variable,
 // adding it on first use.
 func (e *emitter) localIndex(name phpv.ZString) uint16 {
@@ -194,6 +206,7 @@ func (e *emitter) finish(name phpv.ZString, numParams int) *vm.Function {
 		SubFns:      e.subFns,
 		SubClosures: e.subClosures,
 		SubASTs:     e.subASTs,
+		SubArgs:     e.subArgs,
 		LocsSparse:  e.locs,
 		TryHandlers: e.tryHandlers,
 		NumParams:   numParams,