Array functions

What it is and why it exists

A PHP array acts as both a list and an ordered map. Array functions perform standard operations on that container: array_map() transforms values, array_filter() selects elements, array_reduce() accumulates state, array_merge() combines inputs, array_keys() extracts keys, and usort() applies a custom order.

These functions replace repeated traversal code, not every loop. Their names state the operation and PHP handles iteration, but each API still defines its own rules for keys, empty values, and mutation. If you guess from map, filter, or reduce in another language, you can get valid PHP that quietly changes the shape of your data.

array_map(), array_filter(), array_reduce(), and usort() accept a callback . A callback is a function passed into another function, which invokes it while processing data. Arrow functions suit one-expression callbacks; an ordinary anonymous function is usually clearer when validation or state updates take several steps.

The result contract matters more than the syntax:

These functions fit data that is already in memory and has a clear processing boundary. A foreach loop or generator is often more direct when you need early exit, several pieces of state, streaming input, or careful key handling. Array functions don’t guarantee readability; three or four nested callbacks are already beyond their comfortable range.

How it works

All six functions traverse arrays, but they produce different kinds of results. Track values, keys, callback arguments, return values, and mutation separately instead of looking only at the final element values.

array_map() transforms values

array_map($callback, $array) calls the callback once for each value and builds a new array from its return values. With exactly one input array, the new array preserves the original keys. With two or more arrays, PHP combines values by position and gives the result sequential integer keys.

If the input arrays have different lengths, missing positions in shorter arrays are filled with null. The callback’s parameter count should match the number of arrays; PHP throws ArgumentCountError when the callback requires more arguments than the function supplies. If a transformation needs keys, combine array_keys() and array_values() explicitly or use foreach.

array_filter() selects elements

array_filter($array, $callback) retains elements whose callback result converts to true. The default mode passes only the value, ARRAY_FILTER_USE_KEY passes only the key, and ARRAY_FILTER_USE_BOTH passes the value followed by the key. Every mode preserves input keys in the returned array.

Without a callback, array_filter() removes values PHP considers empty, including false, null, integer 0, string "0", the empty string, and an empty array. That shortcut is safe only when all of those values are invalid in your domain. A zero quantity, form value, or status code can be legitimate, so write an explicit predicate for such data.

array_reduce() accumulates a result

array_reduce($array, $callback, $initial) starts with $initial as the accumulator, then passes the accumulator and each value to the callback in array iteration order. Each callback result becomes the next accumulator. The last result is the function result, and keys are never passed to the callback.

PHP differs from JavaScript here: omitting $initial doesn’t use the first element as the starting value. PHP starts with null and still processes the first element. An empty array without an initial value also returns null. Use 0 for a sum, '' for string concatenation, or [] when building a map; the initial value defines both the empty result and accumulator type.

array_merge() combines arrays

array_merge(...$arrays) processes its inputs from left to right. When the same string key occurs more than once, the value on the right overwrites the value on the left. Values with integer keys are appended instead of overwritten, then numbered from 0 in the result. Calling the function without arguments returns an empty array.

The array union operator + uses different rules. It retains every key already present on the left, ignores a right-side value with the same key, and doesn’t renumber integer keys. Use array_merge() to concatenate lists or let later configuration override earlier configuration; use + to preserve left-side keys and values. Neither operation discovers the right deep-merge policy for your domain.

array_keys() extracts keys

array_keys($array) returns every integer and string key in iteration order. With a second argument, it returns only keys whose values match $filterValue; a third argument of true selects ===, while the default uses loose comparison.

Use array_key_exists() to check whether one key exists instead of allocating the full key list and then calling in_array(). isset($array[$key]) asks a different question: it returns false when the key exists but its value is null. Pick the function according to whether you mean “the key exists” or “the value isn’t null.”

usort() defines an order

usort(&$array, $callback) rearranges values in place and replaces every key with a sequential integer. A comparator returns a negative integer, 0, or a positive integer when the left value belongs before, equal to, or after the right value. The <=> operator has exactly that contract.

Since PHP 8, elements that compare equal retain their original relative order, so usort() is a stable sort . Stability cannot repair an inconsistent comparator: if the callback contradicts itself or returns only a Boolean, the order is still unreliable. Since PHP 8.2, the function itself has return type true; the useful result is in the array it modified.

Examples

The four examples cover transformation and filtering, reduction, merging, and sorting. Every output below was produced with the local PHP 8.3.33 runtime.

Filter orders and transform display values

The orders use business identifiers as keys. Filtering and mapping both preserve those keys, so the first JSON encoding produces an object. Reindex with array_values() only when a JSON list is actually required.

Only keys 104 and 310 remain in $paid, and $labels keeps both keys. PHP’s json_encode() emits a JSON array only for arrays with sequential keys starting at 0, which is why the first line has object shape.

The second line deliberately calls array_values() at the serialization boundary. That placement is easy to review: processing retains the order identifiers, and only the external list format discards them.

Reduce order amounts by region

array_reduce() can return an array rather than a number. The empty initial array handles an empty order list and declares that the accumulator is a map from region to amount.

<?php

$orders = [
    ['region' => 'east', 'cents' => 1200],
    ['region' => 'west', 'cents' => 750],
    ['region' => 'east', 'cents' => 750],
];

$totals = array_reduce(
    $orders,
    function (array $carry, array $order): array {
        $region = $order['region'];
        $carry[$region] = ($carry[$region] ?? 0) + $order['cents'];
        return $carry;
    },
    [],
);

foreach (array_keys($totals) as $region) {
    printf("%s=%d\n", $region, $totals[$region]);
}

east=1950
west=750

The callback returns the updated $carry on every iteration. If it changes a local variable but forgets to return it, the next iteration receives null; the declared array type exposes that mistake quickly.

The first appearance of each region determines iteration order in $totals. array_keys() extracts the region-name list, while the loop still reads amounts from the original map. It doesn’t copy the amounts into the key list.

Distinguish merge from union

The user settings appear on the right of array_merge(), so they override the defaults. The nested features array is replaced as one value because this function handles only top-level keys.

<?php

$defaults = [
    'theme' => 'light',
    'page_size' => 20,
    'features' => ['search'],
];
$user = ['theme' => 'dark', 'features' => ['export']];

$settings = array_merge($defaults, $user);
$states = [10 => 'draft', 20 => 'review']
    + [20 => 'ignored', 30 => 'published'];

echo json_encode($settings), PHP_EOL;
echo json_encode($states), PHP_EOL;

{"theme":"dark","page_size":20,"features":["export"]}
{"10":"draft","20":"review","30":"published"}

The second expression uses +, so the left-side review value wins at key 20, and integer keys 10, 20, and 30 remain intact. Those keys aren’t sequential list indexes, so the JSON result is still an object.

Swapping the two operations would still produce valid code, but it would implement a different data policy. Configuration merge code should make override direction clear through names or tests rather than forcing readers to infer it from argument position.

Make a copy, then sort stably

usort() modifies its argument, so the code first copies $tasks. The two priority-1 tasks compare equal and retain their input order on PHP 8.3.

<?php

$tasks = [
    ['name' => 'write', 'priority' => 2],
    ['name' => 'test', 'priority' => 1],
    ['name' => 'deploy', 'priority' => 1],
];

$sorted = $tasks;
usort(
    $sorted,
    fn(array $left, array $right): int =>
        $left['priority'] <=> $right['priority'],
);

echo implode(',', array_column($sorted, 'name')), PHP_EOL;
echo implode(',', array_column($tasks, 'name')), PHP_EOL;

test,deploy,write
write,test,deploy

The first line proves both ascending priority order and preservation of the test, deploy tie. The second line shows that the original array stayed in its original order because the PHP array passed to usort() was a copy.

If the domain requires names to break equal-priority ties, put that second comparison in the callback. A stable sort preserves input order for equal items; it doesn’t invent a business tie-breaker.

Pitfalls

The most dangerous array-function errors don’t throw. They quietly change keys or classify valid data as empty. Tests should assert values, key order, and whether the input changed.

Treating a filtered map as a list

Fix: decide whether the result is a business map or a list. Call array_values() only when the consumer requires sequential indexes. If keys carry order numbers or database IDs, retain them and use a serialization shape that clearly represents a map.

Deleting zero with the default filter

Fix: express the domain condition in a callback, such as fn($value) => $value !== null. Don’t use array_filter($values) as input validation because PHP’s set of empty values is usually broader than your domain’s set of invalid values.

Assuming reduction starts with the first item

Fix: give possibly empty input an identity value of the right type. Omitting the initial value for multiplication lets null enter the calculation rather than starting from the first item; use 1 to state the multiplicative identity.

Mistaking a shallow merge for a policy

Fix: decide whether each configuration node should replace, append, or recurse before choosing an API or writing a small domain function. Test a repeated string key, an integer key, and a nested array. The word “recursive” doesn’t mean “correct for configuration overrides.”

Reversing callback arguments or return types

Fix: give callback parameters domain names and types, then verify comparator signs with lesser, equal, and greater input pairs. A Boolean converted to an integer provides only 0 and 1, so it can’t express both “before” and “equal.”

Forgetting that sorting mutates

Fix: assign the array to a new variable first when you need both orders. Consider uasort() when key-value association must survive. Don’t assign the true return value from usort() to $sorted; the sorted data remains in the argument.

Further reading

• PHP manual: array functions
• PHP manual: array_map()
• PHP manual: array_filter()
• PHP manual: array_reduce()
• PHP manual: array_merge()
• PHP manual: usort()