range — 連番のコレクションを生成する静的メソッド

カテゴリ: collection
掲載バージョン: Laravel 12・PHP 8.4
名前空間 / FQCN / コマンド: Illuminate\Support\Collection::range
関連: times / nth / slice / Illuminate\Support\LazyCollection::range / PHP range()
変更履歴: 既存機能（Laravel 6+ 継続）

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

要点（TL;DR）

何に使うか：開始値から終了値までの連番をコレクションとして作る。
最低限の使い方：Collection::range(1, 5)->all(); // [1,2,3,4,5] (Laravel)
よくある罠
- インスタンスでは呼べない（静的メソッド）。
- step（増分）指定は不可。必要なら PHP range() を collect() する。(php.net)
- 大量レンジはメモリ圧迫。必要に応じて LazyCollection を使う。(josephsilber.com)

概要

Collection::range($from, $to) は、指定区間の整数列を生成して新しいコレクションを返します。クエリ結果が不要でも、連番の ID・ページ番号・ダミーデータのキーなどを簡潔に作れます。ほとんどのコレクション API と同様に非破壊で、チェーンして加工できます。メモリ使用量が気になる場合は LazyCollection::range を検討してください。(Laravel, afterlogic.com)

構文 / シグネチャ

use Illuminate\Support\Collection;

// 連番（両端を含む）を生成して新しいコレクションを返す
public static function range(int $from, int $to): \Illuminate\Support\Enumerable;

引数（表） 引数型必須既定値説明 $from int ✔ — 開始値（含む） $to int ✔ — 終了値（含む）
戻り値：Collection<int,int>（Enumerable を実装する新しいコレクション）。(Laravel API)
例外/副作用：特になし。ただし要素数に比例してメモリを確保します。大量生成は LazyCollection::range で回避可能。(josephsilber.com)

使用例

最小例

<?php

use Illuminate\Support\Collection;

$numbers = Collection::range(1, 5);
// [1, 2, 3, 4, 5]

echo $numbers->implode(','); // 1,2,3,4,5

実務例：月別レポート行のプレースホルダ生成

<?php

use Carbon\Carbon;
use Illuminate\Support\Collection;

// 当年の1〜12月を連番→ラベルに変換
$months = Collection::range(1, 12)
    ->map(fn (int $m) => Carbon::create(null, $m, 1)->format('Y-m'))
    ->keyBy(fn ($ym) => $ym)         // 'YYYY-mm' をキーに
    ->map(fn () => ['count' => 0]);  // 初期値をセット

// 例：DB集計結果を上書きマージ
// $stats = ['2025-01' => 12, '2025-03' => 7, ...];
foreach ($stats as $ym => $count) {
    if ($months->has($ym)) {
        $months[$ym]['count'] = $count;
    }
}

実務例：巨大レンジを遅延評価でストリーム処理

<?php

use Illuminate\Support\LazyCollection;

// 1 から始まる自然数を必要分だけ処理
LazyCollection::range(1, PHP_INT_MAX)
    ->filter(fn ($n) => $n % 3 === 0)
    ->take(5)
    ->each(function ($n) {
        // 3, 6, 9, 12, 15 を順に処理（メモリ低負荷）
    });

LazyCollection::range は必要な分だけ生成して処理でき、巨大データでのメモリ負荷を抑えられます。(afterlogic.com, josephsilber.com)

よくある落とし穴・注意

静的メソッド：collect()->range() は不可。Collection::range() を呼ぶ。(Laravel)
step 指定不可：Collection::range は増分を受け取りません。collect(range($from, $to, $step)) か、生成後に nth($step) を使う。(php.net, Laravel)
大量生成は注意：100万件などはヒープを消費。LazyCollection::range＋take() 等で絞る。(josephsilber.com)
順序制御：降順や間引きは後段で reverse() / sortDesc() / nth() を利用。(stillat.com, Laravel)

代替・関連APIとの比較

PHP range()：step 指定が可能。配列で返るため collect() してチェーンしたい時は Laravel のコレクションに包む。(php.net)
times($n)：回数指定で 1..n を作る。開始値や終了値を細かく制御したいなら range。(Laravel)
nth($step, $offset=0)：既存コレクションからn個おきに抽出。ステップ付きの疑似レンジとして使える。(Laravel)
LazyCollection::range：メモリ効率重視ならこちら。(afterlogic.com)

テスト例（Pest）

<?php

use Illuminate\Support\Collection;

it('builds inclusive integer range', function () {
    $range = Collection::range(1, 5);
    expect($range->all())->toBe([1,2,3,4,5]);
});

it('chains with map and filter', function () {
    $evens = Collection::range(1, 10)->filter(fn ($n) => $n % 2 === 0);
    expect($evens->values()->all())->toBe([2,4,6,8,10]);
});

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

症状/エラー	原因	対処
`Call to undefined method ...->range()`	インスタンスに対して呼び出している	`Collection::range()`（静的）で呼ぶ
`Allowed memory size exhausted`	生成数が大きすぎる	`LazyCollection::range`＋`take()` / `filter()` で絞る
「step が指定できない」	仕様	`collect(range($from, $to, $step))` か `nth($step)` を使用
想定と違う並び順	後段処理で順序変更が必要	`reverse()` / `sortDesc()` を明示的に適用

参考リンク

Laravel 公式ドキュメント：Collections（メソッド一覧に range を掲載） (Laravel)
Laravel API（9.x の例）：Illuminate\Support\Collection::range(int $from, int $to) シグネチャ (Laravel API)
Lazy Collections 解説（Joseph Silber） (josephsilber.com)
PHP 公式：range()（step 指定などの仕様） (php.net)

コレクション固有メモ

チェーン可否：可（非破壊）
破壊的/非破壊：非破壊（新しいコレクションを返す）(Laravel)
キー保持：0 からの再採番（連番値のコレクション）
LazyCollection：LazyCollection::range あり（巨大レンジ向け）(afterlogic.com)
計算量目安：生成 O(n)、後段処理は各メソッドに準ずる

入出力対応（小サンプル）

呼び出し	結果（values）
`Collection::range(1, 3)`	`[1, 2, 3]`
`Collection::range(0, 0)`	`[0]`