Return by reference in PHP

Easy rule: if you place an & in front of a function name in PHP you can use & when you call the function (ie. it's return value) as if it was a variable and not a function.

That's it.

It's easier to think of it as "PHP allowing you to reference the return value" rather then PHP returning by reference. As mentioned above you simply place an & to tell PHP you want this, if you don't place it and try do to $var =& somefunction() you will get the error "Only variables should be assigned by reference."

To clear up some confusion with Jon's answer. There is actually no need to have two separate functions one returning by reference and one returning by value; outside of some project convention. The & only allows it to return by reference, it doesn't force it to return by reference.

eg. same function used both for reference and non-reference assignments

\header('content-type: text/plain');

class Demo
{
    protected $example = 'original value';

    function & example()
    {
        return $this->example;
    }
}

$demo = new Demo;

#1 - pass by value

$var1 = $demo->example();
$var1 = 'var1 value';

echo '$demo->example() => '.$demo->example().PHP_EOL;
echo PHP_EOL;

#2 - pass by reference

$var2 =& $demo->example();
$var2 = 'var2 value';

echo '$demo->example() => '.$demo->example().PHP_EOL;
echo '$var1 => '.$var1.PHP_EOL;
echo '$var2 => '.$var2.PHP_EOL;
echo PHP_EOL;

#3 - altering other references

$var3 =& $demo->example();
$var3 = 'var3 value';

echo '$demo->example() => '.$demo->example().PHP_EOL;
echo '$var1 => '.$var1.PHP_EOL;
echo '$var2 => '.$var2.PHP_EOL;
echo '$var3 => '.$var3.PHP_EOL;
echo PHP_EOL;

exit;

Output

$demo->example() => original value

$demo->example() => var2 value
$var1 => var1 value
$var2 => var2 value

$demo->example() => var3 value
$var1 => var1 value
$var2 => var3 value
$var3 => var3 value

References are great however if you're not familiar with them please follow the following rules:

  • only consider using references if you are dealing with large array or similar non-object data structures
  • never reference an object (if you can avoid it)
  • only allow a function to pass by reference if the value is maintained in a static property or attribute on the object (ie. it's not temporary variable inside the function)

Exceptions would obviously be very utilitarian uses (ie. when you actually want to share a value to simplify code for manipulating it).

Again, NEVER REFERENCE OBJECTS (it's pointless!)


Suppose you have this class:

class Fruit {
    private $color = "red";

    public function getColor() {
        return $this->color;
    }

    public function &getColorByRef() {
        return $this->color;
    }
}

The class has a private property and two methods that let you access it. One returns by value (default behavior) and the other by reference. The difference between the two is that:

  • When using the first method, you can make changes to the returned value and those changes will not be reflected inside the private property of Fruit because you are actually modifying a copy of the property's value.
  • When using the second method, you are in fact getting back an alias for Fruit::$color -- a different name by which you refer to the same variable. So if you do anything with it (including modifying its contents) you are in fact directly performing the same action on the value of the property.

Here's some code to test it:

echo "\nTEST RUN 1:\n\n";
$fruit = new Fruit;
$color = $fruit->getColor();
echo "Fruit's color is $color\n"; 
$color = "green"; // does nothing, but bear with me
$color = $fruit->getColor();
echo "Fruit's color is $color\n"; 

echo "\nTEST RUN 2:\n\n";
$fruit = new Fruit;
$color = &$fruit->getColorByRef(); // also need to put & here
echo "Fruit's color is $color\n"; 
$color = "green"; // now this changes the actual property of $fruit
$color = $fruit->getColor();
echo "Fruit's color is $color\n";

See it in action.

Warning: I feel obliged to mention that references, while they do have legitimate uses, are one of those features that should be used only rarely and only if you have carefully considered any alternatives first. Less experienced programmers tend to overuse references because they see that they can help them solve a particular problem without at the same time seeing the disadvantages of using references (as an advanced feature, its nuances are far from obvious).


The example you posted is probably from PHP4 or earlier. It's no longer necessary to return objects by reference as they are almost always done that way automatically in PHP5+.

Returning by reference is useful when you want to use a function to find to which variable a reference should be bound. Do not use return-by-reference to increase performance. The engine will automatically optimize this on its own. Only return references when you have a valid technical reason to do so.

See return references in PHP docs

Tags:

Php

Return

Reference

Recent Posts