between — 値・文字数・件数が範囲内かを検証するルール

カテゴリ: validation
掲載バージョン: Laravel 12・PHP 8.4
名前空間 / FQCN / コマンド: between（バリデーションルール）, Illuminate\Validation\Rules\Between
関連: min / max / size / digits_between
変更履歴: 初期から存在する基本ルール。Laravel 10〜12 での挙動差分はほぼなし。

要点（TL;DR）

何に使うか：数値・文字列・配列・ファイルサイズが、指定した最小値〜最大値の範囲内かどうかをチェックする。
最低限の使い方：'age' => 'integer|between:18,65'
よくある罠
- 型によって「何が between の対象か」が変わる（数値／文字数／配列要素数／ファイルサイズKB）。
- 数値範囲チェックなのに integer / numeric を付け忘れる。
- between は 境界値を含む（18〜65なら18と65もOK）。

概要

between ルールは、ある値が「最小値〜最大値の範囲内か」を検証します。
数値・文字列・配列・ファイルアップロードに対して使用でき、型ごとに「範囲」の意味が変わります。フォームの年齢制限、タイトルの文字数、タグの数、アップロードサイズ制限など、実務で頻出のルールです。

構文 / シグネチャ

// 文字列ルールとして
'field' => 'between:min,max';

// 配列での指定
'field' => ['between:min,max'];

// Rule オブジェクトとして
use Illuminate\Validation\Rules\Between;

'field' => [new Between($min, $max)];

引数

引数	型	必須	既定値	説明
min	int\|float	✔	なし	許可する最小値
max	int\|float	✔	なし	許可する最大値

※ ルール文字列では between:3,10 のようにカンマ区切りで指定します。

判定対象（型ごとの意味）

型	対象になるもの	例
numeric	数値の値	`between:0,100` は値が0〜100
string	文字数（マルチバイト含む）	`between:3,50` は3〜50文字
array	要素数	`between:1,5` は1〜5要素
file	ファイルサイズ(KB)	`between:10,2048` は10〜2048KB

戻り値

バリデーションとしては true（通過）／false（失敗）
実際には Validator がエラーメッセージをコレクションとして保持し、失敗時に ValidationException が投げられます。

例外 / 副作用

FormRequest や validate() で失敗した場合、Illuminate\Validation\ValidationException が投げられ、Webリクエストなら自動リダイレクト＋エラーメッセージがセッションに保存されます。
モデルやDBへの変更など、直接の副作用はありません。

使用例

最小例（単体スクリプトでの利用）

<?php

use Illuminate\Support\Facades\Validator;

$data = ['age' => 25];

$validator = Validator::make($data, [
    'age' => 'required|integer|between:18,65',
]);

if ($validator->fails()) {
    // ["age は 18 から 65 の間で指定してください。"] のようなメッセージ
    dd($validator->errors()->all());
}

echo "OK\n";

実務例（コントローラでのフォームバリデーション）

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class EpisodeController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            // タイトルは 3〜80 文字
            'title' => 'required|string|between:3,80',

            // タグは 1〜10 個
            'tags'  => 'nullable|array|between:1,10',
            'tags.*' => 'string|max:20',

            // 画像は 10KB〜5MB
            'cover_image' => 'nullable|image|between:10,5120',
        ]);

        // $validated を使って保存処理…
    }
}

FormRequest での利用例

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'age' => 'required|integer|between:18,65',
        ];
    }
}

通過 / 失敗ケース一覧

between:3,5 を例にします。

型	値	結果	説明
numeric	`2`	失敗	3 未満
numeric	`3`	通過	下限を含む
numeric	`5`	通過	上限を含む
numeric	`6`	失敗	5 を超える
string	`"ab"`	失敗	文字数 2
string	`"abc"`	通過	文字数 3
string	`"abcdef"`	失敗	文字数 6
array	`[]`	失敗	要素数 0
array	`['a','b','c']`	通過	要素数 3
file	2KB	失敗	3KB未満
file	4KB	通過	3〜5KB の範囲内

カスタムメッセージ・属性名

resources/lang/ja/validation.php に between 用のメッセージを定義できます。

// resources/lang/ja/validation.php の一部
return [
    'between' => [
        'numeric' => ':attribute は :min〜:max の間で指定してください。',
        'file'    => ':attribute は :min〜:max KB のファイルにしてください。',
        'string'  => ':attribute は :min〜:max 文字で入力してください。',
        'array'   => ':attribute は :min〜:max 個の要素を含めてください。',
    ],
];

特定フィールドだけ変えたい場合:

$messages = [
    'age.between' => '年齢は :min 歳以上 :max 歳以下で入力してください。',
];

$request->validate([
    'age' => 'required|integer|between:18,65',
], $messages);

条件付き（sometimes）での利用例

任意入力だが、入力されていたら範囲チェックしたいケース:

use Illuminate\Support\Facades\Validator;

$data = ['discount_rate' => 120];

$validator = Validator::make($data, [
    'discount_rate' => ['sometimes', 'numeric', 'between:0,100'],
]);

if ($validator->fails()) {
    // 入力があれば 0〜100 の範囲でチェックされる
}

よくある落とし穴・注意

型ごとの意味を取り違える
- 数値範囲だと思っていたが実は文字数を見ていた、という事故が多いです。
  → 数値なら必ず integer / numeric などとセットで書く。
上下限が “含まれる” ことを忘れる
- 「18〜65歳以下」を表現するなら between:18,65 でOK。
  「18歳超〜65歳未満」は gt:18|lt:65 を検討。
ファイルの between は「サイズ(KB)」
- 画像の縦横サイズを制限したい場合は dimensions ルールを使う。
配列に使うと「要素数」が対象
- 中身の値ではなく件数をチェックする点に注意。

代替・関連APIとの比較

min / max
- 片側のみ制限したいとき（下限だけ・上限だけ）。
- 「18歳以上なら何歳でもOK」など。
size
- ちょうど特定の数・文字数・件数・KB だけ許可したいとき。
digits_between
- 数値の「桁数」を制限したいときに使用（例：電話番号など）。
gt / gte / lt / lte
- 厳密に不等号を使いたい場合（境界値を含めたくない／含めたいなど細かく指定したいとき）。

選定の目安

「範囲（最小〜最大）が決まっている」→ between
「片側だけ決まっている」→ min / max
「境界値の含め方を細かく制御したい」→ gt / gte / lt / lte
「桁数の範囲」→ digits_between

テスト例（Pest）

<?php

use Illuminate\Support\Facades\Validator;

it('validates age is between 18 and 65', function () {
    $validator = Validator::make(['age' => 20], [
        'age' => 'required|integer|between:18,65',
    ]);

    expect($validator->passes())->toBeTrue();

    $validatorFail = Validator::make(['age' => 70], [
        'age' => 'required|integer|between:18,65',
    ]);

    expect($validatorFail->fails())->toBeTrue();
});

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

症状/エラー	原因	対処
「The age must be between 18 and 65.」などの英語メッセージ	日本語の言語ファイルが未設定／`locale` が `en` のまま	`config/app.php` の `locale` を `ja` にし、ja言語ファイルを配置
数値を入れているのに `between` に落ちる	`string` として評価されている（`numeric` 未指定）	ルールに `integer` / `numeric` を追加する
ファイルで期待と違う挙動をする	KB 単位のサイズを理解していない	`between:1024,5120` など、KB換算して指定する
配列で件数が合っているのにエラー	`nullable` を付け忘れ、null も検証対象になっている	任意項目なら `nullable

参考リンク

Laravel Docs – Validation: Available Validation Rules（between）
https://laravel.com/docs/12.x/validation#rule-between
Laravel API – Illuminate\Validation\Rules\Between
https://laravel.com/api/12.x/Illuminate/Validation/Rules/Between.html
Laravel Docs – Validation: Error Messages
https://laravel.com/docs/12.x/validation#custom-error-messages