- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::flatten - 関連: collapse / flatMap / dot / pluck / values
- 変更履歴: Laravel 10–12で仕様同等（主な変更なし）
要点（TL;DR）
- 多次元の配列/コレクションを一次元に平坦化する
collect($data)->flatten()で全階層フラット、flatten(1)で1階層のみ- 罠: キーは破棄、深いデータはメモリ使用増、
dot()とは目的が違う（キー保持しない）
概要
flatten は入れ子になった配列やコレクションを一次元のコレクションへ変換します。階層の深さは引数で制御でき、既定は全階層です。タグ一覧の重複排除や、ネストしたレスポンスを単純化して扱いたい場面で有効です。
構文 / シグネチャ
use Illuminate\Support\Collection;
public function Collection::flatten(int|float $depth = INF): static
- 引数（表） 引数 型 必須 既定値 説明 $depth int | float いいえ
INF平坦化する深さ。1で1階層のみ、INFで全階層。 - 戻り値：
Collection（キーはリセットされ、連番キーの一次元コレクションを返す） - 例外/副作用：例外なし。元のコレクションは非破壊。大きなネストを
INFで展開するとメモリ使用量増。
使用例
最小例
use Illuminate\Support\Arr;
$nested = collect([1, [2, 3], [[4], 5]]);
$flat = $nested->flatten(); // [1, 2, 3, 4, 5]
$flat1 = $nested->flatten(1); // [1, 2, 3, [4], 5]
// all() で配列として確認
var_dump($flat->all(), $flat1->all());
実務例（タグ一覧の重複排除）
// $posts: 各Postが ['title' => ..., 'tags' => ['php','laravel']] を持つとする
$uniqueTags = collect($posts)
->pluck('tags') // コレクション<配列>
->flatten() // ['php','laravel','php', ...] に一次元化
->unique() // 重複除去
->values(); // 連番キー付け直し
// ['laravel','php', ...]
実務例（APIレスポンスのネスト解除 + 欠損除去）
$response = [
['items' => [['id'=>1], ['id'=>2]]],
['items' => null],
['items' => [['id'=>3]]],
];
$ids = collect($response)
->pluck('items') // [[['id'=>1],['id'=>2]], null, [['id'=>3]]]
->filter() // null を除去
->flatten() // [['id'=>1], ['id'=>2], ['id'=>3]]
->pluck('id') // [1,2,3]
->values();
よくある落とし穴・注意
- キー喪失：連想キーは破棄されます。キーを保持して平坦化したいなら
dot()を検討。 - 深さの指定：
flatten(1)は1階層のみ。flatMap()はマッピング+1階層フラットで性質が異なる。 - メモリ/性能：
INFで巨大配列を展開するとメモリを食います。必要最小の深さを指定するか、分割処理やLazyCollectionの活用を検討。 - 文字列は分割しない：
"abc"はそのまま1要素として扱われます（文字ごとの分解はしない）。
代替・関連APIとの比較
- collapse：一次元配列を要素に持つコレクションを1階層だけ結合（
flatten(1)に近い用途、構造が単純なときに高速）。 - flatMap：各要素を配列で返すマップ処理 + 1階層フラット。加工と平坦化を同時に行いたいとき。
- dot / undot：キーを
a.b.c形式で保持しつつフラット化／元に戻す。キー情報が必要な設定配列などに向く。
選定基準
- ただ平坦化：
flatten - マッピングしつつ1段フラット：
flatMap - 配列の配列を結合（単純）：
collapse - キーを保持：
dot/undot
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('flattens nested structures', function () {
$c = collect([1, [2, 3], [[4], 5]]);
expect($c->flatten()->all())->toBe([1,2,3,4,5]);
expect($c->flatten(1)->all())->toBe([1,2,3,[4],5]);
});
コレクション特性（collectionカテゴリの追加情報）
- チェーン可否：可（
Collectionを返す） - 破壊的/非破壊：非破壊
- キー保持：しない（数値キーに張り直し）
- LazyCollection：対応可（
LazyCollectionでも同名メソッド使用可） - 計算量の目安：O(n)（展開対象要素数に比例）
- 入出力対応（サンプル） 入力 呼び出し 出力
[1,[2,3],[[4]]]flatten()[1,2,3,4][1,[2,3],[[4]]]flatten(1)[1,2,3,[4]][['a'=>1], ['b'=>2]]flatten()[1,2]（キー喪失）
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
| 期待したキーがない | flatten はキーを破棄する | キー保持が必要なら dot() を使う、または構造を見直す |
| メモリ不足・遅い | 深い/巨大配列を INF で展開 | flatten(1) など深さ制限、分割処理、LazyCollection の活用 |
| 文字列が分解されない | 文字列は配列としては扱われない | 文字分解は別途 str_split 等で処理 |
参考リンク
- Laravel公式：Collections – flatten（Laravel 12）
https://laravel.com/docs/12.x/collections#method-flatten - Laravel公式：Collections – collapse
https://laravel.com/docs/12.x/collections#method-collapse - Laravel公式：Collections – flatMap
https://laravel.com/docs/12.x/collections#method-flatmap - Laravel公式：Collections – dot / undot
https://laravel.com/docs/12.x/collections#method-dot
https://laravel.com/docs/12.x/collections#method-undot - ソースコード（Illuminate\Support\Collection）
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Collection.php
