Array Destructuring ([] = …)
debt(d3/e1/b1/t5)
Closest to 'default linter catches the common case' (d3). The detection_hints list rector and php-cs-fixer, both of which can automatically detect manual indexed access patterns ($a = $arr[0]; $b = $arr[1]) that could be replaced with destructuring syntax. These are standard PHP toolchain tools, not specialist SAST tools, so d3 fits well.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix is literally replacing manual index assignments with [$a, $b] = $array or ['key' => $val] = $array — a direct syntactic swap that touches one line or a small cluster of lines. Rector can even automate this transformation.
Closest to 'minimal commitment' (b1). Array destructuring is a local syntactic choice — it's pure syntax sugar for variable assignment. It doesn't impose any architectural weight or structural commitment on the codebase. Each usage is self-contained and trivially reversible. Tags confirm it's a syntax-level concern.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field states that developers believe destructuring only works with indexed arrays, when in fact PHP 7.1+ supports key-based destructuring in any order. This is a genuine surprise for developers coming from other languages (e.g. JavaScript) where destructuring objects vs arrays works differently. Additionally, common_mistakes include not checking for expected keys (leading to undefined index notices) and not knowing about skipping elements with placeholders. These are non-obvious behaviors that competent developers will guess wrong about initially.
Also Known As
TL;DR
Explanation
Array destructuring (PHP 7.1+) uses [] = syntax as shorthand for the older list() = form. Both positional and key-based forms are supported: [$first, $second] = $arr and ['name' => $name, 'age' => $age] = $row. Elements can be skipped: [, $second] = $pair. Particularly readable in foreach: foreach ($rows as ['id' => $id, 'email' => $email]). PHP 8.1 added support for destructuring in more contexts. The feature improves readability over multiple explicit index accesses and makes tuple-style returns from functions practical.
Common Misconception
Why It Matters
Common Mistakes
- Using list() or [] destructuring without checking that the array has the expected keys first — undefined index notices on missing keys.
- Destructuring numerically-indexed arrays by position when the array structure may change — use named keys instead.
- Not using the short [] syntax (PHP 7.1+) when list() is only being used for clarity — both work but [] is preferred.
- Ignoring values with a placeholder: [$first, , $third] is valid and clearer than skipping the index check.
Code Examples
// Fragile index-based access instead of destructuring:
$coords = getCoordinates();
$lat = $coords[0]; // What's index 0?
$lon = $coords[1];
// Better:
['lat' => $lat, 'lon' => $lon] = getCoordinates();// Key-based in a loop
foreach ($users as ['id' => $id, 'email' => $email]) {
sendNotification($id, $email);
}