====== PHP RFC: Square bracket syntax for array destructuring assignment ======
  * Version: 1.0
  * Date: 2016-04-07
  * Authors: Andrea Faulds <ajf@ajf.me>, Bob Weinand <bwoebi@php.net>
  * Status: Implemented (PHP 7.1)
  * First Published at: http://wiki.php.net/rfc/short_list_syntax

===== Background =====

The fundamental complex data type in PHP is the [[http://php.net/manual/en/language.types.array.php|array]]. This data type is so frequently used that PHP has special syntax for handling it. This RFC focuses, in particular, on the syntax for two different array operations in PHP: construction of an array from values, and destructuring assignment from an array to variables.

Arrays can be constructed in PHP syntax using one of two syntax forms. The first of these, introduced in PHP 3, resembles a function call, where a series of comma-separated values (and optionally keys) is placed between <php>array(</php> and <php>)</php>:

<code php>
<?php

// Creates an array containing elements with the values 1, 2 and 3, and keys numbered from zero
$array = array(1, 2, 3);

// Creates an array containing elements with the values 1, 2 and 3, and the keys "a", "b", "c"
$array = array("a" => 1, "b" => 2, "c" => 3);
</code>

The second syntax form, the so-called [[rfc:shortsyntaxforarrays|short array syntax]] introduced in PHP 5.4, is a more concise form that replaces <php>array(</php> and <php>)</php> with <php>[</php> and <php>]</php>:

<code php>
<?php

// Creates an array containing elements with the values 1, 2 and 3, and keys numbered from zero
$array = [1, 2, 3];

// Creates an array containing elements with the values 1, 2 and 3, and the keys "a", "b", "c"
$array = ["a" => 1, "b" => 2, "c" => 3];
</code>

Beyond being more concise, this second syntax has the benefit of not resembling a function call (preventing misunderstandings from new users), and being familiar to users of other languages like JavaScript, which use similar syntax for constructing arrays.

Similar to the <php>array()</php> syntax for constructing arrays, PHP has had a syntax form for assigning to variables from array elements ("destructuring") since PHP 3, where a series of comma-separated variables are placed between <php>list(</php> and <php>)</php>:

<code php>
<?php

// Assigns to $a, $b and $c the values of their respective array elements in $array with keys numbered from zero
list($a, $b, $c) = $array;
</code>

As of the upcoming PHP 7.1, there will also be [[rfc:list_keys|a syntax form for specifying keys when destructuring]]:

<code php>
<?php

// Assigns to $a, $b and $c the values of the array elements in $array with the keys "a", "b" and "c", respectively
list("a" => $a, "b" => $b, "c" => $c) = $array;
</code>

However, while <php>array()</php> has the more concise counterpart syntax <php>[]</php>, there is currently no such counterpart for <php>list()</php>.

===== Proposal =====

This RFC proposes introducing a second syntax form for destructuring assignment, where <php>list(</php> and <php>)</php> are replaced with <php>[</php> and <php>]</php>:

<code php>
<?php

// Assigns to $a, $b and $c the values of their respective array elements in $array with keys numbered from zero
[$a, $b, $c] = $array;

// Assigns to $a, $b and $c the values of the array elements in $array with the keys "a", "b" and "c", respectively
["a" => $a, "b" => $b, "c" => $c] = $array;
</code>

This syntax is more concise, and like the <php>[]</php> alternative to <php>array()</php>, this new syntax does not resemble a function call.

Importantly, this syntax for destructuring an array means there is now symmetry between array construction and destructuring, which should make it clearer what the function of the syntax is:

<code php>
<?php

// The two lines in each of the following pairs are equivalent to each other

list($a, $b, $c) = array(1, 2, 3);
[$a, $b, $c] = [1, 2, 3];

list("a" => $a, "b" => $b, "c" => $c) = array("a" => 1, "b" => 2, "c" => 3);
["a" => $a, "b" => $b, "c" => $c] = ["a" => 1, "b" => 2, "c" => 3];

list($a, $b) = array($b, $a);
[$a, $b] = [$b, $a];
</code>

This symmetry between construction and destructuring is a feature in some other languages. The following code, for example, is valid ECMAScript 6, and would behave identically in PHP:

<code javascript>
// Creates an array
$array = [1, 2, 3];

// Extracts its elements into variables
[$a, $b, $c] = $array;
</code>

===== Details =====

The <php>list()</php> syntax is not only permitted on the left-hand side of an assignment operation, but also as variable in a <php>foreach</php> loop. The new <php>[]</php> syntax for destructuring would likewise be permitted here:

<code php>
<?php

foreach ($points as ["x" => $x, "y" => $y]) {
    var_dump($x, $y);
}
</code>

Both due to implementation issues, and for consistency's sake, <php>list()</php> cannot be nested inside <php>[]</php>, nor vice-versa:

<code php>
<?php

// This is not allowed:
list([$a, $b], [$c, $d]) = [[1, 2], [3, 4]];

// This is also not allowed:
[list($a, $b), list($c, $d)] = [[1, 2], [3, 4]];

// This, however, is allowed:
[[$a, $b], [$c, $d]] = [[1, 2], [3, 4]];
</code>

Aside from this restriction, assignment with <php>[]</php> on the left-hand side behaves identically to <php>list()</php> in all respects.

===== Backward Incompatible Changes =====

None.

===== Proposed PHP Version(s) =====

This is proposed for the next minor or major version of PHP, whichever comes first. At the time of writing, this would be PHP 7.1.

===== RFC Impact =====

This RFC has no impact upon OPcache or other extensions dealing with PHP opcodes, because the compiled result is identical to the <php>list()</php> syntax.

This RFC would, however, impact upon projects which try to parse PHP syntax or inspect the PHP interpreter's abstract syntax tree.

===== Open Issues =====

None.

===== Unaffected PHP Functionality =====

This RFC does not remove nor deprecate the existing <php>list()</php> syntax, and it continues to function identically.

===== Future Scope =====

We may wish to introduce destructuring assignment syntax for objects in future.

===== Vote =====

Because this proposal affects the language syntax (and also therefore the specification), it is a language change and requires at least a 2/3 majority to be accepted when put to a vote.

The vote will be a simple Yes/No vote on whether or not to accept the RFC for PHP 7.1 and merge the patch into master.

Voting started on 2016-04-27 and ended on 2016-05-08.

<doodle title="Accept the RFC Square bracket syntax for array destructuring assignment for PHP 7.1?" auth="ajf" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

There is a pull request, with tests, for the PHP interpreter (''php-src'') here: https://github.com/php/php-src/pull/1849

There is not yet a patch or pull request for the language specification (''php-langspec'').

===== Implementation =====
Merged into master for PHP 7.1: http://git.php.net/?p=php-src.git;a=commitdiff;h=4f077aee836ad7d8335cf62629a8364bdf939db9

Not yet in the language specification.

After the project is implemented, this section should contain 
  - a link to the PHP manual entry for the feature

===== References =====
  * Nikita Popov's [[rfc:abstract_syntax_tree|Abstract Syntax Tree RFC]], which was accepted into PHP 7, noted that a short list syntax like this would not be possible without having the abstract syntax tree

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.