list() syntax

Discussed at #3456119: Coding Standards Meeting Tuesday 2024-06-18 2100 UTC → and there was agreement that this is something to pursue. I have updated the IS with the new template.

I propose using the following syntax, and explicitly encouraging (or even requiring) [] over list():

[$country, $state, $city] = $this->getPlaceInfo();
[$country] = $this->getPlaceInfo();
[, , $city] = $this->getPlaceInfo();
['city' => $city] = $this->getPlaceInfoAssociative();

That looks like what needs to be on the left side of the assignment. But I think we should have a simpler example, the current suggestion expects the reader to know what $this->getPlaceInfo() and $this->getPlaceInfoAssociative(). And I would like to have an example that is inclusive regardless of where people live or work.

What about using stars?

$stars = ['blue', 'yellow', 'red'];

[$hottest, $hotter, $coldest] = $stars;
[$hottest] = $stars;
[, , $coldest] = $stars;

I'm happy to second quietone's example since it's understandable for people who may have never seen this syntax (you can see $stars is an array).

I initially wasn't sure about not have a space before the first command (proposed [, , $foo] vs my brain's [ , , $foo]) but after writing them out and trying to change them, the proposed spaceless first comma is closest to how it would look if there was a variable, since in that case there would be a variable there and not space. So you can go from [, , $foo] to [$bar, , $foo] without having to remove any characters. That makes sense to me.

I fully agree with #11, I think that example makes sense.

Thanks. I updated the Issue summary with the 'stars' example. I also modified the text a) so it only shows what to do b) uses similar language to the php manual page for lists and c) remove parentheses around characters to be consistent with the coding standards page.

I did some testing.

No errors on these lines:

    list(, , $coldest) = $stars;
    [$hottest, $hotter, $coldest] = $stars;
    [, , $coldest] = $stars;

[ $hottest] = $stars; ERROR | [x] There should be no white space after an opening "["
[ , , $coldest ] = $stars; ERROR | [x] There should be no white space after an opening "[" and ERROR | [x] There should be no white space before a closing "]"

So, perhaps the sniff just needs to detect 'list(.*)'?

Dated as per #1539738-11: Define and document a policy on list() syntax →

Does this now need to cover the shorthand array destructuring syntax?

Thanks, @quietone, I agree that doing this without an invented method makes more sense.
The new example just has the slight downside that it doesn’t include an example for destructuring an associative array.
Do you think just adding `[1 => $hotter] = $stars;` would help, maybe preceded by a comment explaining that this is how you’d destructure an associative array? Or do we add a second, associative array? (Or is the majority against adding an example for associative destructuring?)

Does this now need to cover the shorthand array destructuring syntax?

Could you please elaborate, what syntax do you mean?

Extra examples are usually beneficial so I added that. I don't think it necessary to do more because the style and spacing doesn't change.

I mean:

$array = ['foo', 'bar'];

[$foo, $bar] = $array;

See https://stitcher.io/blog/array-destructuring-with-list-in-php