- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::concat - 関連: merge / union / push / prepend / values
- 変更履歴: —
要点（TL;DR）
- 配列や別のコレクションの値を順に末尾へ連結し、新しいコレクションを返す（キーは捨てる）。
collect([1, 2])->concat(['a' => 3, 4])->all(); // [1, 2, 3, 4]- 罠：①連結側のキーは保持されない／②非破壊（元は変わらない）／③反復可能（iterable）以外はエラー
概要
concat は、与えた配列・コレクションの値だけを取り出して末尾に連結します。返り値は新しいコレクションなので元のインスタンスは変化しません。キーを活かした結合や上書きが必要なら merge / union を選びます。
構文 / シグネチャ
use Illuminate\Support\Collection;
/**
* 値を末尾に連結（キーは破棄）
*
* @param iterable<mixed>|\Illuminate\Support\Enumerable $source
* @return \Illuminate\Support\Collection
*/
public function concat($source): Collection;
引数（表）
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| $source | iterable | Enumerable | ✓ | — | 末尾に連結するシーケンス。キーは無視して値のみを追加 |
- 戻り値：
Collection（0 からの連番キーで再インデックスされた新しいコレクション） - 例外/副作用：元コレクションは変更しない。
$sourceが反復不能だと実行時エラー（TypeError 等）になり得る。
使用例
最小例
<?php
use Illuminate\Support\Collection;
$base = collect(['x' => 'A', 'B']); // 値: ['A', 'B']
$out = $base->concat(['k' => 'C', 'D']); // 値: ['A', 'B', 'C', 'D']
var_dump($out->all()); // ['A', 'B', 'C', 'D'] キーは 0..3 に振り直し
実務例：検索結果に「推薦アイテム」を末尾追加
<?php
use Illuminate\Support\Collection;
$results = collect([
['id' => 10, 'title' => 'Laravel Tips'],
['id' => 11, 'title' => 'Eloquent Basics'],
]);
$recommended = [
['id' => 999, 'title' => '公式ドキュメントを読もう'],
];
$final = $results->concat($recommended);
// 一覧表示などで自然に末尾へ並べたい時に有効（キーを気にしないケース）
foreach ($final as $item) {
echo $item['title'] . PHP_EOL;
}
コレクション特性・計算量
- チェーン可：可
- 破壊的/非破壊：非破壊（新しい
Collectionを返す） - キー保持：しない（追加側だけでなく、結果は 0..N に再インデックス）
- LazyCollection：同名メソッドあり（両方 Lazy なら低メモリで連結可能）
- 計算量：O(n + m)（n=元要素数、m=連結要素数）
入出力対応（小サンプル）
| 入力 | 連結 | 出力（->all()） |
|---|---|---|
['a'=>1, 2] | ['x'=>3, 4] | [1, 2, 3, 4] |
[1] | collect([2,3]) | [1, 2, 3] |
よくある落とし穴・注意
- キーが必要なら不適：
concatは値のみを連結。キーを保つ・キーで上書きしたいならmerge/unionを使う。 - 元が変わらない：
$c->concat([...])は$cを変更しない。元を更新したいなら$c = $c->concat([...])か破壊的なpush/prependを検討。 - 大量データ：大きな配列同士の結合はメモリ消費に注意。
LazyCollectionのconcatでストリーム的に処理すると安全。
代替・関連APIとの比較
- merge：キー付き配列をマージ。同一文字列キーは上書き、数値キーは末尾に追加し再インデックス。
- union：キーの保持を優先し、既存キーは上書きしない。不足キーのみ追加。
- push / prepend：単一値を末尾/先頭に破壊的に追加。
- values：キーを捨てて 0..N に再インデックス（
merge/union後にキーを整理したい時に併用）。
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('concats values and discards keys', function () {
$out = collect(['a' => 1, 2])->concat(['x' => 3, 4]);
expect($out->all())->toBe([1, 2, 3, 4]);
});
it('does not mutate original collection', function () {
$base = collect([1]);
$base->concat([2]);
expect($base->all())->toBe([1]);
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
| TypeError（または foreach 警告） | $source が配列・反復可能でない | Arr::wrap($x) などで配列化する／コレクションに変換して渡す |
| 期待したキーが残らない | concat はキーを破棄する仕様 | merge / union + 必要なら values() を併用 |
| 元コレクションが変わらない | concat は非破壊 | 代入で受ける：$c = $c->concat($more)／破壊的メソッドを使う |
参考リンク
- Laravel 12.x Collections — concat：https://laravel.com/docs/12.x/collections#method-concat
- Laravel 12.x Collections — Lazy Collections：https://laravel.com/docs/12.x/collections#lazy-collections
- Source —
Illuminate\Support\Collection（GitHub）：https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Collection.php
