put — キー指定で要素を追加・上書きする（破壊的）
collection
- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::put
- 関連: get / pull / push / forget / replace
- 変更履歴: なし（互換的に安定）
要点（TL;DR）
- 何に使うか：コレクションに 任意キーの値を追加・上書きする
- 最低限の使い方（1行コード）：
collect()->put('key', 'value');
- よくある罠：
- 破壊的（元のコレクションを変更）なので、参照共有していると意図せず影響する
- ドット記法のネスト更新はできない（
a.b は文字列キー扱い）→ ネストは data_set / Arr::set
- 返り値は
$this（同一インスタンス） なので、チェーンはできるが「新しいコレクションが返る」と誤解しやすい (Laravel)
概要
put は、コレクションに対して 指定キーの値をセットするためのメソッドです。設定済みのキーなら上書き、未設定なら追加になります。設定用の「軽いミューテータ」として、DTO生成前の整形やレスポンス組み立てでよく使います。 (Laravel)
構文 / シグネチャ
use Illuminate\Support\Collection;
/** @return $this */
$collection->put(mixed $key, mixed $value);
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|
$key | mixed | はい | なし | セットするキー（文字列 / 数値など） |
$value | mixed | はい | なし | セットする値 |
使用例
最小例
<?php
use Illuminate\Support\Collection;
$collection = collect(['product_id' => 1, 'name' => 'Desk']);
$collection->put('price', 100);
var_dump($collection->all());
// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
（Laravel公式ドキュメントの例と同じ挙動です） (Laravel)
実務例
<?php
use App\Models\User;
use Illuminate\Http\Request;
final class ProfileController
{
public function show(Request $request)
{
/** @var User $user */
$user = $request->user();
// レスポンス用の“組み立て用コレクション”として put を使う
$payload = collect()
->put('id', $user->id)
->put('name', $user->name)
->put('is_admin', $user->is_admin)
->put('updated_at', $user->updated_at?->toAtomString());
return response()->json($payload->all());
}
}
よくある落とし穴・注意
- **破壊的（mutable）**です。
$a = $collection; $a->put(...) は $collection 側にも影響します（同一インスタンス）。 (Laravel API)
- ネストの更新（ドット記法）には向きません。
put('meta.color', 'red') は ['meta.color' => 'red'] のように「文字列キー」が増えるだけです。ネスト更新は data_set() や Illuminate\Support\Arr::set() を検討してください。
- 計算量の目安：キー指定のセットは概ね O(1)（PHP配列のハッシュ操作相当）。
- キー保持：キー付きコレクションに対して指定キーでセットするので、当然キーは保持されます。
入出力対応表（小サンプル）
| 入力 | 操作 | 出力 |
|---|
collect(['a' => 1]) | ->put('b', 2) | ['a' => 1, 'b' => 2] (Laravel) |
collect(['a' => 1]) | ->put('a', 9) | ['a' => 9] |
collect([]) | ->put('x', null) | ['x' => null] |
代替・関連APIとの比較
get($key, $default = null)：取得。セットはしない（読み取り用途）。pull($key, $default = null)：取得しつつ削除（取り出し用途）。 (Laravel)push($value, ...)：末尾追加（数値キー配列っぽく扱う用途）。forget($key)：キー削除（セットの逆）。replace($items) / merge($items)：複数要素をまとめて反映したいときに有利。
選定基準：1件だけキー指定で更新したいなら put、複数まとめてなら merge/replace、取り出して消すなら pull。
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('put sets the given key and value (mutates)', function () {
$c = collect(['a' => 1]);
$returned = $c->put('b', 2);
expect($returned)->toBe($c); // $this が返る
expect($c->all())->toBe(['a' => 1, 'b' => 2]);
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|
put('a.b', 1) でネストが更新されない | put はドット記法を解釈しない | ネストは data_set / Arr::set を使う |
| どこかの処理で値が勝手に変わる | 同じコレクションインスタンスを参照共有して put している | clone する / 破壊しない設計（配列作成→collect()）にする |
参考リンク
- Laravel 公式ドキュメント（Collections:
put） (Laravel)
- Laravel API（
Illuminate\Support\Collection::put が $this を返す） (Laravel API)
