The Splat Operator In PHP

The PHP splat operator (...) has been available in PHP since version 5.6. When it was introduced I made note of it but have never really used it, so I thought it might be interesting to explore it a little.

Internally, the ellipsis operator in PHP is called T_ELLIPSIS, although I have heard a few different names for the operator in the past. This includes names like:

• Ellipsis
• Unpacking operator.
• Packing operator.
• Three dots operator
• Spread operator
• Splat operator

Personally, I think the splat is the correct name for this operator, so I'll be using that from now on.

As some of the names suggest, the splat operator can be used to unpack parameters to functions or to combine variables into an array. If you have seen this operator in JavaScript then it is usually called the spread operator and it works in a very similar way. Let's run through some examples of how it works in PHP land.

Take the following function, this takes two parameters and adds them together, returning the output.

function addNumbers($number1, $number2) {
  return $number1 + $number2;
}

Now, take the following array of numbers.

$numbersArray = [1, 2];

To add these numbers together using the above function we could call the function in a variety of different ways. The splat operator allows us to send the array to the function and it will be unpacked into separate variables.

We can call the function using the splat operator like this.

echo addNumbers(...$numbersArray);

This prints out '3'. The two numbers in the array are sent to the function as separate parameters and the function adds them together.

It is also possible to use the splat operator to create functions with a variable number of parameters. By adding the operator to the function declaration we are essentially saying that the function can receive a variable number of inputs, so the function should be set up accordingly to process multiple items.

The following function will take different amounts of numbers and add them together.

function addNumbers(...$numbers) {
  $sum = 0;
  foreach ($numbers as $number) {
    $sum += $number;
  }
  return $sum;
}

This is called in the following way.

echo addNumbers(1, 2, 3, 4, 5);

The output of this code is "15" as each parameter is sent to the function as an array and the numbers are all added together. We can add as many parameters to this function as we want, they will be turned into a single array once inside the function.

It is also possible to use type hinting in order to ensure that we are only receiving an array of items that are all the same type.

Take this very simple class, this has a single property that we set via the constructor.

class Thing {
  public $value;
  public function __construct($value) {
    $this->value = $value;
  }
}

We can ensure that our function can only accept one or more Thing objects by using a type hint in front of the splat operator, like this.

function addThings(Thing ...$things) {
  $sum = 0;
  foreach ($things as $thing) {
    $sum += $thing->value;
  }
  return $sum;
}

With this in place we can use the function in the following way.

$thing1 = new Thing(1);
$thing2 = new Thing(2);

echo addThings($thing1, $thing2);

If we pass any other type variable to the function it will throw an exception.

Finally, since PHP 7.4 it is also possible to run a kind of array merge operation using the splat operator. The following example creates an array and then merges it into the start of a second array.

$numbers1 = [1, 2, 3];
$numbers2 = [...$numbers1, 4, 5, 6];
print_r($numbers2);

This prints out the following.

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
    [5] => 6
)

I was trying to think why I hadn't really seen this operator much in my professional PHP work and it's probably because it's not used much in Drupal. Searching through source code I have locally showed that it is used in applications like Deployer, where a variable number of hostnames might be passed to a function. The splat operator is used to pack those host names into a single array. I can see it being used heavily in the JavaScript world. In fact, the array merge use of the splat operator is something that already happens in JavaScript so I can see why this was added.