PHP Array Unpacking and String-Keyed Arrays

PHP provides several ways to combine arrays, but one of the cleanest is array unpacking using the spread operator (...).

Array unpacking lets you insert the elements of an existing array into a new array without writing each element individually.

In this guide, you'll learn how array unpacking works with numeric and string keys, what happens when keys are duplicated, and how it compares with other PHP array operations.

What Is Array Unpacking in PHP?

Array unpacking uses three dots (...) to expand the elements of an array into another array.

For example:

<?php

$colors = ["Red", "Green"];

$allColors = [
    ...$colors,
    "Blue"
];

print_r($allColors);

Output:

Array
(
    [0] => Red
    [1] => Green
    [2] => Blue
)

The spread operator inserts the elements of $colors into the new array, followed by "Blue".

Array unpacking was introduced in PHP 7.4 for integer-keyed arrays. Support for string-keyed arrays was added in PHP 8.1.

Combining Multiple Indexed Arrays

You can use the spread operator more than once to combine multiple arrays.

<?php

$frontend = ["HTML", "CSS"];

$backend = ["PHP", "Python"];

$languages = [
    ...$frontend,
    ...$backend
];

print_r($languages);

Output:

Array
(
    [0] => HTML
    [1] => CSS
    [2] => PHP
    [3] => Python
)

PHP creates a new array containing the elements from both source arrays.

For numeric keys, unpacking appends the values and assigns new sequential integer keys, beginning at zero in a new empty array.

This means the original numeric keys are not preserved.

Unpacking String-Keyed Arrays

An associative array uses named keys instead of only numeric indexes.

Starting with PHP 8.1, you can unpack associative arrays directly.

<?php

$basicSettings = [
    "theme" => "light",
    "language" => "en"
];

$extraSettings = [
    "timezone" => "UTC"
];

$settings = [
    ...$basicSettings,
    ...$extraSettings
];

print_r($settings);

Output:

Array
(
    [theme] => light
    [language] => en
    [timezone] => UTC
)

Unlike numeric keys, string keys are preserved when arrays are unpacked.

This makes the spread operator useful for combining configuration values, application settings, and structured records.

What Happens with Duplicate String Keys?

When two unpacked arrays contain the same string key, the later value replaces the earlier value.

For example:

<?php

$defaults = [
    "theme" => "light",
    "itemsPerPage" => 10
];

$custom = [
    "theme" => "dark"
];

$settings = [
    ...$defaults,
    ...$custom
];

print_r($settings);

Output:

Array
(
    [theme] => dark
    [itemsPerPage] => 10
)

Because $custom appears after $defaults, its theme value takes precedence.

This is useful when an application has default settings that users or administrators can override.

Remember that unpacking does not recursively merge nested arrays. If the same string key contains an array in both sources, the later array replaces the earlier one.

Array Unpacking vs array_merge() vs the + Operator

PHP provides several ways to combine arrays, but they don't all behave the same way.

The array union operator (+) preserves values from the left-hand array when keys overlap.

<?php

$defaults = ["theme" => "light"];
$custom = ["theme" => "dark"];

$merged = [...$defaults, ...$custom];

$union = $defaults + $custom;

echo $merged["theme"] . PHP_EOL;
echo $union["theme"];

Output:

dark
light

Choose the operation based on which values should have priority, not just which syntax looks shorter.

Practical Example: Building Application Settings

Let's create a simple configuration system that combines default settings, environment settings, and user preferences.

Create a file named settings.php:

<?php

declare(strict_types=1);

// Default application settings.

$defaults = [
    "theme" => "light",
    "language" => "en",
    "itemsPerPage" => 10
];

// Settings for the current environment.

$environment = [
    "itemsPerPage" => 25
];

// User preferences.

$userPreferences = [
    "theme" => "dark"
];

// Combine settings in priority order.

$settings = [
    ...$defaults,
    ...$environment,
    ...$userPreferences
];

// Display the final configuration.

foreach ($settings as $key => $value) {

    echo "<p>" . htmlspecialchars(
        $key . ": " . (string) $value,
        ENT_QUOTES,
        "UTF-8"
    ) . "</p>";
}

Browser output:

theme: dark
language: en
itemsPerPage: 25

The final settings follow a clear priority:

• Default values are added first.
• Environment settings override matching defaults.
• User preferences override earlier values when their keys match.

The example uses predefined arrays. In a real application, validate configuration values received from users or external sources before applying them.

Common Mistakes

Key Takeaways

• Use the spread operator (...) to unpack arrays.
• PHP 7.4 introduced array unpacking for integer-keyed arrays.
• PHP 8.1 added support for string-keyed arrays.
• Numeric keys are reindexed when values are unpacked.
• Duplicate string keys use the value from the later array.
• array_merge() and the array union operator provide alternative merging behavior.
• Array unpacking is useful for combining lists and overriding configuration settings.

PHP array unpacking provides a readable way to combine arrays without unnecessary loops. Understanding how numeric and string keys behave helps you avoid unexpected results and choose the appropriate approach for structured data.