References Explained
PHP Manual

Returning References

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. To return references, use this syntax:

<?php
class foo {
    public 
$value 42;

    public function &
getValue() {
        return 
$this->value;
    }
}

$obj = new foo;
$myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 42.
$obj->value 2;
echo 
$myValue;                // prints the new value of $obj->value, i.e. 2.
?>
In this example, the property of the object returned by the getValue function would be set, not the copy, as it would be without using reference syntax.

Note: Unlike parameter passing, here you have to use & in both places - to indicate that you want to return by reference, not a copy, and to indicate that reference binding, rather than usual assignment, should be done for $myValue.

Note: If you try to return a reference from a function with the syntax: return ($this->value); this will not work as you are attempting to return the result of an expression, and not a variable, by reference. You can only return variables by reference from a function - nothing else. Since PHP 4.4.0 in the PHP 4 branch, and PHP 5.1.0 in the PHP 5 branch, an E_NOTICE error is issued if the code tries to return a dynamic expression or a result of the new operator.

To use the returned reference, you must use reference assigment:

<?php
function &collector() {
  static 
$collection = array();
  return 
$collection;
}
$collection = &collector();
$collection[] = 'foo';
?>
To pass the returned reference to another function expecting a reference you can use this syntax:
<?php
function &collector() {
  static 
$collection = array();
  return 
$collection;
}
array_push(collector(), 'foo');
?>

Note: Note that array_push(&collector(), 'foo'); will not work, it results in a fatal error.


References Explained
PHP Manual

copyright  ©  October 21 2014 sean dreilinger url: http://durak.org/sean/pubs/software/php/language.references.return.html