# RFC: Spread Operator in Array Expression

- Status: Implemented (PHP 7.4)
- Authors: CHU Zhaowei, jhdxr@php.net
- Date: 2018-10-13
- Version: 0.2
- Original: https://wiki.php.net/rfc/spread_operator_for_array
- Page: https://externals.io/rfc/spread_operator_for_array
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Support spread operator for array definition in PHP 7.4? (closed)

Yes: 43 · No: 1

Voters: ashnazg (Yes), bishop (Yes), carusogabriel (Yes), colinodell (Yes), cpriest (Yes), dams (Yes), danack (Yes), didou (Yes), diegopires (Yes), duncan3dc (Yes), emir (Yes), galvao (Yes), guilhermeblanco (Yes), jasny (Yes), jhdxr (Yes), jwage (Yes), kalle (Yes), kguest (Yes), kinncj (Yes), levim (Yes), lstrojny (Yes), malukenho (Yes), marcio (Yes), mariano (Yes), mcmic (Yes), mike (Yes), nikic (Yes), ocramius (Yes), patrickallaert (Yes), petk (Yes), pmmaga (Yes), pollita (Yes), reywob (Yes), royopa (Yes), rtheunissen (Yes), salathe (No), santiagolizardo (Yes), sergey (Yes), svpernova09 (Yes), thekid (Yes), trowski (Yes), weierophinney (Yes), yunosh (Yes), zimt (Yes)

## Discussions on the mailing list

- [\[RFC\] Spread Operator in Array Expression](https://externals.io/message/103452.md) — started on 2018-11-19, 8 messages
- [\[RFC\] Spread Operator in Array Expression v0.2](https://externals.io/message/105072.md) — started on 2019-04-04, 20 messages
- [\[RFC\]\[VOTE\] Spread Operator in Array Expression v0.2](https://externals.io/message/105325.md) — started on 2019-04-21, 4 messages
- [Suggestion: Inconsistency: Allow array spread operator to work on string keys](https://externals.io/message/112378.md) — started on 2020-12-02, 6 messages

---

## Introduction

PHP has already supported [argument unpacking](https://externals.io/rfc/argument_unpacking) (AKA spread operator) since 5.6. This RFC proposes to bring this feature to array expression.

## Proposal

An array pair prefixed by `...` will be expanded in places during array definition. Only arrays and objects who implement Traversable can be expanded.

For example,

```php
$parts = ['apple', 'pear'];
$fruits = ['banana', 'orange', ...$parts, 'watermelon'];
// ['banana', 'orange', 'apple', 'pear', 'watermelon'];
```

It's possible to do the expansion multiple times, and unlike argument unpacking, `...` can be used anywhere. It's possible to add normal elements before or after the spread operator.

Spread operator works for both array syntax(`array()`) and short syntax(`[]`).

It's also possible to unpack array returned by a function immediately.

```php
$arr1 = [1, 2, 3];
$arr2 = [...$arr1]; //[1, 2, 3]
$arr3 = [0, ...$arr1]; //[0, 1, 2, 3]
$arr4 = array(...$arr1, ...$arr2, 111); //[1, 2, 3, 1, 2, 3, 111]
$arr5 = [...$arr1, ...$arr1]; //[1, 2, 3, 1, 2, 3]
 
function getArr() {
  return ['a', 'b'];
}
$arr6 = [...getArr(), 'c']; //['a', 'b', 'c']
 
$arr7 = [...new ArrayIterator(['a', 'b', 'c'])]; //['a', 'b', 'c']
 
function arrGen() {
	for($i = 11; $i < 15; $i++) {
		yield $i;
	}
}
$arr8 = [...arrGen()]; //[11, 12, 13, 14]
```

### String keys

In order to make the behavior consistent with [argument unpacking](https://externals.io/rfc/argument_unpacking), string keys are not supported. A recoverable error will be thrown once a string key is encountered.

### By-reference passing

It's not possible to unpack an array by reference.

```php
$arr1 = [1, 2, 3];
$arr2 = [...&$arr1]; //invalid syntax
```

However, if elements in the array to be unpacked are stored by reference, they will be stored by reference in the new array as well.

```php
$one = 1;
$arr1 = [&$one, 2, 3];
$arr2 = [0, ...$arr1];
var_dump($arr2);
/*
array(4) {
  [0]=>
  int(0)
  [1]=>
  &int(1)
  [2]=>
  int(2)
  [3]=>
  int(3)
}
*/
```

## Backward Incompatible Changes

This change should not break anything.

## Q &amp; A

### Advantages over array\_merge

1. Spread operator should have a better performance than `array_merge`. It's because not only that spread operator is a language structure while `array_merge` is a function call, but also compile time optimization can be performant for constant arrays.
2. `array_merge` only supports array, while spread operator also supports objects implementing `Traversable`.

```php
// Before
array_merge(iterator_to_array($iter1), iterator_to_array($iter2))
 
// Or to generalize to all iterables
array_merge(
  is_array($iter1) ? $iter1 : iterator_to_array($iter1),
  is_array($iter2) ? $iter2 : iterator_to_array($iter2)
)
 
// After (handles both cases)
[ ...$iter1, ...$iter2 ]
 
//Thanks Rowan for providing this example
```

### ... should be preserved for other use (e.g. map concat)

This is kind of out of scope here to discuss other concat / merge operation. The important thing is we should make the behavior of same operator consistent and not to confuse userland developer. It's also why I changed the behavior for string keys in this revised version.

## Proposed PHP Version(s)

next PHP 7.x, likely 7.4

## RFC Impact

### To Opcache

Some changes in opcache to support the new opcode is needed.

## Vote

Voting started 2019-04-22 and ends 2019-05-06. A 2/3 majority is required.

**Vote: Support spread operator for array definition in PHP 7.4?** — Yes: 43 · No: 1 (closed)

## Patches and Tests

WIP

<https://github.com/php/php-src/pull/3640>

## Implementation

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

## References

Links to external references, discussions or RFCs

## Rejected Features

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