array_map
Applies a callback to every element of one or more arrays and returns the results as a new array.
array_map(?callable $callback, array $array, array ...$arrays): array- Added in PHP 4.0.6
Parameters
| Parameter | Type | Description |
|---|---|---|
$callback | ?callable | The function to run for each element. Pass null to zip the arrays together instead. |
$array | array | The array whose elements are passed to the callback. |
$arraysoptional | array | Any number of further arrays; the callback then receives one element from each, in parallel. |
Return value
arrayA new array containing the return value of the callback for each element. With a null callback and several arrays, it returns an array of grouped arrays (a zip).
Errors
Throws a TypeError if the callback is not callable, and any exception the callback itself throws propagates out of array_map.
Changelog
- PHP 8.0.0If the callback expects a parameter by reference, an E_WARNING is emitted.
array_map() is the tool for turning one array into another array of the same shape. You give it a callback and an array; it hands each value to the callback and collects the return values. Nothing is modified in place — the original array is untouched.
When to reach for it
Use it when every element needs the same transformation and you want the result as a value, not as a side effect: casting a column of strings to ints, formatting prices, extracting one field from a list of rows, building label strings for a select box. If you want to keep or drop elements instead of transforming them, use array_filter(). If you want a single value out, use array_reduce(). If you want to mutate the array in place, use array_walk().
Two things that trip people up
First, the callback only receives the value, never the key. To work with keys, pass array_keys($arr) as a second array and let array_map() walk them in parallel.
Second, keys survive only in the single-array form. As soon as you pass a second array, the result is renumbered from 0. When the arrays have different lengths, the shorter ones are padded with null so the longest one determines the result size.
Passing null as the callback with two or more arrays zips them into pairs — the array equivalent of transposing rows and columns.
Example
When to use it
- Add tax to every price in a cart before rendering the totals
- Cast a column of numeric strings from a CSV into real integers
- Zip parallel arrays of IDs and names into 'id: name' display strings
- Trim whitespace from every field of a submitted form array
Frequently asked questions
Does array_map preserve keys?
Only when you pass exactly one array — then string and integer keys are kept as they are. If you pass two or more arrays, the result is reindexed with sequential integer keys starting at 0.
What is the difference between array_map and array_walk?
array_map returns a new array and leaves the original alone; array_walk returns a bool and modifies the array in place through a by-reference callback. Use array_map when you want a transformed copy, array_walk when you want to mutate what you already have.
How do I get the key inside the array_map callback?
Pass array_keys($arr) as an additional array so the callback receives the key and the value in parallel. Be aware that this makes the result a reindexed list rather than a keyed array.
More examples
Zipping arrays with a null callback
With null as the callback and more than one array, array_map groups the arrays element by element. The output is three sub-arrays: [1, 'Ada'], [2, 'Bo'] and [3, 'Cy'] — the same result you would get from transposing a table.
<?php
$ids = [1, 2, 3];
$names = ['Ada', 'Bo', 'Cy'];
$pairs = array_map(null, $ids, $names);
print_r($pairs);
echo count($pairs), " rows\n";Getting at the keys
The callback never sees keys, so array_keys() is passed as a parallel array. The output shows ['page=2', 'sort=name'] and then the joined string page=2&sort=name. Note the result is a list — the original string keys are gone because two arrays were passed.
<?php
$query = ['page' => 2, 'sort' => 'name'];
$parts = array_map(
fn($k, $v) => "$k=$v",
array_keys($query),
$query
);
print_r($parts);
echo implode('&', $parts), "\n";Uneven array lengths pad with null
The result has three entries, matching the longest input. The second and third pairs receive NULL for $q because $b ran out of elements. This is a common source of silent nulls when mapping over arrays you assumed were the same length.
<?php
$a = [1, 2, 3];
$b = ['x'];
var_dump(array_map(fn($p, $q) => [$p, $q], $a, $b));
Discussion