<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>What References Do</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.references.whatare.html">What References Are</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.references.arent.html">What References Are Not</a></div>
<div class="up"><a href="language.references.html">References Explained</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="language.references.whatdo" class="sect1">
<h2 class="title">What References Do</h2>
<p class="para">
There are three basic operations performed using references:
<a href="language.references.whatdo.html#language.references.whatdo.assign" class="link">assigning by
reference</a>, <a href="language.references.whatdo.html#language.references.whatdo.pass" class="link">passing
by reference</a>,
and <a href="language.references.whatdo.html#language.references.whatdo.return" class="link">returning by
reference</a>. This section will give an introduction to these
operations, with links for further reading.
</p>
<div class="sect2" id="language.references.whatdo.assign">
<h3 class="title">Assign By Reference</h3>
<p class="para">
In the first of these, PHP references allow you to make two
variables refer to the same content. Meaning, when you do:
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$a </span><span style="color: #007700">=& </span><span style="color: #0000BB">$b</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
it means that <var class="varname"><var class="varname">$a</var></var> and <var class="varname"><var class="varname">$b</var></var>
point to the same content.
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
<var class="varname"><var class="varname">$a</var></var> and <var class="varname"><var class="varname">$b</var></var> are completely
equal here. <var class="varname"><var class="varname">$a</var></var> is not pointing to
<var class="varname"><var class="varname">$b</var></var> or vice versa.
<var class="varname"><var class="varname">$a</var></var> and <var class="varname"><var class="varname">$b</var></var> are pointing to the
same place.
</p>
</p></blockquote>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If you assign, pass, or return an undefined variable by reference,
it will get created.
<div class="example" id="example-279">
<p><strong>Example #1 Using references with undefined variables</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">foo</span><span style="color: #007700">(&</span><span style="color: #0000BB">$var</span><span style="color: #007700">) { }<br /><br /></span><span style="color: #0000BB">foo</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">); </span><span style="color: #FF8000">// $a is "created" and assigned to null<br /><br /></span><span style="color: #0000BB">$b </span><span style="color: #007700">= array();<br /></span><span style="color: #0000BB">foo</span><span style="color: #007700">(</span><span style="color: #0000BB">$b</span><span style="color: #007700">[</span><span style="color: #DD0000">'b'</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">array_key_exists</span><span style="color: #007700">(</span><span style="color: #DD0000">'b'</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">)); </span><span style="color: #FF8000">// bool(true)<br /><br /></span><span style="color: #0000BB">$c </span><span style="color: #007700">= new </span><span style="color: #0000BB">StdClass</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">foo</span><span style="color: #007700">(</span><span style="color: #0000BB">$c</span><span style="color: #007700">-></span><span style="color: #0000BB">d</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">property_exists</span><span style="color: #007700">(</span><span style="color: #0000BB">$c</span><span style="color: #007700">, </span><span style="color: #DD0000">'d'</span><span style="color: #007700">)); </span><span style="color: #FF8000">// bool(true)<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</p></blockquote>
<p class="para">
The same syntax can be used with functions that return
references, and with the <em>new</em> operator (since PHP
4.0.4 and before PHP 5.0.0):
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$foo </span><span style="color: #007700">=& </span><span style="color: #0000BB">find_var</span><span style="color: #007700">(</span><span style="color: #0000BB">$bar</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
Since PHP 5, <a href="language.oop5.basic.html#language.oop5.basic.new" class="link">new</a>
returns a reference automatically, so
using <em>=&</em> in this context is deprecated and
produces an <strong><code>E_DEPRECATED</code></strong> message in PHP 5.3 and
later, and an <strong><code>E_STRICT</code></strong> message in earlier versions.
(Technically, the difference is that, in PHP 5, object variables, much like
resources, are a mere pointer to the actual object data, so these object
references are not "references" in the same sense used before (aliases).
For more information, see <a href="language.oop5.references.html" class="link">Objects
and references</a>.)
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
If you assign a reference to a variable declared <em>global</em>
inside a function, the reference will be visible only inside the function.
You can avoid this by using the <var class="varname"><var class="varname"><a href="reserved.variables.globals.html" class="classname">$GLOBALS</a></var></var> array.
<div class="example" id="example-280">
<p><strong>Example #2 Referencing global variables inside functions</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$var1 </span><span style="color: #007700">= </span><span style="color: #DD0000">"Example variable"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$var2 </span><span style="color: #007700">= </span><span style="color: #DD0000">""</span><span style="color: #007700">;<br /><br />function </span><span style="color: #0000BB">global_references</span><span style="color: #007700">(</span><span style="color: #0000BB">$use_globals</span><span style="color: #007700">)<br />{<br /> global </span><span style="color: #0000BB">$var1</span><span style="color: #007700">, </span><span style="color: #0000BB">$var2</span><span style="color: #007700">;<br /> if (!</span><span style="color: #0000BB">$use_globals</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$var2 </span><span style="color: #007700">=& </span><span style="color: #0000BB">$var1</span><span style="color: #007700">; </span><span style="color: #FF8000">// visible only inside the function<br /> </span><span style="color: #007700">} else {<br /> </span><span style="color: #0000BB">$GLOBALS</span><span style="color: #007700">[</span><span style="color: #DD0000">"var2"</span><span style="color: #007700">] =& </span><span style="color: #0000BB">$var1</span><span style="color: #007700">; </span><span style="color: #FF8000">// visible also in global context<br /> </span><span style="color: #007700">}<br />}<br /><br /></span><span style="color: #0000BB">global_references</span><span style="color: #007700">(</span><span style="color: #0000BB">false</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"var2 is set to '</span><span style="color: #0000BB">$var2</span><span style="color: #DD0000">'\n"</span><span style="color: #007700">; </span><span style="color: #FF8000">// var2 is set to ''<br /></span><span style="color: #0000BB">global_references</span><span style="color: #007700">(</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"var2 is set to '</span><span style="color: #0000BB">$var2</span><span style="color: #DD0000">'\n"</span><span style="color: #007700">; </span><span style="color: #FF8000">// var2 is set to 'Example variable'<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
Think about <em>global $var;</em> as a shortcut to <em>$var
=& $GLOBALS['var'];</em>. Thus assigning another reference
to <em>$var</em> only changes the local variable's reference.
</p>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If you assign a value to a variable with references in a
<a href="control-structures.foreach.html" class="link">foreach</a> statement, the references are modified too.
<div class="example" id="example-281">
<p><strong>Example #3 References and foreach statement</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$ref </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$row </span><span style="color: #007700">=& </span><span style="color: #0000BB">$ref</span><span style="color: #007700">;<br />foreach (array(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">3</span><span style="color: #007700">) as </span><span style="color: #0000BB">$row</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// do something<br /></span><span style="color: #007700">}<br />echo </span><span style="color: #0000BB">$ref</span><span style="color: #007700">; </span><span style="color: #FF8000">// 3 - last element of the iterated array<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</p></blockquote>
<p class="para">
While not being strictly an assignment by reference, expressions created
with the language construct
<a href="function.array.html" class="link"><em>array()</em></a> can also
behave as such by prefixing <em>&</em> to the array element
to add. Example:
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$a </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$b </span><span style="color: #007700">= array(</span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">3</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$arr </span><span style="color: #007700">= array(&</span><span style="color: #0000BB">$a</span><span style="color: #007700">, &</span><span style="color: #0000BB">$b</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">], &</span><span style="color: #0000BB">$b</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$arr</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]++; </span><span style="color: #0000BB">$arr</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]++; </span><span style="color: #0000BB">$arr</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">]++;<br /></span><span style="color: #FF8000">/* $a == 2, $b == array(3, 4); */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Note, however, that references inside arrays are potentially dangerous.
Doing a normal (not by reference) assignment with a reference on the
right side does not turn the left side into a reference, but references
inside arrays are preserved in these normal assignments. This also applies
to function calls where the array is passed by value. Example:
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Assignment of scalar variables */<br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$b </span><span style="color: #007700">=& </span><span style="color: #0000BB">$a</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$c </span><span style="color: #007700">= </span><span style="color: #0000BB">$b</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$c </span><span style="color: #007700">= </span><span style="color: #0000BB">7</span><span style="color: #007700">; </span><span style="color: #FF8000">//$c is not a reference; no change to $a or $b<br /><br />/* Assignment of array variables */<br /></span><span style="color: #0000BB">$arr </span><span style="color: #007700">= array(</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">=& </span><span style="color: #0000BB">$arr</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]; </span><span style="color: #FF8000">//$a and $arr[0] are in the same reference set<br /></span><span style="color: #0000BB">$arr2 </span><span style="color: #007700">= </span><span style="color: #0000BB">$arr</span><span style="color: #007700">; </span><span style="color: #FF8000">//not an assignment-by-reference!<br /></span><span style="color: #0000BB">$arr2</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]++;<br /></span><span style="color: #FF8000">/* $a == 2, $arr == array(2) */<br />/* The contents of $arr are changed even though it's not a reference! */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
In other words, the reference behavior of arrays is defined in an
element-by-element basis; the reference behavior of individual elements
is dissociated from the reference status of the array container.
</p>
</div>
<div class="sect2" id="language.references.whatdo.pass">
<h3 class="title">Pass By Reference</h3>
<p class="para">
The second thing references do is to pass variables by
reference. This is done by making a local variable in a function
and a variable in the calling scope referencing the same
content. Example:
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">foo</span><span style="color: #007700">(&</span><span style="color: #0000BB">$var</span><span style="color: #007700">)<br />{<br /> </span><span style="color: #0000BB">$var</span><span style="color: #007700">++;<br />}<br /><br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">=</span><span style="color: #0000BB">5</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">foo</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
will make <var class="varname"><var class="varname">$a</var></var> to be 6. This happens because in
the function <var class="varname"><var class="varname">foo</var></var> the variable
<var class="varname"><var class="varname">$var</var></var> refers to the same content as
<var class="varname"><var class="varname">$a</var></var>. For more information on this, read
the <a href="language.references.pass.html" class="link">passing by
reference</a> section.
</p>
</div>
<div class="sect2" id="language.references.whatdo.return">
<h3 class="title">Return By Reference</h3>
<p class="para">
The third thing references can do is <a href="language.references.return.html" class="link">return by reference</a>.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.references.whatare.html">What References Are</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.references.arent.html">What References Are Not</a></div>
<div class="up"><a href="language.references.html">References Explained</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
