<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.39 $ -->
 <chapter id="language.references">
  <title>References Explained</title>

  <sect1 id="language.references.whatare">
   <title>What References Are</title>
   <simpara>  
    References in PHP are a means to access the same variable content 
    by different names. They are not like C pointers, they are symbol
    table aliases. Note that in PHP, variable name and variable content 
    are different, so the same content can have different names.
    The most close analogy is with Unix filenames and files -
    variable names are directory entries, while variable contents is
    the file itself. References can be thought of as hardlinking in
    Unix filesystem.
   </simpara>
  </sect1>

  <sect1 id="language.references.whatdo">
   <title>What References Do</title>
   <para>
    PHP references allow you to make two variables to refer to the
    same content. Meaning, when you do:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$a =& $b;
?>
]]>
     </programlisting>
    </informalexample>
    it means that <varname>$a</varname> and <varname>$b</varname>
    point to the same content.
    <note>
     <para>
      <varname>$a</varname> and <varname>$b</varname> are completely
      equal here, that's not <varname>$a</varname> is pointing to
      <varname>$b</varname> or vice versa, that's
      <varname>$a</varname> and <varname>$b</varname> pointing to the
      same place.
     </para>
    </note>
   </para>
   <note>
    <para>
     If array with references is copied, its values are not dereferenced.
     This is valid also for arrays passed by value to functions.
    </para>
   </note>
   <para>
   The same syntax can be used with functions, that return references,
   and with <literal>new</literal> operator (in PHP 4.0.4 and later):
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$bar =& new fooclass();
$foo =& find_var($bar);
?>
]]>
    </programlisting>
    </informalexample>
    </para>
    <note>
     <para>
     Not using the <literal>&amp;</literal> operator causes a copy of the
     object to be made. If you use <literal>$this</literal> in the class it
     will operate on the current instance of the class. The assignment without
     <literal>&amp;</literal> will copy the instance (i.e. the object) and
     <literal>$this</literal> will operate on the copy, which is not always
     what is desired. Usually you want to have a single instance to work with,
     due to performance and memory consumption issues.
     </para>
     <para>
      While you can use the <literal>@</literal> operator to
      <emphasis>mute</emphasis> any errors in the constructor when using it as
      <literal>@new</literal>, this does not work when using the
      <literal>&amp;new</literal> statement. This is a limitation of the Zend
      Engine and will therefore result in a parser error.
     </para>
   </note>
   <warning>
    <para>
     If you assign a reference to a variable declared <literal>global</literal>
     inside a function, the reference will be visible only inside the function.
     You can avoid this by using the <varname>$GLOBALS</varname> array.
     <example>
      <title>Referencing global variables inside function</title>
      <programlisting role="php">
<![CDATA[
<?php
$var1 = "Example variable";
$var2 = "";

function global_references($use_globals)
{
    global $var1, $var2;
    if (!$use_globals) {
        $var2 =& $var1; // visible only inside the function
    } else {
        $GLOBALS["var2"] =& $var1; // visible also in global context
    }
}

global_references(false);
echo "var2 is set to '$var2'\n"; // var2 is set to ''
global_references(true);
echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
?>
]]>
      </programlisting>
     </example>
     Think about <literal>global $var;</literal> as a shortcut to <literal>$var
     =&amp; $GLOBALS['var'];</literal>. Thus assigning other reference
     to <literal>$var</literal> only changes the local variable's reference.
    </para>
   </warning>
   <note>
    <para>
     If you assign a value to a variable with references in a <link
     linkend="control-structures.foreach">foreach</link> statement,
     the references are modified too.
     <example>
      <title>References and foreach statement</title>
      <programlisting role="php">
<![CDATA[
<?php
$ref = 0;
$row =& $ref;
foreach (array(1, 2, 3) as $row) {
    // do something
}
echo $ref; // 3 - last element of the iterated array
?>
]]>
      </programlisting>
     </example>
    </para>
   </note>
   <warning>
    <para>
     Complex arrays are sometimes rather copied than referenced. Thus following
     example will not work as expected.
     <example>
      <title>References with complex arrays</title>
      <programlisting role="php">
<![CDATA[
<?php
$top = array(
    'A' => array(),
    'B' => array(
        'B_b' => array(),
    ),
);

$top['A']['parent'] = &$top;
$top['B']['parent'] = &$top;
$top['B']['B_b']['data'] = 'test';
print_r($top['A']['parent']['B']['B_b']); // array()
?>
]]>
      </programlisting>
     </example>
    </para>
   </warning>
   <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 reference to the same content. Example:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var++;
}

$a=5;
foo($a);
?>
]]>
     </programlisting>
    </informalexample>
    will make <varname>$a</varname> to be 6. This happens because in
    the function <varname>foo</varname> the variable
    <varname>$var</varname> refers to the same content as
    <varname>$a</varname>. See also more detailed explanations about <link
    linkend="language.references.pass">passing by reference</link>.
   </para>
   <simpara>
    The third thing reference can do is <link
    linkend="language.references.return">return by reference</link>.
   </simpara>
  </sect1>

  <sect1 id="language.references.arent">
   <title>What References Are Not</title>
   <para>
    As said before, references aren't pointers. That means, the
    following construct won't do what you expect:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar); 
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    What happens is that <varname>$var</varname> in
    <varname>foo</varname> will be bound with
    <varname>$bar</varname> in caller, but then it will be
    re-bound with <varname>$GLOBALS["baz"]</varname>. There's no way
    to bind <varname>$bar</varname> in the calling scope to something else
    using the reference mechanism, since <varname>$bar</varname> is not
    available in the function <varname>foo</varname> (it is represented by
    <varname>$var</varname>, but <varname>$var</varname> has only
    variable contents and not name-to-value binding in the calling
    symbol table).
    You can use <link linkend="language.references.return">returning
    references</link> to reference variables selected by the function.
   </simpara>
  </sect1>

  <sect1 id="language.references.pass">
   <title>Passing by Reference</title>
   <para>
   You can pass variable to function by reference, so that function could modify
   its arguments. The syntax is as follows:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var++;
}

$a=5;
foo($a);
// $a is 6 here
?>
]]>
     </programlisting>
    </informalexample>
  Note that there's no reference sign on function call - only on
  function definition. Function definition alone is enough to
  correctly pass the argument by reference. 
  </para>
  <para>
  Following things can be passed by reference:
   <itemizedlist>
    <listitem>
     <simpara>
      Variable, i.e. <literal>foo($a)</literal>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      New statement, i.e. <literal>foo(new foobar())</literal>
     </simpara>
    </listitem>
    <listitem>
     <para>
      Reference, returned from a function, i.e.:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function &bar()
{
    $a = 5;
    return $a;
}
foo(bar());
?>
]]>
     </programlisting>
    </informalexample>
    See also explanations about <link
    linkend="language.references.return">returning by reference</link>. 
     </para>
    </listitem>
  </itemizedlist>
  </para>
  <para>
  Any other expression should not be passed by reference, as the
  result is undefined. For example, the following examples of passing
  by reference are invalid:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function bar() // Note the missing &
{
    $a = 5;
    return $a;
}
foo(bar());

foo($a = 5); // Expression, not variable
foo(5); // Constant, not variable
?>
]]>
     </programlisting>
    </informalexample>
    These requirements are for PHP 4.0.4 and later.
  </para>
  </sect1>

  <sect1 id="language.references.return">
   <title>Returning References</title>
   <para>
    Returning by-reference is useful when you want to use a function
    to find which variable a reference should be bound to. When
    returning references, use this syntax:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function &find_var($param)
{
    /* ...code... */
    return $found_var;
}

$foo =& find_var($bar);
$foo->x = 2;
?>
]]>
     </programlisting>
    </informalexample>
    In this example, the property of the object returned by the
    <varname>find_var</varname> function would be set, not the
    copy, as it would be without using reference syntax.
   </para>
   <note>
    <simpara>
     Unlike parameter passing, here you have to use
     <literal>&amp;</literal> in both places - to indicate that you
     return by-reference, not a copy as usual, and to indicate that
     reference binding, rather than usual assignment, should be done
     for <varname>$foo</varname>.
     <literal>&amp;</literal> by function definition is optional in
     <link linkend="keyword.class">class</link> methods.
    </simpara>
   </note>
  </sect1>

  <sect1 id="language.references.unset">
   <title>Unsetting References</title>
   <para>
    When you unset the reference, you just break the binding between
    variable name and variable content. This does not mean that
    variable content will be destroyed. For example:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b =& $a;
unset($a); 
?>
]]>
     </programlisting>
    </informalexample>
    won't unset <varname>$b</varname>, just <varname>$a</varname>. 
   </para>
   <simpara>
    Again, it might be useful to think about this as analogous to Unix
    <command>unlink</command> call.
   </simpara>
  </sect1>

  <sect1 id="language.references.spot">
   <title>Spotting References</title>
   <simpara>
    Many syntax constructs in PHP are implemented via referencing
    mechanisms, so everything told above about reference binding also
    apply to these constructs. Some constructs, like passing and
    returning by-reference, are mentioned above. Other constructs that
    use references are:
   </simpara>

   <sect2 id="references.global">
    <title><literal>global</literal> References</title>
    <para>
     When you declare variable as <command>global $var</command> you
     are in fact creating reference to a global variable. That means,
     this is the same as:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$var =& $GLOBALS["var"];
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     That means, for example, that unsetting <varname>$var</varname>
     won't unset global variable.
    </simpara>
   </sect2>

   <sect2 id="references.this">
    <title><literal>$this</literal></title>
    <simpara>
     In an object method, <varname>$this</varname> is always reference
     to the caller object.
    </simpara>
   </sect2>
  </sect1>

 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->