引用的解释
在线手册:中文 英文
PHP手册

引用返回

引用返回用在当想用函数找到引用应该被绑定在哪一个变量上面时。不要用返回引用来增加性能,引擎足够聪明来自己进行优化。仅在有合理的技术原因时才返回引用!要返回引用,使用此语法:

<?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.
?>
本例中 getValue 函数所返回的对象的属性将被赋值,而不是拷贝,就和没有用引用语法一样。

Note: 和参数传递不同,这里必须在两个地方都用 & 符号——指出返回的是一个引用,而不是通常的一个拷贝,同样也指出 $myValue 是作为引用的绑定,而不是通常的赋值。

Note: 如果试图这样从函数返回引用:return ($this->value);,这将不会起作用,因为在试图返回一个表达式的结果而不是一个引用的变量。只能从函数返回引用变量——没别的方法。如果代码试图返回一个动态表达式或 new 运算符的结果,自 PHP 4.4.0 和 PHP 5.1.0 起会发出一条 E_NOTICE 错误。


引用的解释
在线手册:中文 英文
PHP手册
PHP手册 - N: 引用返回

用户评论:

benjamin dot delespierre at gmail dot com (23-Feb-2011 01:36)

Keep in mind that returning by reference doesn't work with __callStatic:

<?php
class Test {
  private static
$_inst;
  public static function &
__callStatic ($name, $args) {
    if (!isset(static::
$_inst)){
      echo
"create";
      static::
$_inst = (object)"test";
   }
   return static::
$_inst;
}

var_dump($a = &Test::abc()); // prints 'create'
$a = null;
var_dump(Test::abc()); // doesn't prints and the instance still exists in Test::$_inst
?>

szymoncofalik at gmail dot com (28-Jan-2011 08:41)

Sometimes, you would like to return NULL with a function returning reference, to indicate the end of chain of elements. However this generates E_NOTICE. Here is little tip, how to prevent that:

<?php
class Foo {
   const
$nullGuard = NULL;
  
// ... some declarations and definitions
  
public function &next() {
     
// ...
     
if (!$end) return $bar;
      else return
$this->nullGuard;
   }
}
?>

by doing this you can do smth like this without notices:

<?php
$f
= new Foo();
// ...
while (($item = $f->next()) != NULL) {
// ...
}
?>

you may also use global variable:
global $nullGuard;
return $nullGuard;

spidgorny at gmail dot com (19-Mar-2010 02:18)

When returning reference to the object member which is instantiated inside the function, the object is destructed upon returning (which is a problem). It's easier to see the code:

<?php

class MemcacheArray {
    public
$data;

    ...

   
/**
     * Super-clever one line cache reading AND WRITING!
     * Usage $data = &MemcacheArray::getData(__METHOD__);
     * Hopefully PHP will know that $this->data is still used
     * and will call destructor after data changes.
     * Ooops, it's not the case.   
     *
     * @return unknown
     */
   
function &getData($file, $expire = 3600) {
       
$o = new MemcacheArray($file, $expire);
        return
$o->data;
    }
?>

Here, destructor is called upon return() and the reference becomes a normal variable.

My solution is to store objects in a pool until the final exit(), but I don't like it. Any other ideas?

<?php
   
protected static $instances = array();

    function &
getData($file, $expire = 3600) {
       
$o = new MemcacheArray($file, $expire);
       
self::$instances[$file] = $o; // keep object from destructing too early
       
return $o->data;
    }
?>

sandaimespaceman at gmail dot com (02-Nov-2008 04:52)

The &b() function returns a reference of $a in the global scope.

<?php
$a
= 0;
function &
b()
{
    global
$a;
    return
$a;
}
$c = &b();
$c++;
echo
"
\$a:
$a
\$b:
$c
"
?>

It outputs:

$a: 1 $b: 1

sandaimespaceman at gmail dot com (20-Sep-2008 07:09)

References can produce a chain like what jQuery used:
<?php
$a
= new test();
echo (
$a -> one() -> two() -> one() -> two() -> one() -> two() -> f);
?>
instead of
<?php
$a
= new test();
$a -> one();
$a -> two();
$a  -> one();
$a  -> two();
$a  -> one();
$a  -> two();
echo
$a -> f;
?>
They both return 29.

interframe at 126 dot com (30-Jul-2008 03:33)

"Return by reference" cause private member can be accessed from outside of the class, as shown:

<?php
class foo {
    private
$value = 42;

    public function &
getValue() {
        return
$this->value;
    }
    public function
echoValue(){
        echo
"in class the private \$value = $this->value <br />";
    }
}

$obj = new foo;
$myValue = &$obj->getValue();
$myValue = 33;    //the private foo::$value been changed
$obj->echoValue();  

?>

Spad-XIII (31-Jan-2008 01:01)

a little addition to the example of pixel at minikomp dot com here below
<?php

   
function &func(){
        static
$static = 0;
       
$static++;
        return
$static;
    }

   
$var1 =& func();
    echo
"var1:", $var1; // 1
   
func();
   
func();
    echo
"var1:", $var1; // 3
   
$var2 = func(); // assignment without the &
   
echo "var2:", $var2; // 4
   
func();
   
func();
    echo
"var1:", $var1; // 6
   
echo "var2:", $var2; // still 4

?>

pixel at minikomp dot com (31-Dec-2007 12:21)

<?php

   
function &func(){
        static
$static = 0;
       
$static++;
        return
$static;
    }

   
$var =& func();
    echo
$var; // 1
   
func();
   
func();
   
func();
   
func();
    echo
$var; // 5

?>

stanlemon at mac dot com (28-Sep-2007 06:51)

I haven't seen anyone note method chaining in PHP5.  When an object is returned by a method in PHP5 it is returned by default as a reference, and the new Zend Engine 2 allows you to chain method calls from those returned objects.  For example consider this code:

<?php

class Foo {

    protected
$bar;

    public function
__construct() {
       
$this->bar = new Bar();

        print
"Foo\n";
    }   
   
    public function
getBar() {
        return
$this->bar;
    }
}

class
Bar {

    public function
__construct() {
        print
"Bar\n";
    }
   
    public function
helloWorld() {
        print
"Hello World\n";
    }
}

function
test() {
    return new
Foo();
}

test()->getBar()->helloWorld();

?>

Notice how we called test() which was not on an object, but returned an instance of Foo, followed by a method on Foo, getBar() which returned an instance of Bar and finally called one of its methods helloWorld().  Those familiar with other interpretive languages (Java to name one) will recognize this functionality.  For whatever reason this change doesn't seem to be documented very well, so hopefully someone will find this helpful.

cesoid at yahoo dot com (23-Feb-2007 08:27)

The note by zayfod below is very misleading. The following is not true:

"You do not have to use & to indicate that reference binding should be done when you assign to a value passed by reference the result of a function which returns by reference."

As proof, you can change zayfod's second example slightly to show that $var does not, as he claims, become a reference to $some_var.

<?php

class some_class
{
    function    &
func_b ()
    {
      
$this->some_var = 2;
       return
$this->some_var;
    }
   
    function   
func_a (& $param)
    {
      
# $param is 1 here
      
$param = $this->func_b();
      
# $param is 2 here
   
}
}

$var = 1;

$object = new some_class();
$object->func_a($var);

print
$var; // this prints two
$var = 5;
print
$object->some_var;
// $object->some_var  is still 2, because $var is not bound to it
// (as the original post by zayfod claims) and therefore has no
// effect on it
?>

In actuality it is impossible to bind a variable passed by reference to a variable returned by reference, doing so only removes the link between the internal parameter variable and binds it to something new. This is why zayfod's first example shows $var having a value of 1 at the end. What is actually happening in zayfod's first example is the following:
1) $var is passed by reference into func_a, which binds $param to $var
2) func_b is evaluated, returning a reference to $some_var
3) $param is bounded to $some_var therefore losing it's binding to $var
4) func_a returns, with $var unchanged

In the second example step 1 and 2 are the same, but then this happens:
3) the value 2 is copied into $param, which still references $var, and therefore $var now also evaluates to 2
4) func_a returns, $var is 2, but is not bound to $some_var (and wouldn't be even in my example where some_var still exists afterward)

The mistake seems to be based on misuse of references. When you return a reference, it means that you want a variable that is tied to another, so that when you change one, the other one changes. In zayfod's example, returning by reference is pointless, because $some_var ceases to exist after the function is completed, it won't stay tied to anything.

There are two ways to change those functions so that in the end you have $var actually bound to $this->some_var:

1) Pass $param into func_b by reference and reference $this->some_var to func_b's parameter like so:

func_b (&$b_param)
{
      $this->some_var =& $b_param; // be careful not to flip this
      $this->some_var = 2;
}

2) change func_a to return the result of func_b by reference, and reference that to $var

And remember this simple rule: If a variable is already referenced to another variable and you reference it to a third (put it on the left side of =&) it loses its original reference. This is what happens to $param in zayfod's example. (Also don't forget that passing by reference actually references the internal parameter variable to the the passed variable.)

php at thunder-2000 dot com (02-Feb-2007 10:31)

If you want to get a part of an array to manipulate, you can use this function

function &getArrayField(&$array,$path) {
  if (!empty($path)) {
    if (empty($array[$path[0]])) return NULL;
    else return getArrayField($array[$path[0]], array_slice($path, 1));
  } else {
    return $array;
  }
}

Use it like this:

$partArray =& getArrayField($GLOBALS,array("config","modul1"));

You can manipulate $partArray and the changes are also made with $GLOBALS.

neozenkai at yahoo dot com (15-Jul-2006 09:38)

While trying to create a function to return Database connection objects, it took me a while to get this right:

<?php

class TestClass
{
    var
$thisVar = 0;

    function
TestClass($value)
    {
       
$this->thisVar = $value;
    }

    function &
getTestClass($value)
    {
        static
$classes;

        if (!isset(
$classes[$value]))
        {
           
$classes[$value] = new TestClass($value);
        }

        return
$classes[$value];
    }
}

echo
"<pre>";

echo
"Getting class1 with a value of 432\n";
$class1 =& TestClass::getTestClass(432);
echo
"Value is: " . $class1->thisVar . "\n";

echo
"Getting class2 with a value of 342\n";
$class2 =& TestClass::getTestClass(342);
echo
"Value is: " . $class2->thisVar . "\n";

echo
"Getting class3 with the same value of 432\n";
$class3 =& TestClass::getTestClass(432);
echo
"Value is: " . $class3->thisVar . "\n";

echo
"Changing the value of class1 to 3425, which should also change class3\n";
$class1->thisVar = 3425;

echo
"Now checking value of class3: " . $class3->thisVar . "\n";

?>

Which outputs:

Getting class1 with a value of 432
Value is: 432
Getting class2 with a value of 342
Value is: 342
Getting class3 with the same value of 432
Value is: 432
Changing the value of class1 to 3425, which should also change class3
Now checking value of class3: 3425

Note that PHP syntax is different from C/C++ in that you must use the & operator in BOTH places, as stated by the manual. It took me a while to figure this out.

rwruck (27-Feb-2006 05:22)

The note about using parentheses when returning references is only true if the variable you try to return does not already contain a reference.

<?php
// Will return a reference
function& getref1()
  {
 
$ref =& $GLOBALS['somevar'];
  return (
$ref);
  }

// Will return a value (and emit a notice)
function& getref2()
  {
 
$ref = 42;
  return (
$ref);
  }

// Will return a reference
function& getref3()
  {
  static
$ref = 42;
  return (
$ref);
  }
?>

warhog at warhog dot net (13-Dec-2005 08:04)

firstly a note on the post below: technically correct that -> "to get a reference to an exsisting class and it's properties" should be "...to an existing object..."

in PHP5 it's senseless to return objects by reference.. let's say you have, as in the post below, a class which should return a reference to its own instance (maybe it's been created using the singleton pattern..), than it's no problem to simply return that variable holding the instance.
In PHP5 variables holding objects are always references to a specific object, so when you return (=copy) a variable "having" an object you in fact return a reference to that object.

Because of that behaviour, which is very common for many programming languages, especially those, which are to be compiled (due to memory problems and so on), you have to use the clone-function which was introduced in PHP5.

Here an example to underline what i mean:

<?php

class sample_singleton
{
  protected static
$instance = NULL;
 
  private function
__construct()
  { }

  public static function
create()
  {
self::$instance = new sample_singleton(); }

  public static function
getInstance()
  { return
self::$instance; }

  public function
yea()
  { echo
"wuow"; }
}

sample_singleton::create();

// $singleton will be a reference to sample_singleton::$instance
$singleton = sample_singleton::getInstance();

$singleton->yea();

?>

Note some more (maybe) strange behaviour: although $instance is private you can have a reference pointing on it. Maybe that does not seem strange to you in any way, but maybe you wondered as i did : )

The code posted here was just a sample to illustrate my posting, for using the singleton pattern please look it up in the manual. I just used this cause it was the simplest example which went in my mind right know.

willem at designhulp dot nl (09-Oct-2005 12:54)

There is an important difference between php5 and php4 with references.

Lets say you have a class with a method called 'get_instance' to get a reference to an exsisting class and it's properties.

<?php
class mysql {
    function
get_instance(){
       
// check if object exsists
       
if(empty($_ENV['instances']['mysql'])){
           
// no object yet, create an object
           
$_ENV['instances']['mysql'] = new mysql;
        }
       
// return reference to object
       
$ref = &$_ENV['instances']['mysql'];
        return
$ref;
    }
}
?>

Now to get the exsisting object you can use
mysql::get_instance();

Though this works in php4 and in php5, but in php4 all data will be lost as if it is a new object while in php5 all properties in the object remain.

obscvresovl at NOSPAM dot hotmail dot com (24-Dec-2004 09:09)

An example of returning references:

<?

$var = 1;
$num = NULL;

function &blah()
{
    $var =& $GLOBALS["var"]; # the same as global $var;
    $var++;
    return $var;
}

$num = &blah();

echo $num; # 2

blah();

echo $num; # 3

?>

Note: if you take the & off from the function, the second echo will be 2, because without & the var $num contains its returning value and not its returning reference.

hawcue at yahoo dot com (17-Mar-2004 03:58)

Be careful when using tinary operation condition?value1:value2

See the following code:

$a=1;
function &foo()
{
  global $a;
  return isset($a)?$a:null;
}
$b=&foo();
echo $b;   // shows 1
$b=2;
echo $a;   // shows 1 (not 2! because $b got a copy of $a)

To let $b be a reference to $a, use "if..then.." in the function.

contact at infopol dot fr (12-Feb-2004 05:36)

A note about returning references embedded in non-reference arrays :

<?
$foo;

function bar () {
    global $foo;
    $return = array();
    $return[] =& $foo;
    return $return;
}

$foo = 1;
$foobar = bar();
$foobar[0] = 2;
echo $foo;
?>

results in "2" because the reference is copied (pretty neat).

zayfod at yahoo dot com (03-Dec-2003 05:23)

There is a small exception to the note on this page of the documentation. You do not have to use & to indicate that reference binding should be done when you assign to a value passed by reference the result of a function which returns by reference.

Consider the following two exaples:

<?php

function    & func_b ()
{
   
$some_var = 2;
    return
$some_var;
}

function   
func_a (& $param)
{
   
# $param is 1 here
   
$param = & func_b();
   
# $param is 2 here
}

$var = 1;
func_a($var);
# $var is still 1 here!!!

?>

The second example works as intended:

<?php

function    & func_b ()
{
   
$some_var = 2;
    return
$some_var;
}

function   
func_a (& $param)
{
   
# $param is 1 here
   
$param = func_b();
   
# $param is 2 here
}

$var = 1;
func_a($var);
# $var is 2 here as intended

?>

(Experienced with PHP 4.3.0)