Retornando referências

Retorno por referência é útil quando você precisa utilizar uma função para localizar variável cuja referência precisa ser obtida. Não use retorno por referência para aumentar performance, a engine é esperta o bastante para otimizar isto para você. Somente retorne referências quando você tem uma razão técnica para isso! Para retornar referências, use a sintaxe:


<?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 precissa ser assimilada, não copiada, como acontecerá se não utilizar a sintaxe de referências.

Nota: Diferentemente da passagem de parâmetros por referência, aqui você precisa 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.

Nota: Se você tentar retornar uma referência de uma função com a sintaxe: return ($this->value); isto não irá funcionar como você espera, para retornar o resultado de uma expressão, e não uma variável, por referência. Você pode somente retornar variáveis por referência para uma função - nada além. Erro E_NOTICE é emitido desde o PHP 4.4.0 e PHP 5.1.0 se o código tenta retornar uma expressão dinâmica ou um resultado do operador new.

Para utilizar a referência retornada, você precisa 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 qual espera uma referência você pode utilizar a seguinte sintaxe:


<?php
function &collector() {
  static $collection = array();
  return $collection;
}
array_push(collector(), 'foo');
?>

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