Retornando referências

Retorno por referência é útil quando é necessário utilizar uma função para localizar variáveis cuja referência precisa ser obtida. Não deve ser usado retorno por referência para aumentar desempenho, o mecanismo é esperto o bastante para otimizar isso. Referências somente devem ser retornadas quando existir uma razão técnica para isso! Para retornar referências, a sintaxe abaixo deve ser usada:

<?php

class Foo
{
    public $value = 42;

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

$obj = new Foo();
$myValue = &$obj->getValue(); // $myValue é uma referência a $obj->value, que é 42
$obj->value = 2;
echo $myValue;                // imprime o valor valor de $obj->value, ou seja, 2

?>

Neste exemplo, a propriedade do objeto retornado pela função getValue precisa ser assimilada, não copiada, como acontecerá se não utilizar a sintaxe de referências.

Note: Diferentemente da passagem de parâmetros por referência, aqui é necessário utilizar & em ambos os lugares - primeiro para indicar o retorno por referência (e não a cópia), e depois para indicar a ligação da referência (em vez da assimilação convencional) que precisa ser explícita para $myValue.

Note: Se houver tentativa de retornar uma referência de uma função com a sintaxe return ($this->value);, isto não funcionará como esperado para retornar o resultado de uma expressão, e não uma variável, por referência. Deve-se retornar variáveis por referência somente para uma função - nada além disso.

Para utilizar a referência retornada, é necessário utilizar a atribuição por referência:

<?php

function &collector()
{
    static $collection = array();
    return $collection;
}

$collection = &collector();
$collection[] = 'foo';

?>

Para passar a referência retornada para outra função que espera uma referência, a seguinte sintaxe pode ser utilizada:

<?php

function &collector()
{
    static $collection = array();
    return $collection;
}

array_push(collector(), 'foo');

?>

Note: Note que array_push(&collector(), 'foo'); não funcionará, e retornará um erro fatal.