定義と使用方法

PHPバージョン
4.0.6+

array_map関数は、
配列の各要素に指定したコールバック関数を適用し、新しい配列を返す関数です。
このとき、元の配列は変更されません。

array_map関数に渡されるコールバック関数は、「各要素を変換して新しい配列にマッピング（mapping）する役割を持つ」と言われます。
このようにマッピングされた結果を新しい配列として返すため、この関数名は「array_map」と名付けられています。マッピング（mapping）とはある値を別の値に対応させる処理を意味する概念であり、数学、コンピューターサイエンス、地理情報システムなどさまざまな分野で使用されます。

なぜarray_map()関数を使用するのか？

array_map()関数は、既存の配列の各要素を特定のルールやロジックを持つコールバック関数を通じて変換し、変換後の要素で構成された新しい配列を作成するために使用します。

例えば、次のような処理でよく使用されます。

  • 数値の配列を二乗した新しい配列を作成する
  • 文字列の配列をすべて小文字に変換する
  • 既存の配列を加工してHTMLのUIコンポーネントやそのオプションに変換する

概念理解のための基本例

簡単な例を通して説明します。
次は、数値の配列の各数字を2倍にして新しい配列を生成して返すarray_map()関数の使用例です。

PHP 
$numbers = [1, 2, 3, 4, 5];

// 各要素を2倍にするコールバック関数を定義
function double($number) {
    return $number * 2;
}

// array_map()関数を使用して各要素にコールバック関数を適用し、新しい配列を生成
$doubled_numbers = array_map('double', $numbers);

print_r($doubled_numbers);
// 出力: Array ( [0] => 2 [1] => 4 [2] => 6 [3] => 8 [4] => 10 )

この例では、$numbers配列の各要素を2倍にするためのdouble()というコールバック関数を定義し、array_map()関数を使用してこの関数を$numbers配列の各要素に適用し、$doubled_numbers配列を生成します。その結果、$doubled_numbers配列には各要素が2倍になった値が含まれています。

構文

PHP 
array_map(?callable $callback, array $array, array ...$arrays): array

引数

array_map()関数の引数
$callback コールバック関数です。各配列要素に適用する関数を指定します。この関数は配列の各要素に適用され、要素を変換または加工する役割を持ちます。コールバック関数は配列の要素1つを引数として受け取り、変換後の結果を返す必要があります。コールバック関数を名前で渡す場合は、文字列として名前を指定します。
$array $callbackに適用する最初の配列です。
$arrays $callbackに適用する…番目の配列です。配列の数に応じて追加の配列を指定できます。

戻り値

コールバック関数を指定された配列（または複数の配列）の各値に適用し、結果を含む新しい配列を返します。この新しい配列は、コールバック関数が適用された配列のキーを保持します。ただし、注意すべき点もあります。

  • 1つの配列のみがコールバック関数に渡された場合：返された配列は元の配列と同じキーを持ちます。コールバック関数がnullの場合は、元の配列がそのまま返されます。
  • 複数の配列がコールバック関数に渡された場合：返された配列は連続する整数キーを持ちます。
  • コールバック関数に渡された配列が参照変数の場合：PHP 8.0.0以降ではE_WARNINGの警告が発生します。

1つの配列のみがコールバック関数に渡された場合

PHP 
$numbers = [1, 2, 3, 4, 5];

// 各要素を2倍にするコールバック関数を定義
function double($number) {
    return $number * 2;
}

// array_map()関数を使用して1つの配列にのみコールバック関数を適用
$doubledNumbers = array_map('double', $numbers);

print_r($doubledNumbers);
/* 出力:
Array
(
    [0] => 2
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 10
)
*/

上の例では、$numbers配列のみにコールバック関数doubleを適用しています。array_map()関数が1つの配列にのみ適用されたため、返された配列は元の配列と同じキーを持ちます。出力では、各要素が2倍になった値とともに元のキーを保持しています。

複数の配列がコールバック関数に渡された場合

PHP - コールバックに渡す配列の長さが同じ場合 
$array1 = [1, 2, 3];
$array2 = [4, 5, 6];

// 2つの配列をコールバック関数に渡して値を合計する例
function add_arrays($a, $b) {
    return $a + $b;
}

$result = array_map('add_arrays', $array1, $array2);

print_r($result);
/* 出力:
Array
(
    [0] => 5
    [1] => 7
    [2] => 9
)
*/

上の例では、$array1と$array2の2つの配列をadd_arraysというコールバック関数に渡し、この関数は2つの配列の値を加算して返します。ただし、$result配列のキーは連続する整数で構成されます。

PHP - コールバックに渡す配列の長さが異なる場合 
$array1 = [1, 2, 3];
$array2 = [4, 5];

// 2つの配列をコールバック関数に渡して値を合計する例
function add_arrays($a, $b) {
    return $a + $b;
}

$result = array_map('add_arrays', $array1, $array2);

print_r($result);
/* 出力:
Array
(
    [0] => 5
    [1] => 7
    [2] => 3
)
*/

上の例では、$array1と$array2の2つの配列をadd_arraysコールバック関数に渡します。$array1は3つの要素を持ち、$array2は2つの要素を持っています。array_map()関数は最も長い配列の長さを基準にコールバック関数を適用し、返される配列の長さも最も長い配列の長さと同じになります。

つまり、複数の配列をarray_map()関数に渡し、配列の長さが異なる場合、返される配列の長さは最も長い入力配列の長さと同じになり、連続する整数キーが割り当てられます。このとき、より長い配列に存在しない要素はnullで埋められます。

コールバック関数に渡された配列が参照変数の場合

PHP - 8.0.0以降ではE_WARNINGの警告が発生します。 
$array = [1, 2, 3];

// コールバック関数は参照で渡す必要がありますが、参照で渡していません
function addOne(&$value) {
    $value += 1;
}

array_map('addOne', $array);

活用例

array_map()関数を使用して配列の各要素をマッピングし、新しい配列を返す3つの有用な例を見てみましょう。

小文字変換

文字列の配列に対して各文字列を小文字に変換し、新しい配列を作成する場合、array_map()関数を使用できます。

PHP 
$words = ['Hello', 'World', 'PHP', 'ARRAY'];

// 各文字列要素を小文字に変換するコールバック関数を定義
function to_lowercase($word) {
    return strtolower($word);
}

// array_map()関数を使用して各文字列要素にコールバック関数を適用し、新しい配列を生成
$lowercase_words = array_map('to_lowercase', $words);

print_r($lowercase_words);

// 出力: Array ( [0] => hello [1] => world [2] => php [3] => array )

上のコードでは、to_lowercaseというコールバック関数を定義し、この関数をarray_map()関数に適用して$words配列の各文字列要素を小文字に変換しています。結果として、配列にはすべての文字列要素が小文字（strtolower()関数を使用）に変換された値が格納されます。

複数配列の操作

複数の配列を同時に操作して結合する場合です。例えば、複数の配列の値を合計したり、連結して新しいデータ構造を作成する際に使用できます。

PHP 
$names = ['John', 'Jane', 'Bob'];
$scores = [85, 92, 78];

// 名前と点数を結合して連想配列を作成
$students = array_map(function($name, $score) {
    return ['name' => $name, 'score' => $score];
}, $names, $scores);

print_r($students);
/* 出力:
Array
(
    [0] => Array ( [name] => John [score] => 85 )
    [1] => Array ( [name] => Jane [score] => 92 )
    [2] => Array ( [name] => Bob [score] => 78 )
)
*/

オブジェクト配列への変換

オブジェクト配列から特定のプロパティを抽出したり、オブジェクトのメソッドを呼び出して配列を変換する場合です。例えば、ユーザーオブジェクトの配列から名前だけを抽出したり、各ユーザーの特定のメソッドを呼び出して新しいデータを生成する際に使用できます。

PHP 
class User {
    public $name;
    public function __construct($name) {
        $this->name = $name;
    }
    public function getGreeting() {
        return "Hello, my name is " . $this->name;
    }
}

$users = [new User('Alice'), new User('Bob'), new User('Charlie')];

// 各ユーザーの挨拶文を抽出
$greetings = array_map(function($user) {
    return $user->getGreeting();
}, $users);

print_r($greetings);
/* 出力:
Array
(
    [0] => Hello, my name is Alice
    [1] => Hello, my name is Bob
    [2] => Hello, my name is Charlie
)
*/

array_map()関数は、配列の操作や変換のための強力なツールとして使用でき、さまざまな状況で有用に活用できます。

参考資料

関連項目