The Art of Immutable Array Updates Using Functional PHP

To achieve immutable array updates in PHP, it must be done by creating a new array instead of modifying the original array. 1. Avoid directly modifying the array elements. You should use array_merge() or manually copy to generate a new array; 2. Use array_merge() to perform concise immutable updates, keeping the original array unchanged and supporting the addition of new keys; 3. Use pure functions such as recursive setIn() for nested arrays to ensure that there are no side effects when the deep structure is updated; 4. Combine functional tools such as array_map and array_filter to achieve side effects without side effects; 5. Strengthen immutability through conventions, such as treating the input array as read-only, returning a new array, encapsulating data using PHP 8.2 readonly class or DTO of PHP 8.2. This approach improves the predictability, maintainability and testability of the code, ultimately achieving safer state management.

Immutable array updates in PHP might sound like a concept borrowed from functional programming languages like Haskell or Elm, but you can apply the same principles effectively even in PHP—especially as the language matures with features supporting functional patterns.

The core idea is simple: instead of modifying an array in place, you create a new array that includes the desired changes, leaving the original untouched. This leads to more predictable code, easier debugging, and fewer side effects—especially valuable in larger applications or when working with state in a functional style.

Here's how to master immutable array updates in PHP using functional techniques.

1. Avoid Modifying Arrays In Place

In traditional PHP, you might do something like:

 $user = ['name' => 'Alice', 'age' => 30];
$user['age'] = 31; // Mutation!

This mutates the original array. Instead, create a new version:

 $user = ['name' => 'Alice', 'age' => 30];
$newUser = ['name' => $user['name'], 'age' => $user['age'] 1];

Now $user remains unchanged, and $newUser reflects the update.

But manually copying keys gets tedious. Use the spread-like behavior of or array_merge() .

2. Use array_merge() for Clean Immutable Updates

array_merge() is your go-to tool for creating updated copies:

 $user = ['name' => 'Alice', 'age' => 30];
$updatedUser = array_merge($user, ['age' => 31]);

This returns a new array. The original $user is untouched.

You can also add new keys:

 $extendedUser = array_merge($user, ['active' => true]);

Important: array_merge() only works reasonably with indexed or associated arrays, not complex nested structures unless handled recursively.

3. Handle Nested Updates with Pure Functions

For nested arrays, immutability requires deeper care. Don't do this:

 $data['user']['profile']['theme'] = 'dark'; // Mutation!

Instead, build a pure function to return a new structure:

 function withUpdatedTheme(array $data, string $theme): array
{
    return array_merge($data, [
        'user' => array_merge($data['user'], [
            'profile' => array_merge($data['user']['profile'], [
                'theme' => $theme
            ])
        ])
    ]);
}

Usage:

 $newData = withUpdatedTheme($data, 'dark');

Now $data is preserved, and changes are encapsulated in a reusable, testable function.

For deeply nested data, consider writing a generic setIn() function:

 function setIn(array $array, array $path, $value): array
{
    $result = $array;
    $cursor = &$result;

    foreach ($path as $key) {
        if (!is_array($cursor)) {
            $cursor = [];
        }
        $cursor = &$cursor[$key];
    }

    $cursor = $value;

    return $result;
}

Wait—this uses references and mutates $result . Not pure.

Here's a truly immutable version:

 function setIn(array $array, array $path, $value): array
{
    if (empty($path)) {
        return $array;
    }

    $key = array_shift($path);
    if (!empty($path)) {
        $nested = $array[$key] ?? [];
        if (!is_array($nested)) {
            $nested = [];
        }
        $array[$key] = setIn($nested, $path, $value);
    } else {
        $array[$key] = $value;
    }

    return $array;
}

Now you can do:

 $newData = setIn($data, ['user', 'profile', 'theme'], 'dark');

And $data remains unchanged.

4. Combine with Functional Helpers

To make this style more expressive, pair immutable updates with functional helpers.

For example, map over arrays without mutation:

 $users = [['name' => 'Alice', 'age' => 30], ['name' => 'Bob', 'age' => 25]];

$usersAgedUp = array_map(
    fn($user) => array_merge($user, ['age' => $user['age'] 1]),
    $users
);

Or filter:

 $activeUsers = array_filter($users, fn($user) => $user['active'] ?? false);

These don't alter the original $users array—pure and predictable.

5. Embrace Immutability by Convention

PHP doesn't enforce immutability, so discipline matters. Tips:

• Treat arrays passed into functions as read-only.
• Return new arrays instead of modifying inputs.
• Use readonly classes (PHP 8.2) when modeling data structures.
• Consider using value objects or DTOs for complex data.

Example with a readonly class:

 readonly class User
{
    public function __construct(
        public string $name,
        public int $age
    ) {}
}

function withAgeIncreased(User $user, int $by = 1): User
{
    return new User($user->name, $user->age $by);
}

Now immutability is enforced at the object level.

Immutable array updates in PHP aren't automatic, but with array_merge() , pure functions, and functional thinking, you can write safer, more maintained code. It's not about copying everything—it's about control, clarity, and avoiding unintended consequences.

Basically, if you treat data as if it can't be changed, you'll write better PHP.

The above is the detailed content of The Art of Immutable Array Updates Using Functional PHP. For more information, please follow other related articles on the PHP Chinese website!