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

  <sect1 id="language.references.whatare">
   <title>What are References</title>
   <simpara>  
    References in PHP are means to call same variable content with
    different names. They are not like C pointers, they are symbol
    table aliases.  Note that in PHP, variable names and variable
    content are different, so same content can have different
    names. The most close analogy is 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 do References</title>
   <para>
    PHP references allow you to make two variables to refer to the
    same content. Meaning, when you do:
    <informalexample>
     <programlisting role="php">
$a =&amp; $b 
     </programlisting>
    </informalexample>
    it means that <varname>$a</varname> and <varname>$b</varname>
    point to the same variable.
    <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>
   <para>
    The second thing references do is to pass variables
    by-reference. This is done by making local function variable and
    caller variable to be reference to the same content. Example:
    <informalexample>
     <programlisting role="php">
function foo (&amp;$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>.
   </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 aren't References</title>
   <para>
    As said above, references aren't pointers. That means, the
    following construct won't do what you expect:
    <informalexample>
     <programlisting role="php">
function foo (&amp;$var) {
    $var =&amp; $GLOBALS["baz"];
}
foo($bar); 
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    What will happen that <varname>$var</varname> in foo 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 caller to something else
    using reference mechanism, since <varname>$bar</varname> is not
    available in the function foo (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).
   </simpara>
  </sect1>

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

$foo =&amp; find_var ($bar);
$foo->x = 2; 
     </programlisting>
    </informalexample>
    In this example, property of the object returned by the
    <varname>find_var</varname> function would be set, not of 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 than
     reference binding and not usual assignment should be done for
     <varname>$foo</varname>.
    </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">
$a = 1;
$b =&amp; $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 the Reference</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">
$var =&amp; $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:
-->