pull — コレクションから値を取得しつつ削除する

• カテゴリ: collection
• 種類: メソッド
• 掲載バージョン: Laravel 12 / PHP 8.4
• FQCN: Illuminate\Support\Collection::pull
• 関連: get, forget, only, except
• 変更履歴: なし（長期安定）

要点（TL;DR）

• 使いどころ：キー指定で値を取り出し、その要素を同時にコレクションから削除したいとき
• 最小例：$value = $collection->pull('key');
• よくある罠：
  • 破壊的メソッド（元のコレクションが変更される）
  • 存在しないキーは既定値を返すだけでエラーにならない
  • ネスト指定はドット記法のみ対応

概要

pull は、コレクションから 指定キーの値を取得しつつ、その要素を削除 するメソッドです。
設定値の消費、キュー的な扱い、処理済みデータの切り出しなどで使われます。
配列の unset と get を同時に行うイメージです。

構文 / シグネチャ

public function pull($key, $default = null): mixed

引数

引数	型	必須	既定値	説明
$key	string|int	はい	–	取得・削除するキー（ドット記法可）
$default	mixed	いいえ	null	キーが存在しない場合に返す値

• 戻り値：mixed（取得した値、または既定値）
• 副作用：指定キーがコレクションから削除される

使用例

最小例

use Illuminate\Support\Collection;

$collection = collect([
    'name' => 'Laravel',
    'version' => 12,
]);

$version = $collection->pull('version');

// $version === 12
// $collection === collect(['name' => 'Laravel'])

既定値付き

$value = $collection->pull('not_exists', 'default');
// 'default' が返る。コレクションは変更なし

実務例：設定値を消費する

$options = collect([
    'limit' => 10,
    'offset' => 0,
    'debug' => true,
]);

$limit = $options->pull('limit');
$offset = $options->pull('offset');

// $options には 'debug' だけが残る

ネスト構造（ドット記法）

$data = collect([
    'user' => [
        'name' => 'Taro',
        'role' => 'admin',
    ],
]);

$role = $data->pull('user.role');

// $role === 'admin'
// user 配下から role が削除される

よくある落とし穴・注意

• 破壊的操作
  pull は元のコレクションを書き換えます。再利用する場合は注意。
• 存在チェック不要だが見落としやすい
  キーがなくても例外は出ません。意図せず既定値を使っていないか注意。
• LazyCollection 非対応
  pull は即時評価が前提。LazyCollection では使えません。

代替・関連APIとの比較

メソッド	取得	削除	破壊的	用途
get	○	×	×	値を読むだけ
forget	×	○	○	削除のみ
pull	○	○	○	取得＋削除
only	○	×	×	必要なキーだけ抽出
except	×	○	×	指定キー以外を残す

選定基準：
「一度使った値を残したくない」なら pull。

テスト例（Pest）

it('pull removes the value from collection', function () {
    $c = collect(['a' => 1, 'b' => 2]);

    $value = $c->pull('a');

    expect($value)->toBe(1);
    expect($c->has('a'))->toBeFalse();
});

トラブルシュート

症状	原因	対処
値が消えている	pull が破壊的	get に変更する
null が返る	キーが存在しない	既定値を指定する
ネストで取得できない	配列形式が違う	ドット記法を確認

参考リンク

• Laravel公式ドキュメント（Collections）
  https://laravel.com/docs/collections