<?xml version="1.0" encoding="utf-8"?>
<sect1 xml:id="language.operators.assignment">
 <title>Assignment Operators</title>
 <titleabbrev>Assignment</titleabbrev>
 <simpara>
  The basic assignment operator is "=". Your first inclination might
  be to think of this as "equal to". Don't. It really means that the
  left operand gets set to the value of the expression on the
  right (that is, "gets set to").
 </simpara>
 <para>
  The value of an assignment expression is the value assigned. That
  is, the value of "<literal>$a = 3</literal>" is 3. This allows you to do some tricky
  things:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

$a = ($b = 4) + 5; // $a is equal to 9 now, and $b has been set to 4.

?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  In addition to the basic assignment operator, there are "combined
  operators" for all of the <link linkend="language.operators">binary
  arithmetic</link>, array union and string operators that allow you to use a value in an
  expression and then set its value to the result of that expression. For
  example:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

$a = 3;
$a += 5; // sets $a to 8, as if we had said: $a = $a + 5;
$b = "Hello ";
$b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";

?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  Note that the assignment copies the original variable to the new
  one (assignment by value), so changes to one will not affect the
  other. This may also have relevance if you need to copy something
  like a large array inside a tight loop.
 </para>
 <para>
  An exception to the usual assignment by value behaviour within PHP occurs
  with <type>object</type>s, which are assigned by reference.
  Objects may be explicitly copied via the <link
  linkend="language.oop5.cloning">clone</link> keyword.
 </para>

 <sect2 xml:id="language.operators.assignment.reference">
  <title>Assignment by Reference</title>
  <para>
   Assignment by reference is also supported, using the
   "<computeroutput>$var = &amp;$othervar;</computeroutput>" syntax.
   Assignment by reference means that both variables end up pointing at the
   same data, and nothing is copied anywhere.
  </para>
  <para>
   <example>
    <title>Assigning by reference</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = 3;
$b = &$a; // $b is a reference to $a

print "$a\n"; // prints 3
print "$b\n"; // prints 3

$a = 4; // change $a

print "$a\n"; // prints 4
print "$b\n"; // prints 4 as well, since $b is a reference to $a, which has
              // been changed
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   The <link linkend="language.oop5.basic.new">new</link>
   operator returns a reference automatically, as such assigning the result of
   <link linkend="language.oop5.basic.new">new</link> by reference is an error.
  </para>
  <para>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
class C {}

$o = &new C;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Parse error: syntax error, unexpected 'new' (T_NEW) in …
]]>
    </screen>
   </informalexample>
  </para>
  <para>
   More information on references and their potential uses can be found in
   the <link linkend="language.references">References Explained</link>
   section of the manual.
  </para>
 </sect2>

 <sect2 xml:id="language.operators.assignment.arithmetic">
  <title>Arithmetic Assignment Operators</title>
  <informaltable>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Example</entry>
      <entry>Equivalent</entry>
      <entry>Operation</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>$a += $b</entry>
      <entry>$a = $a + $b</entry>
      <entry>Addition</entry>
     </row>
     <row>
      <entry>$a -= $b</entry>
      <entry>$a = $a - $b</entry>
      <entry>Subtraction</entry>
     </row>
     <row>
      <entry>$a *= $b</entry>
      <entry>$a = $a * $b</entry>
      <entry>Multiplication</entry>
     </row>
     <row>
      <entry>$a /= $b</entry>
      <entry>$a = $a / $b</entry>
      <entry>Division</entry>
     </row>
     <row>
      <entry>$a %= $b</entry>
      <entry>$a = $a % $b</entry>
      <entry>Modulus</entry>
     </row>
     <row>
      <entry>$a **= $b</entry>
      <entry>$a = $a ** $b</entry>
      <entry>Exponentiation</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </sect2>

 <sect2 xml:id="language.operators.assignment.bitwise">
  <title>Bitwise Assignment Operators</title>
  <informaltable>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Example</entry>
      <entry>Equivalent</entry>
      <entry>Operation</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>$a &amp;= $b</entry>
      <entry>$a = $a &amp; $b</entry>
      <entry>Bitwise And</entry>
     </row>
     <row>
      <entry>$a |= $b</entry>
      <entry>$a = $a | $b</entry>
      <entry>Bitwise Or</entry>
     </row>
     <row>
      <entry>$a ^= $b</entry>
      <entry>$a = $a ^ $b</entry>
      <entry>Bitwise Xor</entry>
     </row>
     <row>
      <entry>$a &lt;&lt;= $b</entry>
      <entry>$a = $a &lt;&lt; $b</entry>
      <entry>Left Shift</entry>
     </row>
     <row>
      <entry>$a &gt;&gt;= $b</entry>
      <entry>$a = $a &gt;&gt; $b</entry>
      <entry>Right Shift</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </sect2>

 <sect2 xml:id="language.operators.assignment.other">
  <title>Other Assignment Operators</title>
  <informaltable>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Example</entry>
      <entry>Equivalent</entry>
      <entry>Operation</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>$a .= $b</entry>
      <entry>$a = $a . $b</entry>
      <entry>String Concatenation</entry>
     </row>
     <row>
      <entry>$a ??= $b</entry>
      <entry>$a = $a ?? $b</entry>
      <entry>Null Coalesce</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </sect2>

 <sect2 role="seealso" xml:id="language.operators.assignment.see-also">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="language.operators.arithmetic">arithmetic operators</link></member>
    <member><link linkend="language.operators.bitwise">bitwise operators</link></member>
    <member><link linkend="language.operators.comparison.coalesce">null coalescing operator</link></member>
   </simplelist>
  </para>
 </sect2>
</sect1>