<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<sect2 xml:id="migration70.incompatible.variable-handling">
 <title>Changes to variable handling</title>

 <para>
  PHP 7 now uses an abstract syntax tree when parsing source files. This has
  permitted many improvements to the language which were previously
  impossible due to limitations in the parser used in earlier versions of
  PHP, but has resulted in the removal of a few special cases for consistency
  reasons, which has resulted in backward compatibility breaks. These cases
  are detailed in this section.
 </para>

 <sect3 xml:id="migration70.incompatible.variable-handling.indirect">
  <title>
   Changes to the handling of indirect variables, properties, and methods
  </title>

  <para>
   Indirect access to variables, properties, and methods will now be
   evaluated strictly in left-to-right order, as opposed to the previous mix
   of special cases. The table below shows how the order of evaluation has
   changed.
  </para>

  <para>
   <table>
    <title>Old and new evaluation of indirect expressions</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Expression</entry>
       <entry>PHP 5 interpretation</entry>
       <entry>PHP 7 interpretation</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>
        <code>$$foo['bar']['baz']</code>
       </entry>
       <entry>
        <code>${$foo['bar']['baz']}</code>
       </entry>
       <entry>
        <code>($$foo)['bar']['baz']</code>
       </entry>
      </row>
      <row>
       <entry>
        <code>$foo-&gt;$bar['baz']</code>
       </entry>
       <entry>
        <code>$foo-&gt;{$bar['baz']}</code>
       </entry>
       <entry>
        <code>($foo-&gt;$bar)['baz']</code>
       </entry>
      </row>
      <row>
       <entry>
        <code>$foo-&gt;$bar['baz']()</code>
       </entry>
       <entry>
        <code>$foo-&gt;{$bar['baz']}()</code>
       </entry>
       <entry>
        <code>($foo-&gt;$bar)['baz']()</code>
       </entry>
      </row>
      <row>
       <entry>
        <code>Foo::$bar['baz']()</code>
       </entry>
       <entry>
        <code>Foo::{$bar['baz']}()</code>
       </entry>
       <entry>
        <code>(Foo::$bar)['baz']()</code>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>

  <para>
   Code that used the old right-to-left evaluation order must be rewritten to
   explicitly use that evaluation order with curly braces (see the above
   middle column). This will make the code both forwards compatible with PHP
   7.x and backwards compatible with PHP 5.x.
  </para>

  <para>
   This also affects the &global; keyword. The curly brace syntax can be
   used to emulate the previous behaviour if required:
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
function f() {
    // Valid in PHP 5 only.
    global $$foo->bar;

    // Valid in PHP 5 and 7.
    global ${$foo->bar};
}
?>
]]>
   </programlisting>
  </informalexample>
 </sect3>

 <sect3 xml:id="migration70.incompatible.variable-handling.list">
  <title>Changes to <function>list</function> handling</title>

  <sect4 xml:id="migration70.incompatible.variable-handling.list.order">
   <title>
    <function>list</function> no longer assigns variables in reverse order
   </title>

   <para>
    <function>list</function> will now assign values to variables in the
    order they are defined, rather than reverse order. In general, this only
    affects the case where <function>list</function> is being used in
    conjunction with the array <code>[]</code> operator, as shown below:
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
list($a[], $a[], $a[]) = [1, 2, 3];
var_dump($a);
?>
]]>
    </programlisting>
    &example.outputs.5;
    <screen>
<![CDATA[
array(3) {
  [0]=>
  int(3)
  [1]=>
  int(2)
  [2]=>
  int(1)
}
]]>
    </screen>
    &example.outputs.7;
    <screen>
<![CDATA[
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}
]]>
    </screen>
   </informalexample>

   <para>
    In general, it is recommended not to rely on the order in which
    <function>list</function> assignments occur, as this is an implementation
    detail that may change again in the future.
   </para>
  </sect4>

  <sect4 xml:id="migration70.incompatible.variable-handling.list.empty">
   <title>Empty <function>list</function> assignments have been removed</title>

   <para>
    <function>list</function> constructs can no longer be empty. The following
    are no longer allowed:
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
list() = $a;
list(,,) = $a;
list($x, list(), $y) = $a;
?>
]]>
    </programlisting>
   </informalexample>
  </sect4>

  <sect4 xml:id="migration70.incompatible.variable-handling.list.string">
   <title><function>list</function> cannot unpack <type>string</type>s</title>

   <para>
    <function>list</function> can no longer unpack <type>string</type>
    variables. <function>str_split</function> should be used instead.
   </para>
  </sect4>
 </sect3>

 <sect3 xml:id="migration70.incompatible.variable-handling.array-order">
  <title>
   Array ordering when elements are automatically created during by reference
   assignments has changed
  </title>

  <para>
   The order of the elements in an array has changed when those elements have
   been automatically created by referencing them in a by reference
   assignment. For example:
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$array = [];
$array["a"] =& $array["b"];
$array["b"] = 1;
var_dump($array);
?>
]]>
   </programlisting>
   &example.outputs.5;
   <screen>
<![CDATA[
array(2) {
  ["b"]=>
  &int(1)
  ["a"]=>
  &int(1)
}
]]>
   </screen>
   &example.outputs.7;
   <screen>
<![CDATA[
array(2) {
  ["a"]=>
  &int(1)
  ["b"]=>
  &int(1)
}
]]>
   </screen>
  </informalexample>
 </sect3>

 <sect3 xml:id="migration70.incompatible.variable-handling.parentheses">
  <title>
   Parentheses around function arguments no longer affect behaviour
  </title>

  <para>
   In PHP 5, using redundant parentheses around a function argument could
   quiet strict standards warnings when the function argument was passed by
   reference. The warning will now always be issued.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
function getArray() {
    return [1, 2, 3];
}

function squareArray(array &$a) {
    foreach ($a as &$v) {
        $v **= 2;
    }
}

// Generates a warning in PHP 7.
squareArray((getArray()));
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Notice: Only variables should be passed by reference in /tmp/test.php on line 13
]]>
   </screen>
  </informalexample>
 </sect3>
</sect2>

<!-- 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:"~/.phpdoc/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
-->