values — 連番キーで再構築する

カテゴリ: collection
掲載バージョン: Laravel 12・PHP 8.4
名前空間 / FQCN / コマンド: Illuminate\Support\Collection::values
関連: keys / pluck / map / sortBy / unique
変更履歴: —

要点（TL;DR）
概要
構文 / シグネチャ
使用例
よくある落とし穴・注意
代替・関連APIとの比較
テスト例（Pest）
トラブルシュート（エラー別）
コレクション特性（カテゴリ追記）
参考リンク
関連記事

要点（TL;DR）

フィルタやソート後に欠番キーを0からの連番に振り直す。
collect($arr)->values()->all()
罠：非連番の数値キーのまま json_encode すると配列でなくオブジェクトになる／ネストには効かない／元コレクションは変わらない。

概要

values はコレクションの現在の順序を保ったまま、キーを 0..n-1 の連番に詰め直すメソッドです。filter や sortBy 等の後はキーに欠番が残るため、API レスポンスを厳密な配列（list）として返したいときや、ページング・添字アクセスを行いたいときに使います。PHP の array_values 相当の非破壊操作で、チェーンに適します。

構文 / シグネチャ

public function values(): static

引数引数型必須既定値説明なし — — — —
戻り値：Collection（または呼び出し元と同じ具象型）
例外/副作用：例外なし。キーを破棄して0始まりで再採番（順序は維持）。元インスタンスは変更されない。

使用例

最小例

<?php

use Illuminate\Support\Collection;

$users = collect([
    10 => ['id' => 10, 'name' => 'Ann'],
    12 => ['id' => 12, 'name' => 'Bob'],
])->filter(fn ($u) => $u['id'] >= 11); // => キーは [12] のまま

$reindexed = $users->values();         // => キーが [0]
print_r($reindexed->all());
// [ ['id' => 12, 'name' => 'Bob'] ]

実務例（API レスポンスを list として返す）

<?php

use Illuminate\Support\Collection;
use Illuminate\Http\JsonResponse;

$items = collect($repository->latest())  // Eloquent/配列どちらでもOK
    ->sortByDesc('score')                // 並びのみ変わりキーは維持される
    ->values()                           // ここで list 化（0..n-1）
    ->map(fn ($row) => [
        'title' => $row['title'],
        'score' => (int) $row['score'],
    ]);

return new JsonResponse($items); // JSONは厳密な配列として出力

よくある落とし穴・注意

JSON で配列にならない問題：非連番の数値キーを含む配列は json_encode 時にオブジェクト扱いになります。API で list を返す場合は values() を通す。
ネストには効かない：values は最上位のキーのみ再採番。入れ子の配列を詰め直すには、map で各要素に対して collect(...)->values() を適用。
順序はそのまま：再採番しても要素の順序は保持。並び替えは別途 sortBy* 系を使用。
非破壊：元のコレクションは変更されない。更新が必要なら代入またはチェーン継続で。

代替・関連APIとの比較

array_values（PHP）：純配列に対して同様の処理。コレクションチェーン内で使うなら values を選択。
keys：キーだけ取り出す。再採番はしない。
pluck：特定キーの値を抽出。必要に応じて ->pluck(...)->values() で list 化。
sortBy / unique：これらの後はキーが欠番になりがち。->values() を併用。

テスト例（Pest）

<?php

use Illuminate\Support\Collection;

it('reindexes to consecutive integers', function () {
    $c = collect([2 => 'a', 5 => 'b'])->values();
    expect($c->keys()->all())->toBe([0, 1]);
    expect($c->all())->toBe(['a', 'b']);
});

it('keeps order while reindexing', function () {
    $c = collect([3 => 'x', 1 => 'y'])->values();
    expect($c->all())->toBe(['x', 'y']);
});

トラブルシュート（エラー別）

症状/エラー	原因	対処
JSON が配列でなく `{}`（オブジェクト）になる	数値キーが非連番で list 判定に失敗	`->values()` を通して 0..n-1 に再採番
ネスト配列の中が非連番のまま	`values` は最上位のみ	`->map(fn($x) => collect($x)->values())` 等で内側にも適用
順序が意図通りでない	再採番前の順序が不正	`sortBy` / `sortByDesc` で順序を確定してから `values`

コレクション特性（カテゴリ追記）

チェーン可否：可
破壊的/非破壊：非破壊（新インスタンスを返す）
キー保持：破棄し、0 始まりの連番へ
LazyCollection：対応（逐次的に 0..n-1 を割当）
計算量の目安：O(n)
入出力対応表

入力	実行	出力
`[2 => 'a', 5 => 'b']`	`values()`	`[0 => 'a', 1 => 'b']`
`collect([...])->unique('id')`	`values()`	欠番解消・順序維持
`[ ['items' => [2=>'x',9=>'y']] ]`	`values()`	最上位のみ連番（内側はそのまま）

参考リンク

Laravel Docs — Collections: values（英語）: https://laravel.com/docs/12.x/collections#method-values
Laravel API — Illuminate\Support\Collection: https://laravel.com/api/12.x/Illuminate/Support/Collection.html
PHP Manual — array_values: https://www.php.net/array_values