Spread Operator

PHP introduced the spread operator in version 7.4 to enable you to merge arrays, pass a list of arguments to a function, or unpack data from a specific object.

In this article, you will learn how to use the PHP spread operator with arrays, functions, and traversable objects. By the end, you will be able to use this syntax in your code as needed.

What is the PHP Spread Operator? 

The spread operator was introduced in PHP 7.4 and is also called the splat operator. It helps you unpack elements in arrays and iterables and spread them into individual pieces. You can write it using three dots ( … ) before the array variable.

Here is its syntax:

...ARRAY

That means, you can merge or expand an array inside another array. It takes the elements of an array and spreads them out as individual values.

This method saves time compared to using complicated code, such as combining arrays with the array_merge function or using loops.

Here is a quick example:

$newArray = [...$array1, ...$array2];

Let’s move on to the following sections to see examples of how to expand and merge arrays within one another.

Merging and Expanding Arrays Using the PHP Spread Syntax

In the following example, we will take an array and expand its elements into another one.

$array = [1, 2, 3]; 
$newArray = [...$array, 4, 5, 6];

The $newArray will contain all elements of the $array alongside the values 4, 5, and 6. Its output would be like this:

[1, 2, 3, 4, 5, 6]

Instead of using extra lines of code to perform a merging operation, you can use the spread operator for this task. Here is an example:

$array1 = [0, 100, 56];
$array2 = [41, 200, 96];
$mergedArray = [...$array1, ...$array2];

Here, the $mergedArray will take all elements of $array1 and $array2 and then create a new array with both. Its output will be:

[0, 100, 56, 41, 200, 96]

Anyway, let’s move on to the section below to understand why we cannot use the spread operator with objects in PHP.

Why Objects Cannot Use the Spread Syntax in PHP?

PHP does not support the direct use of the spread operator with objects. Let’s see what happens if we try to use the spread operator with objects.

class Machine {
    public $ram = "8GB";
    public $screen = "30 Inch";
    protected function play() {
      echo "Welcome to FlatCoding Tutorials";
   }
}

$computer = new Machine();
$laptop = ["Touchable Mouse", "On Keyboard"];

$combine = [...$computer, ...$laptop]; // Cannot unpack an object of class Machine
print_r($combine);

This will produce a fatal error. Here is the output:

Fatal error: Uncaught TypeError: Only arrays and Traversables can be unpacked in /test/index.php:10

So why are we not able to use objects with the spread operator in PHP?

Objects in PHP have access modifiers such as public, protected, and private. If PHP allowed the spread operator to unpack objects, it would violate encapsulation by unintentionally exposing protected and private properties.

Objects are not just collections; they may have methods, behaviour, and an internal state.

But, you can use the spread operator with objects indirectly.

You could use the get_object_vars function. This would turn the object into an array that will be proper for unpacking as needed. Let’s see how we can do that:

class Machine {
    public $ram = "8GB";
    public $screen = "30 Inch";
    protected function play() {
      echo "Welcome to FlatCoding Tutorials";
   }
}

$computer = get_object_vars(new Machine());
$laptop = ["Touchable Mouse", "On Keyboard"];

$combine = [...$computer, ...$laptop]; // Cannot unpack an object of class Machine
print_r($combine);

Here is the output:

Array
(
    [ram] => 8GB
    [screen] => 30 Inch
    [0] => Touchable Mouse
    [1] => On Keyboard
)

As you saw in the fatal error, only arrays and traversables can be unpacked with the spread operator. Let’s see how we can do that in the section below.

How to Use Traversable Objects Within Spread Operator in PHP?

The class should implement the traversable interface. You can do that by implementing the Iterator or IteratorAggregate interface.

Here is an example:

class Numbers implements IteratorAggregate {
    private $numbers;

    public function __construct(...$numbers) {
        $this->numbers = $numbers;
    }

    public function getIterator(): Traversable {
        return new ArrayIterator($this->numbers);
    }
}

$numbers = new Numbers(1, 2, 3, 4, 5);
$array = [...$numbers];

print_r($array);

You can also use #[\ReturnTypeWillChange] instead of “Traversable” keyword to be like this:

class Numbers implements IteratorAggregate {
    private $numbers;

    public function __construct(...$numbers) {
        $this->numbers = $numbers;
    }
    
    #[\ReturnTypeWillChange]
    public function getIterator(){
        return new ArrayIterator($this->numbers);
    }
}

$numbers = new Numbers(1, 2, 3, 4, 5);
$array = [...$numbers];

print_r($array);

The output:

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

In the following section, you will learn how to pass arguments with spread operator in PHP. 

Passing Multiple Arguments With the PHP Spread Operator

You can pass an array as arguments to a function. This will extract the array elements and spread them into the function arguments.

Here is an example:

function greet($name1, $name2, $name3) {
    echo "Hello, $name1, $name2, and $name3!";
}

$names = ['Alice', 'Bob', 'Charlie'];
greet(...$names);

The output:

Hello, Alice, Bob, and Charlie!

The function greet expects three arguments. PHP enables you to pass the three arguments through an array, which should have three elements equivalent to the number of arguments in the function.

You can not use the spread operator with flag (&) reference in PHP. Let’s move on to the section below to see how it works.

References Within the Spread Syntax

You are not allowed to use the & flag of reference within the array directly. So, this [...&$array, 4, 5] will cause an error. Here is an example:

Parse error: syntax error, unexpected token "&" in index.php

The PHP spread operator can work with a reference through a middle variable, but that will not affect the original array. Here is an example:

$origin_array = [1, 2, 3]; 
$ref =& $origin_array; 
$newArray = [...$ref, 4, 5];
print_r($origin_array);
print_r($newArray);

The output:

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

In the following section, you will learn how to use type hinting alongside the spread operator.

How to Use Type Hinting Within the PHP Spread Syntax

The PHP spread operator became compatible with type hinting, which allows a function to expect only a specific data type alongside (...).

Here is an example:

function addNumbers(int ...$numbers) { 
  return array_sum($numbers); 
} 
$nums = [1, 2, 3, 4]; 
echo addNumbers(...$nums);

The output: 10.

Wrapping Up

PHP spread syntax is an operator used to unpack elements of an array into other inputs, such as function arguments or another array.

You can’t use the spread operator with objects in PHP.