- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::pluck - 関連: mapWithKeys, keyBy, values, data_get, Eloquent Builder::pluck
- 変更履歴: Laravel 12.x（12.20.0系）:
$value/$keyにClosureを渡せるように拡張 (Laravel News)
要点（TL;DR）
- 配列/モデル配列の「特定カラム（キー）」だけを抜き出して 新しいCollection を作る
- 最低限の使い方：
$names = $users->pluck('name'); - よくある罠
概要
pluck は、コレクション各要素（配列/オブジェクト）から、指定したキーの値だけを抽出して新しいコレクションを作ります。フォームの選択肢（id => name）や、ログ/DTOの一部フィールドだけ欲しい時に最短で書けます。ネストはドット記法にも対応します。 (Laravel)
構文 / シグネチャ
use Illuminate\Support\Collection;
/**
* @param string|array|\Closure $value // 取得する値（キー or ネスト指定 or 変換Closure）
* @param string|array|\Closure|null $key // 結果のキー（任意）
* @return \Illuminate\Support\Collection
*/
$plucked = $collection->pluck($value, $key = null);
- 引数
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
$value | string | array（Laravel 12.xで Closure も可） | ✅ | – | 取り出す値のキー。ネストはドット記法（例: a.b） (Laravel) |
$key | string | array | null（Laravel 12.xで Closure も可） | ❌ | null | 結果コレクションのキーに使う値のキー（重複時は後勝ち） (Laravel) |
- 戻り値：
Collection（抽出結果の新しいコレクション） - 例外/副作用：基本なし（元コレクションは変更しない／非破壊）
使用例
最小例
use Illuminate\Support\Collection;
$collection = collect([
['product_id' => 'prod-100', 'name' => 'Desk'],
['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$names = $collection->pluck('name');
dump($names->all()); // ['Desk', 'Chair']
（公式例と同等） (Laravel)
実務例（select用の id => label を作る）
use App\Models\User;
$items = User::query()
->where('active', true)
->get(['id', 'name']) // ここは明示しておくと意図が伝わりやすい
->pluck('name', 'id'); // [id => name] の Collection
// Bladeなら: @foreach($items as $id => $name) ...
もし「結果を配列で欲しい」なら
->all()、連番キーにしたいなら->values()を併用します。
よくある落とし穴・注意
- キー重複は後勝ち：
pluck('color', 'brand')のように$keyを指定して重複すると最後の要素で上書きされます。 (Laravel) - ネストはドット記法：配列の深い場所を
speakers.first_dayのように取れます（data_get相当の挙動を期待すると安全）。 (Laravel) - 計算量の目安：O(n)（要素を1回走査）
- チェーン可否 / 破壊的：チェーン可、非破壊（新しいCollectionを返す）
- LazyCollection：
LazyCollection側にもpluck関連の実装があり、同様の抽出用途で使えます（大量データならlazy()/cursor()と組み合わせる選択肢）。 (api.laravel.com)
代替・関連APIとの比較
keyBy()：要素全体をキーで引き直したい（id => モデル/配列）ならこちら。mapWithKeys()：キーと値を自由に整形して['k' => 'v']を作りたい（複雑な加工）ならこちら。values()：pluck()後に連番に振り直したい時（キー指定した/元キーが残った等）。- Eloquentの
pluck()（Builder）：DBから1〜2カラムだけ取る用途なら クエリ側のpluckが高速・省メモリになりやすい（必要カラムのみ取得）。
テスト例（Pest）
it('can pluck values and key them', function () {
$collection = collect([
['id' => 10, 'name' => 'Desk'],
['id' => 20, 'name' => 'Chair'],
]);
expect($collection->pluck('name')->all())->toBe(['Desk', 'Chair']);
expect($collection->pluck('name', 'id')->all())->toBe([10 => 'Desk', 20 => 'Chair']);
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
pluck したら null だらけ | 指定キーが存在しない / ネスト指定が間違い | キー名を確認。ネストはドット記法にする。必要なら filter() で除去 |
$key 指定したら件数が減った | キー重複で上書き（後勝ち） (Laravel) | キーがユニークになるよう見直す or groupBy() 等へ設計変更 |
| 取りたいのが「2列」以上 | pluck は基本1列（+キー列） | map->only([...]) / select / DTO化などに切り替える |
参考リンク
- Laravel 12.x Collections —
pluck()(Laravel) - Laravel News — pluckがClosure対応（2025-09-22） (Laravel News)
- LaravelVersions（12.x変更一覧に pluck Closure 対応が記載） (Laravel Versions)
