<?xml version="1.0" encoding="utf-8"?>
<sect1 xml:id="language.operators.precedence">
 <title>Operator Precedence</title>
 <titleabbrev>Operator Precedence</titleabbrev>
 <para>
  The precedence of an operator specifies how "tightly" it binds two
  expressions together. For example, in the expression <literal>1 +
  5 * 3</literal>, the answer is <literal>16</literal> and not
  <literal>18</literal> because the multiplication ("*") operator
  has a higher precedence than the addition ("+") operator.
  Parentheses may be used to force precedence, if necessary. For
  instance: <literal>(1 + 5) * 3</literal> evaluates to
  <literal>18</literal>.
 </para>
 <para>
  When operators have equal precedence their associativity decides
  how the operators are grouped. For example "-" is left-associative, so
  <literal>1 - 2 - 3</literal> is grouped as <literal>(1 - 2) - 3</literal>
  and evaluates to <literal>-4</literal>. "=" on the other hand is
  right-associative, so <literal>$a = $b = $c</literal> is grouped as
  <literal>$a = ($b = $c)</literal>.
 </para>
 <para>
  Operators of equal precedence that are non-associative cannot be used
  next to each other, for example <literal>1 &lt; 2 &gt; 1</literal> is
  illegal in PHP. The expression <literal>1 &lt;= 1 == 1</literal> on the
  other hand is legal, because the <literal>==</literal> operator has a lower
  precedence than the <literal>&lt;=</literal> operator.
 </para>
 <para>
  Associativity is only meaningful for binary (and ternary) operators.
  Unary operators are either prefix or postfix so this notion is not applicable.
  For example <literal>!!$a</literal> can only be grouped as <literal>!(!$a)</literal>.
 </para>
 <para>
  Use of parentheses, even when not strictly necessary, can often increase
  readability of the code by making grouping explicit rather than relying
  on the implicit operator precedence and associativity.
 </para>
 <para>
  The following table lists the operators in order of precedence, with
  the highest-precedence ones at the top. Operators on the same line
  have equal precedence, in which case associativity decides grouping.
  <table>
   <title>Operator Precedence</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Associativity</entry>
      <entry>Operators</entry>
      <entry>Additional Information</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>(n/a)</entry>
      <entry>
       <literal>clone</literal>
       <literal>new</literal>
      </entry>
      <entry><link linkend="language.oop5.cloning">clone</link> and <link linkend="language.oop5.basic.new">new</link></entry>
     </row>
     <row>
      <entry>right</entry>
      <entry><literal>**</literal></entry>
      <entry><link linkend="language.operators.arithmetic">arithmetic</link></entry>
     </row>
     <row>
      <entry>(n/a)</entry>
      <entry>
       <literal>+</literal>
       <literal>-</literal>
       <literal>++</literal>
       <literal>--</literal>
       <literal>~</literal>
       <literal>(int)</literal>
       <literal>(float)</literal>
       <literal>(string)</literal>
       <literal>(array)</literal>
       <literal>(object)</literal>
       <literal>(bool)</literal>
       <literal>@</literal>
      </entry>
      <entry>
       <link linkend="language.operators.arithmetic">arithmetic</link> (unary <literal>+</literal> and <literal>-</literal>),
       <link linkend="language.operators.increment">increment/decrement</link>,
       <link linkend="language.operators.bitwise">bitwise</link>,
       <link linkend="language.types.typecasting">type casting</link>&listendand;
       <link linkend="language.operators.errorcontrol">error control</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>instanceof</literal></entry>
      <entry>
       <link linkend="language.operators.type">type</link>
      </entry>
     </row>
     <row>
      <entry>(n/a)</entry>
      <entry><literal>!</literal></entry>
      <entry>
       <link linkend="language.operators.logical">logical</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry>
       <literal>*</literal>
       <literal>/</literal>
       <literal>%</literal>
      </entry>
      <entry>
       <link linkend="language.operators.arithmetic">arithmetic</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry>
       <literal>+</literal>
       <literal>-</literal>
       <literal>.</literal>
      </entry>
      <entry>
       <link linkend="language.operators.arithmetic">arithmetic</link> (binary <literal>+</literal> and <literal>-</literal>),
       <link linkend="language.operators.array">array</link>&listendand;
       <link linkend="language.operators.string">string</link> (<literal>.</literal> prior to PHP 8.0.0)
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry>
       <literal>&lt;&lt;</literal>
       <literal>&gt;&gt;</literal>
      </entry>
      <entry>
       <link linkend="language.operators.bitwise">bitwise</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>.</literal></entry>
      <entry>
       <link linkend="language.operators.string">string</link> (as of PHP 8.0.0)
      </entry>
     </row>
     <row>
      <entry>non-associative</entry>
      <entry>
       <literal>&lt;</literal>
       <literal>&lt;=</literal>
       <literal>&gt;</literal>
       <literal>&gt;=</literal>
      </entry>
      <entry>
       <link linkend="language.operators.comparison">comparison</link>
      </entry>
     </row>
     <row>
      <entry>non-associative</entry>
      <entry>
       <literal>==</literal>
       <literal>!=</literal>
       <literal>===</literal>
       <literal>!==</literal>
       <literal>&lt;&gt;</literal>
       <literal>&lt;=&gt;</literal>
      </entry>
      <entry>
       <link linkend="language.operators.comparison">comparison</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>&amp;</literal></entry>
      <entry>
       <link linkend="language.operators.bitwise">bitwise</link>&listendand;
       <link linkend="language.references">references</link></entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>^</literal></entry>
      <entry>
       <link linkend="language.operators.bitwise">bitwise</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>|</literal></entry>
      <entry>
       <link linkend="language.operators.bitwise">bitwise</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>&amp;&amp;</literal></entry>
      <entry>
       <link linkend="language.operators.logical">logical</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>||</literal></entry>
      <entry>
       <link linkend="language.operators.logical">logical</link>
      </entry>
     </row>
     <row>
      <entry>right</entry>
      <entry><literal>??</literal></entry>
      <entry>
       <link linkend="language.operators.comparison.coalesce">null coalescing</link>
      </entry>
     </row>
     <row>
      <entry>non-associative</entry>
      <entry><literal>? :</literal></entry>
      <entry>
       <link linkend="language.operators.comparison.ternary">ternary</link>
       (left-associative prior to PHP 8.0.0)
      </entry>
     </row>
     <row>
      <entry>right</entry>
      <entry>
       <literal>=</literal>
       <literal>+=</literal>
       <literal>-=</literal>
       <literal>*=</literal>
       <literal>**=</literal>
       <literal>/=</literal>
       <literal>.=</literal>
       <literal>%=</literal>
       <literal>&amp;=</literal>
       <literal>|=</literal>
       <literal>^=</literal>
       <literal>&lt;&lt;=</literal>
       <literal>&gt;&gt;=</literal>
       <literal>??=</literal>
      </entry>
      <entry>
       <link linkend="language.operators.assignment">assignment</link>
      </entry>
     </row>
     <row>
      <entry>(n/a)</entry>
      <entry><literal>yield from</literal></entry>
      <entry>
       <link linkend="control-structures.yield.from">yield from</link>
      </entry>
     </row>
     <row>
      <entry>(n/a)</entry>
      <entry><literal>yield</literal></entry>
      <entry>
       <link linkend="control-structures.yield">yield</link>
      </entry>
     </row>
     <row>
      <entry>(n/a)</entry>
      <entry><literal>print</literal></entry>
      <entry><function>print</function></entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>and</literal></entry>
      <entry>
       <link linkend="language.operators.logical">logical</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>xor</literal></entry>
      <entry>
       <link linkend="language.operators.logical">logical</link>
      </entry>
     </row>
     <row>
      <entry>left</entry>
      <entry><literal>or</literal></entry>
      <entry>
       <link linkend="language.operators.logical">logical</link>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </para>
 <para>
  <example>
   <title>Associativity</title>
   <programlisting role="php">
<![CDATA[
<?php
$a = 3 * 3 % 5; // (3 * 3) % 5 = 4
var_dump($a);

$a = 1;
$b = 2;
$a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
var_dump($a, $b);
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  The ternary operator specifically requires the use of parenthesis to
  disambiguate precedence.
 </para>
 <para>
  <example>
   <title>Explicit Precedence</title>
   <programlisting role="php">
<![CDATA[
<?php
$a = true ? 0 : (true ? 1 : 2);
var_dump($a);

// this is not allowed since PHP 8
// $a = true ? 0 : true ? 1 : 2;
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  Operator precedence and associativity only determine how expressions
  are grouped, they do not specify an order of evaluation. PHP does not
  (in the general case) specify in which order an expression is evaluated
  and code that assumes a specific order of evaluation should be avoided,
  because the behavior can change between versions of PHP or depending on
  the surrounding code.
  <example>
   <title>Undefined order of evaluation</title>
   <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
$a = 1;
echo $a + $a++; // may print either 2 or 3

$i = 1;
$array[$i] = $i++; // may set either index 1 or 2
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><literal>+</literal>, <literal>-</literal> and <literal>.</literal> precedence</title>
   <programlisting role="php">
<![CDATA[
<?php
$x = 4;
// this line might result in unexpected output:
echo "x minus one equals " . $x-1 . ", or so I hope\n";

// the desired precedence can be enforced by using parentheses:
echo "x minus one equals " . ($x-1) . ", or so I hope\n";

// this is not allowed, and throws a TypeError:
echo (("x minus one equals " . $x) - 1) . ", or so I hope\n";
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
-1, or so I hope
-1, or so I hope
Fatal error: Uncaught TypeError: Unsupported operand types: string - int
]]>
   </screen>
  </example>
  <example>
   <title>Prior to PHP 8, <literal>+</literal>, <literal>-</literal> and <literal>.</literal> had the same precedence</title>
   <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
$x = 4;
// this line might result in unexpected output:
echo "x minus one equals " . $x-1 . ", or so I hope\n";

// because it is evaluated like this line (prior to PHP 8.0.0):
echo (("x minus one equals " . $x) - 1) . ", or so I hope\n";

// the desired precedence can be enforced by using parentheses:
echo "x minus one equals " . ($x-1) . ", or so I hope\n";
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
-1, or so I hope
-1, or so I hope
x minus one equals 3, or so I hope
]]>
   </screen>
  </example>
 </para>
 <note>
  <para>
   Although <literal>=</literal> has a lower precedence than
   most other operators, PHP will still allow expressions
   similar to the following: <literal>if (!$a = foo())</literal>,
   in which case the return value of <literal>foo()</literal> is
   put into <varname>$a</varname>.
  </para>
 </note>
 <sect2 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       String concatenation (<literal>.</literal>) now has a lower precedence than
       arithmetic addition/subtraction (<literal>+</literal> and <literal>-</literal>) and
       bitwise shift left/right (<literal>&lt;&lt;</literal> and <literal>&gt;&gt;</literal>);
       previously it had the same precedence as <literal>+</literal> and <literal>-</literal>
       and a higher precedence than <literal>&lt;&lt;</literal> and <literal>&gt;&gt;</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       The ternary operator (<literal>? :</literal>) is non-associative now;
       previously it was left-associative.
      </entry>
     </row>
     <row>
      <entry>7.4.0</entry>
      <entry>
       Relying on the precedence of string concatenation (<literal>.</literal>) relative to
       arithmetic addition/subtraction (<literal>+</literal> or <literal>-</literal>) or
       bitwise shift left/right (<literal>&lt;&lt;</literal> or <literal>&gt;&gt;</literal>),
       i.e. using them together in an unparenthesized expression, is deprecated.
      </entry>
     </row>
     <row>
      <entry>7.4.0</entry>
      <entry>
       Relying on left-associativity of the ternary operator (<literal>? :</literal>),
       i.e. nesting multiple unparenthesized ternary operators, is deprecated.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </sect2>
</sect1>