- カテゴリ: collection
- 対応バージョン: Laravel 12・PHP 8.2
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::collapse - 関連: flatten / flatMap / concat / merge / pluck
- 変更履歴: ─
要点（TL;DR）
- 何に使うか：配列（やコレクション）を要素に持つコレクションを、1段だけフラットなコレクションへ結合する
- 最低限の使い方：
collect([[1,2],[3,4]])->collapse() - よくある罠：
- 配列以外の要素は無視される（文字列・数値だけの要素は結果に含まれない）
- 文字列キーは後勝ちで上書き、数値キーは再インデックス
- 深いネストは解消しない（1段のみ）。再帰的には
flatten()を使う
概要
collapse()は「配列（またはコレクション）の集合」を1つの平坦なリストへ結合します。APIレスポンスでページごとにitemsが分かれている、pluck()で属性配列の配列になった、といった場面で後処理を簡潔にします。返り値は新しいコレクションで、元のデータは変更しません。
構文 / シグネチャ
// Illuminate\Support\Collection
public function collapse(): static;
引数（表）
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| なし | — | いいえ | — | 要素は配列またはコレクションであること |
- 戻り値：
Collection（1段フラット化された要素列） - 例外/副作用：
- 非配列・非コレクション要素は無視される
- 数値キーは再インデックス、文字列キーは後勝ちで上書き
使用例
最小例
<?php
use Illuminate\Support\Collection;
$collapsed = collect([[1, 2, 3], [4, 5], [6]])
->collapse();
$collapsed->all(); // [1, 2, 3, 4, 5, 6]
実務例
投稿のタグ配列（配列の配列）を1本化してユニーク化
<?php
use Illuminate\Support\Collection;
/** @var \Illuminate\Support\Collection $posts */
// $posts = collect([['tags' => ['php','laravel']], ['tags' => ['php','collection']]]);
$uniqueTags = $posts
->pluck('tags') // => Collection([['php','laravel'], ['php','collection']])
->collapse() // => Collection(['php','laravel','php','collection'])
->unique()
->values(); // => Collection(['php','laravel','collection'])
ページングAPIのitemsを一括結合
<?php
$responses = collect([
['items' => [['id'=>1], ['id'=>2]]],
['items' => [['id'=>3]]],
['items' => []],
]);
$allItems = $responses->pluck('items')->collapse(); // [['id'=>1], ['id'=>2], ['id'=>3]]
よくある落とし穴・注意
- 1段のみ：
[[1,[2,3]],[4]]→collapse()後は[1, [2,3], 4]。深いネストを解消したいならflatten()（必要ならflatten($depth)で段数指定）。 - キーの扱い：
- 数値キー：0から振り直し
- 文字列キー：同一キーは後勝ち（前の値が上書きされる）
- 要素型の制約：要素が配列/コレクション以外（例：
'foo'）は結果に含まれない。そうした要素も並べたいならflatten()を検討。 - パフォーマンス：総要素数に対してO(n)。大きなストリームを扱うなら
LazyCollectionでも利用可能（遅延評価でメモリ節約）。
代替・関連APIとの比較
flatten($depth = INF)：再帰的に多段ネストを平坦化。配列以外の要素も対象。多段ならこちら。flatMap($callback)：各要素を配列（またはコレクション）へ変換→即collapseまで一気に行う。「変換しながら結合」するなら最短。concat($items)：末尾にシーケンスを連結。入れ子を見ない。merge($items)：配列/コレクションを1回マージ。**「配列の配列」ではなく、**単に2つを合わせたい時に。
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('collapses one level and reindexes numeric keys', function () {
$c = collect([[10 => 'a', 'b'], ['c']])->collapse();
expect($c->all())->toBe(['a', 'b', 'c']);
});
it('ignores non-array items', function () {
$c = collect([[1,2], 'x', collect([3])])->collapse();
expect($c->all())->toBe([1,2,3]);
});
it('overwrites duplicate string keys (last wins)', function () {
$c = collect([['k' => 1], ['k' => 2]])->collapse();
expect($c->all())->toBe(['k' => 2]);
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
Call to a member function collapse() on array | 生配列に対して呼び出している | collect($array)->collapse() に変える |
| 期待より深くフラット化されない | collapse()は1段のみ | flatten()やflatMap()を使用 |
| 値が欠落している/上書きされる | 文字列キーが重複し後勝ちで上書き | キーを数値化してから結合、またはflatMapで配列の形を調整 |
| 文字列等が結果に出てこない | 非配列要素は無視 | すべて配列化する、またはflatten()を使う |
参考リンク
- Laravel公式ドキュメント：Collections – collapse
https://laravel.com/docs/12.x/collections#method-collapse - フレームワーク実装（
Illuminate\Support\Arr::collapseソース）
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Arr.php - フレームワーク実装（
Illuminate\Support\Collection）
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Collection.php
代替・関連APIとの比較（クイックガイド）
- flatten：多段ネストを解消したい
- flatMap：変換＋結合を一度にやりたい
- concat：ただ後ろに繋げたい
- merge：2つの配列/コレクションを統合したい
