push — コレクション末尾に要素を追加
collection
- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN:
Illuminate\Support\Collection::push
- 関連:
put, prepend, merge, concat
- 変更履歴: なし（安定API）
要点（TL;DR）
- 用途: コレクションの末尾に要素を追加する
- 最小例:
$collection->push($value);
- よくある罠:
- 破壊的（元のコレクションが変更される）
- 連想キーは付かない（数値キーで追加）
LazyCollection では使えない
概要
push は、既存の Collection の末尾に 1 つ以上の要素を追加するメソッドです。
配列の []= に相当し、**インプレース（破壊的）**に動作します。
ループ内での逐次追加や、処理結果の後付けに向いています。
構文 / シグネチャ
public function push(...$values): static
引数
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|
| $values | mixed | ✔ | — | 追加する値（複数指定可） |
- 戻り値:
Collection（自身）
- 例外/副作用: なし（元コレクションを書き換える）
使用例
最小例
use Illuminate\Support\Collection;
$collection = collect([1, 2]);
$collection->push(3);
$collection->all(); // [1, 2, 3]
複数要素の追加
$collection = collect([1]);
$collection->push(2, 3, 4);
$collection->all(); // [1, 2, 3, 4]
実務例（処理結果の後付け）
use Illuminate\Support\Collection;
$logs = collect();
foreach ($records as $record) {
if ($record->isInvalid()) {
$logs->push([
'id' => $record->id,
'reason' => 'invalid',
]);
}
}
// $logs は逐次追加された結果を保持
よくある落とし穴・注意
- 破壊的
push は元のコレクションを変更します。
イミュータブルに扱いたい場合は concat や merge を検討してください。
- キーを指定できない
連想配列として追加したい場合は put を使用します。
- LazyCollection 非対応
遅延評価を保ちたい場合、push は使えません。
代替・関連APIとの比較
| メソッド | 特徴 | 使い分け |
|---|
push | 末尾に追加（破壊的） | 逐次追加したい |
prepend | 先頭に追加 | 順序を前に |
put | キー指定で追加 | 連想キーが必要 |
merge | 配列/コレクション結合 | 新しいコレクション |
concat | 非破壊で結合 | イミュータブルに扱う |
テスト例（Pest）
it('push appends values to the collection', function () {
$collection = collect([1, 2]);
$collection->push(3);
expect($collection->all())->toBe([1, 2, 3]);
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|
| 追加されない | LazyCollection を使用 | Collection に変換する |
| キーが保持されない | push は数値キー | put を使う |
参考リンク
