PHP Reference ยท Functions and Classes
Passing by reference in PHP
Reference for PHP reference parameters: the &$param syntax, modifying caller variables, returning references, objects versus references and the foreach trap.
By default PHP passes arguments by value: the function gets its own copy, and changes inside do not affect the caller. Put an ampersand before a parameter (&$param) and the function instead works on the caller's variable itself, so assignments inside are visible outside.
Reference parameters are used for functions that need to return more than one result or modify large data in place, such as sort(), preg_match() (its $matches) and array_push().
function addOne(int &$n): void { $n++; } $x = 5; addOne($x); echo $x; // 6
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
function name(Type &$param, Type &...$many) function &name() // returns a reference $ref = &$variable; // reference assignment
| Part | Description |
|---|---|
&$param |
The parameter is an alias for the argument variable. |
| Default values | Allowed: array &$out = [] or ?array &$out = null uses a fresh local when omitted. |
function &name() |
The function returns a reference; the caller must use =& to keep it. Rare. |
Errors: passing something that is not a variable (a literal, a function result, a constant) throws Error ("could not be passed by reference") for user functions, or a notice for functions returning a value.
Usage notes
- Objects are not the reason to use
&. An object variable holds a handle; passing it by value already lets the function change the object's properties. Use&only when the function must replace the variable itself. - Arrays are copy-on-write. Passing a big array by value is cheap until it is modified. Do not add
&for performance; measure first. - Caller side must be a variable.
swap('literal', $y)fails because a literal has no storage to alias. - Undefined variables are created.
parse('a', $newVar)creates$newVarasnulland then assigns it. This makes output parameters work. - The
foreachtrap. Afterforeach ($a as &$v)the variable$vstill references the last element. Reusing$vlater overwrites it. Alwaysunset($v)right after the loop. - Prefer return values. Returning an array or object is clearer than output parameters; use references for legacy-style APIs or in-place algorithms.
- No
&at the call. Call-time pass-by-reference (f(&$x)) was removed in PHP 5.4; only the declaration carries the&. - Closures:
use (&$var)captures by reference. See Anonymous functions. - Reference semantics in arrays can persist silently: copying an array that contains a reference slot shares that slot.