What References Do

PHP references allow you to make two variables to refer to the same content. Meaning, when you do:

<?php

$a =& $b;
?>

it means that $a and $b point to the same content.

Note:

$a and $b are completely equal here, that's not $a is pointing to $b or vice versa, that's $a and $b pointing to the same place.

Note:

If array with references is copied, its values are not dereferenced. This is valid also for arrays passed by value to functions.

Note:

If you assign, pass or return an undefined variable by reference, it will get created.

Example 12.1. Using references with undefined variables

copy to clipboard

<?php
function foo(&$var) { }

foo($a); // $a is "created" and assigned to null

$b = array();
foo($b['b']);
var_dump(array_key_exists('b', $b)); // bool(true)

$c = new StdClass;
foo($c->d);
var_dump(property_exists($c, 'd')); // bool(true)
?>

The same syntax can be used with functions, that return references, and with new operator (in PHP 4.0.4 and later):

copy to clipboard

<?php

$bar =& new fooclass();
$foo =& find_var($bar);
?>

Since PHP 5, new return reference automatically so using =& in this context is deprecated and produces E_STRICT level message.

Note:

Not using the & operator causes a copy of the object to be made. If you use $this in the class it will operate on the current instance of the class. The assignment without & will copy the instance (i.e. the object) and $this will operate on the copy, which is not always what is desired. Usually you want to have a single instance to work with, due to performance and memory consumption issues.

While you can use the @ operator to mute any errors in the constructor when using it as @new, this does not work when using the &new statement. This is a limitation of the Zend Engine and will therefore result in a parser error.

Warning:

If you assign a reference to a variable declared global inside a function, the reference will be visible only inside the function. You can avoid this by using the $GLOBALS array.

Example 12.2. Referencing global variables inside function

copy to clipboard

<?php

$var1 = "Example variable";
$var2 = "";


function global_references($use_globals)

{

    global $var1, $var2;

    if (!$use_globals) {

        $var2 =& $var1; // visible only inside the function

    } else {

        $GLOBALS["var2"] =& $var1; // visible also in global context

    }

}

global_references(false);

echo "var2 is set to '$var2'\n"; // var2 is set to ''
global_references(true);

echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
?>

Think about global $var; as a shortcut to $var =& $GLOBALS['var'];. Thus assigning other reference to $var only changes the local variable's reference.

Note:

If you assign a value to a variable with references in a foreach statement, the references are modified too.

Example 12.3. References and foreach statement

copy to clipboard

<?php

$ref = 0;
$row =& $ref;

foreach (array(1, 2, 3) as $row) {

    // do something
}

echo $ref; // 3 - last element of the iterated array
?>

The second thing references do is to pass variables by-reference. This is done by making a local variable in a function and a variable in the calling scope reference to the same content. Example:

copy to clipboard

<?php
function foo(&$var)

{

    $var++;

}

$a=5;
foo($a);
?>

will make $a to be 6. This happens because in the function foo the variable $var refers to the same content as $a. See also more detailed explanations about passing by reference.

The third thing reference can do is return by reference.

What References Do

Example 12.1. Using references with undefined variables

Example 12.2. Referencing global variables inside function

Example 12.3. References and foreach statement

Code Examples / Notes » language.references.whatdo

Change Language