- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN:
Illuminate\Support\Collection::map - 関連: transform / flatMap / each / filter
- 変更履歴: 旧来より存在。非破壊メソッドとして一貫。
要点（TL;DR）
- 要素ごとにコールバックを適用し、新しいコレクションを返す
$collection->map(fn ($v) => $v * 2)- 罠: 元のコレクションは変更されない／キーは保持される
概要
map はコレクション内の全要素に対してコールバックを実行し、処理結果を集めた新しいコレクションを返します。
非破壊的でチェーン利用に向き、データ変換やDTO生成に多用されます。キーはそのまま維持されます。
構文 / シグネチャ
public function map(callable $callback): static
- 引数
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
$callback | callable | ✔ | — | 各要素を受け取り、新しい値を返すクロージャ。引数は (mixed $value, mixed $key) |
- 戻り値:
Collection— 変換後のコレクション - 例外/副作用: 特になし（遅延評価ではなく即実行）
使用例
最小例
use Illuminate\Support\Collection;
$numbers = collect([1, 2, 3]);
$doubled = $numbers->map(fn ($n) => $n * 2);
print_r($doubled->all());
// [2, 4, 6]
実務例
use Illuminate\Support\Collection;
$users = collect([
['id' => 1, 'name' => 'Taro'],
['id' => 2, 'name' => 'Hanako'],
]);
$dtos = $users->map(fn ($u) => new App\Data\UserDto($u['id'], $u['name']));
foreach ($dtos as $dto) {
echo $dto->id.': '.$dto->name.PHP_EOL;
}
よくある落とし穴・注意
- 元コレクションは変わらない → 更新したいなら
transformを使う - キーは保持される → 再採番したいなら
values()を併用 - ネスト変換が必要なら
flatMapを検討
代替・関連APIとの比較
map: 非破壊、キー保持transform: 破壊的、キー保持flatMap: ネスト配列をフラット化しつつ変換each: 値を返さず副作用実行のみ
テスト例（Pest）
it('doubles each number', function () {
$numbers = collect([1, 2, 3]);
$result = $numbers->map(fn ($n) => $n * 2);
expect($result->all())->toBe([2, 4, 6]);
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
| 値が更新されない | map は非破壊 | transform を使用する |
| インデックスが飛び飛び | キー保持仕様 | values() でリセット |
| ネスト配列が残る | map は平坦化しない | flatMap を使用 |
