Implement explicit send-by-ref

Currently, in order to pass an argument by reference, the reference
has to be declared at the definition-site, but not at the call-site:

    function byRef(&$ref) {}
    byRef($var);

This change adds the ability to specify the by reference pass at
*both* the definition-site and the call-site:

    function byRef(&$ref) {}
    byRef(&$var);

Importantly, specifying a reference during the call will generate
an error if the argument is not also declared by-reference at the
declaration site:

    function byVal($val) {}
    byVal(&$val); // ERROR

This makes it different from the call-time-pass-by-reference
feature in PHP 4. If this feature is used, the reference has to
be declared at both the call- *and* declaration-site.

Note that it is still possible to not explicitly specify the use
of by-reference passing at the call-site. As such, the following
code remain legal:

    function byRef(&$ref) {}
    byRef($var);

Author: nikic

Zend/Optimizer/optimize_func_calls.c

@@ -340,6 +340,24 @@ void zend_optimize_func_calls(zend_op_array *op_array, zend_optimizer_ctx *ctx)
 					break;
 				}
 				break;
+			case ZEND_SEND_EXPLICIT_REF:
+				if (call_stack[call - 1].func) {
+					if (ARG_SHOULD_BE_SENT_BY_REF(call_stack[call - 1].func, opline->op2.num)) {
+						opline->opcode = ZEND_SEND_REF;
+					}
+				}
+				break;
+			case ZEND_SEND_EXPLICIT_VAL:
+				if (call_stack[call - 1].func) {
+					if (!ARG_MUST_BE_SENT_BY_REF(call_stack[call - 1].func, opline->op2.num)) {
+						if (opline->op1_type & (IS_CONST|IS_TMP_VAR)) {
+							opline->opcode = ZEND_SEND_VAL;
+						} else {
+							opline->opcode = ZEND_SEND_VAR;
+						}
+					}
+				}
+				break;
 			case ZEND_SEND_UNPACK:
 			case ZEND_SEND_USER:
 			case ZEND_SEND_ARRAY:

Zend/Optimizer/sccp.c

@@ -238,6 +238,8 @@ static bool can_replace_op1(
 		case ZEND_UNSET_DIM:
 		case ZEND_UNSET_OBJ:
 		case ZEND_SEND_REF:
+		case ZEND_SEND_EXPLICIT_REF:
+		case ZEND_SEND_EXPLICIT_REF_FUNC:
 		case ZEND_SEND_VAR_EX:
 		case ZEND_SEND_FUNC_ARG:
 		case ZEND_SEND_UNPACK:

Zend/Optimizer/zend_call_graph.c

@@ -139,6 +139,9 @@ ZEND_API void zend_analyze_calls(zend_arena **arena, zend_script *script, uint32
 			case ZEND_SEND_VAR_EX:
 			case ZEND_SEND_FUNC_ARG:
 			case ZEND_SEND_REF:
+			case ZEND_SEND_EXPLICIT_VAL:
+			case ZEND_SEND_EXPLICIT_REF:
+			case ZEND_SEND_EXPLICIT_REF_FUNC:
 			case ZEND_SEND_VAR_NO_REF:
 			case ZEND_SEND_VAR_NO_REF_EX:
 			case ZEND_SEND_USER:

Zend/Optimizer/zend_dfg.c

@@ -154,6 +154,7 @@ static zend_always_inline void _zend_dfg_add_use_def_op(const zend_op_array *op_
 		case ZEND_BIND_INIT_STATIC_OR_JMP:
 		case ZEND_SEND_VAR_NO_REF:
 		case ZEND_SEND_VAR_NO_REF_EX:
+		case ZEND_SEND_EXPLICIT_REF:
 		case ZEND_SEND_VAR_EX:
 		case ZEND_SEND_FUNC_ARG:
 		case ZEND_SEND_REF:

Zend/Optimizer/zend_inference.c

@@ -3268,6 +3268,7 @@ static zend_always_inline zend_result _zend_update_type_info(
 			}
 			break;
 		case ZEND_SEND_REF:
+		case ZEND_SEND_EXPLICIT_REF:
 			if (ssa_op->op1_def >= 0) {
 				tmp = MAY_BE_REF|MAY_BE_RC1|MAY_BE_RCN|MAY_BE_ANY|MAY_BE_ARRAY_KEY_ANY|MAY_BE_ARRAY_OF_ANY|MAY_BE_ARRAY_OF_REF;
 				UPDATE_SSA_TYPE(tmp, ssa_op->op1_def);
@@ -3658,6 +3659,7 @@ static zend_always_inline zend_result _zend_update_type_info(
 							case ZEND_SEND_VAR_NO_REF:
 							case ZEND_SEND_VAR_NO_REF_EX:
 							case ZEND_SEND_REF:
+							case ZEND_SEND_EXPLICIT_REF:
 							case ZEND_ASSIGN_REF:
 							case ZEND_YIELD:
 							case ZEND_INIT_ARRAY:
@@ -4930,6 +4932,7 @@ ZEND_API bool zend_may_throw_ex(const zend_op *opline, const zend_ssa_op *ssa_op
 				case ZEND_FETCH_DIM_IS:
 				case ZEND_FETCH_OBJ_IS:
 				case ZEND_SEND_REF:
+				case ZEND_SEND_EXPLICIT_REF:
 				case ZEND_UNSET_CV:
 				case ZEND_ISSET_ISEMPTY_CV:
 				case ZEND_MAKE_REF:
@@ -4958,6 +4961,7 @@ ZEND_API bool zend_may_throw_ex(const zend_op *opline, const zend_ssa_op *ssa_op
 				case ZEND_SEND_VAR_NO_REF:
 				case ZEND_SEND_VAR_NO_REF_EX:
 				case ZEND_SEND_REF:
+				case ZEND_SEND_EXPLICIT_REF:
 				case ZEND_SEPARATE:
 				case ZEND_END_SILENCE:
 				case ZEND_MAKE_REF:

Zend/Optimizer/zend_ssa.c

@@ -685,6 +685,7 @@ static zend_always_inline int _zend_ssa_rename_op(const zend_op_array *op_array,
 		case ZEND_SEND_VAR_EX:
 		case ZEND_SEND_FUNC_ARG:
 		case ZEND_SEND_REF:
+		case ZEND_SEND_EXPLICIT_REF:
 		case ZEND_SEND_UNPACK:
 		case ZEND_FE_RESET_RW:
 		case ZEND_MAKE_REF:

Zend/tests/explicitSendByRef/__call.phpt

@@ -0,0 +1,35 @@
+--TEST--
+__call() magic with explicit pass by ref
+--FILE--
+<?php
+
+class Incrementor {
+    public function inc(&$i) {
+        $i++;
+    }
+}
+
+class ForwardCalls {
+    private $object;
+    public function __construct($object) {
+        $this->object = $object;
+    }
+    public function __call(string $method, array $args) {
+        return $this->object->$method(...$args);
+    }
+}
+
+$forward = new ForwardCalls(new Incrementor);
+
+$i = 0;
+$forward->inc(&$i);
+var_dump($i);
+
+$i = 0;
+$forward->inc($i);
+var_dump($i);
+
+?>
+--EXPECT--
+int(1)
+int(0)

Zend/tests/explicitSendByRef/basic.phpt

@@ -0,0 +1,75 @@
+--TEST--
+Basic tests for explicit pass-by-ref
+--FILE--
+<?php
+
+// Works (by-ref arg)
+$a = 42;
+incArgRef(&$a);
+var_dump($a);
+
+// Works (by-ref arg, deep reference)
+writeArgRef(&$b[0][1]);
+var_dump($b);
+
+// Works (prefer-ref arg)
+$c = 42;
+$vars = ['d' => &$c];
+extract(&$vars, EXTR_REFS);
+$d++;
+var_dump($c);
+
+// Works (by-ref arg, by-ref function)
+$e = 42;
+incArgRef(&returnsRef($e));
+var_dump($e);
+
+// Fails (by-val arg)
+try {
+    $f = 1;
+    var_dump(incArgVal(&$f));
+} catch (Error $e) {
+    echo $e->getMessage(), "\n";
+}
+
+// Fails (by-ref arg, by-val function)
+try {
+    $g = 42;
+    incArgRef(&returnsVal($g));
+    var_dump($g);
+} catch (Error $e) {
+    echo $e->getMessage(), "\n";
+}
+
+// Fails (by-val arg, by-ref function)
+try {
+    $h = 1;
+    var_dump(incArgVal(&returnsRef($h)));
+} catch (Error $e) {
+    echo $e->getMessage(), "\n";
+}
+
+// Functions intentionally declared at the end of the file,
+// to avoid the fbc being known during compilation
+function incArgVal($a) { return $a + 1; }
+function incArgRef(&$a) { $a++; }
+function writeArgRef(&$a) { $a = 43; }
+
+function returnsVal($a) { return $a; }
+function &returnsRef(&$a) { return $a; }
+
+?>
+--EXPECT--
+int(43)
+array(1) {
+  [0]=>
+  array(1) {
+    [1]=>
+    int(43)
+  }
+}
+int(43)
+int(43)
+Cannot pass reference to by-value parameter 1
+Cannot pass result of by-value function by reference
+Cannot pass reference to by-value parameter 1

Zend/tests/explicitSendByRef/call_user_func.phpt

@@ -0,0 +1,35 @@
+--TEST--
+call_user_func() with explicit pass by ref
+--FILE--
+<?php
+
+// Avoid VM builtin.
+namespace Foo;
+
+function inc(&$i) { $i++; }
+
+$i = 0;
+call_user_func('Foo\inc', $i);
+var_dump($i);
+
+$i = 0;
+call_user_func('Foo\inc', &$i);
+var_dump($i);
+
+$i = 0;
+\call_user_func('Foo\inc', $i);
+var_dump($i);
+
+$i = 0;
+\call_user_func('Foo\inc', &$i);
+var_dump($i);
+
+?>
+--EXPECTF--
+Warning: Foo\inc(): Argument #1 ($i) must be passed by reference, value given in %s on line %d
+int(0)
+int(1)
+
+Warning: Foo\inc(): Argument #1 ($i) must be passed by reference, value given in %s on line %d
+int(0)
+int(1)

Zend/tests/explicitSendByRef/compileError.phpt

@@ -0,0 +1,11 @@
+--TEST--
+A compilation error is thrown is the ref/val mismatch is detected at compile-time
+--FILE--
+<?php
+
+function argByVal($a) {}
+argByVal(&$b);
+
+?>
+--EXPECTF--
+Fatal error: Cannot pass reference to by-value parameter 1 in %s on line %d