- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::isEmpty - 関連: isNotEmpty / first / count / whenEmpty / whenNotEmpty
- 変更履歴: なし
要点（TL;DR）
- コレクションに要素が 1件もない かを
boolで判定する - 最低限の使い方：
$items->isEmpty() - 罠：LazyCollection（
cursor()等）では 全件走査 になりがち／大規模データで重い／配列に対して呼ぶと「未定義メソッド」
概要
isEmpty はコレクションが空かどうかを簡潔にチェックするメソッドです。ガード句（早期 return）や 404 応答、処理分岐の条件に使われます。配列の empty($arr) 相当ですが、コレクションのチェーンの途中や Eloquent 取得結果に対して安全に使える点が実務で便利です。
構文 / シグネチャ
public function isEmpty(): bool
- 引数
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| なし | — | — | — | — |
- 戻り値：
bool（空ならtrue、1件以上あればfalse） - 例外/副作用：例外なし。LazyCollection では内部的に件数計測のために走査が発生し、大規模データで I/O 負荷・時間増大の可能性あり。
使用例
最小例
<?php
use Illuminate\Support\Collection;
$items = collect([]);
if ($items->isEmpty()) {
echo "empty\n"; // 出力: empty
}
実務例：該当がなければ 404
<?php
use App\Models\User;
use Illuminate\Http\Request;
Route::get('/active-users', function (Request $request) {
$users = User::where('active', true)->get();
abort_if($users->isEmpty(), 404, 'Active users not found.');
return $users;
});
大規模データ（LazyCollection）での安全な判定
<?php
use App\Models\LogEntry;
// cursor() は LazyCollection。isEmpty() は全件走査になり得る。
// 先頭要素の有無だけを見たいなら first() を使うと早い。
$lazy = LogEntry::whereDate('created_at', today())->cursor();
if ($lazy->first() === null) {
// 空
}
よくある落とし穴・注意
- LazyCollection は全走査に注意：
cursor()などのストリーミング取得でisEmpty()は全件カウント相当。先頭有無判定ならfirst() === nullを推奨。 - 配列に対して呼べない：
[]->isEmpty()は不可。配列はcollect($array)->isEmpty()か PHP のempty($array)を使う。 - 「空」定義は要素数のみ：
[null]は空ではありません（false）。値の中身の空判定とは異なる点に注意。
コレクション特性（カテゴリ準拠）
- チェーン可否：不可（
boolを返すためチェーン終了） - 破壊的/非破壊：非破壊
- キー保持：判定のみで変化なし
- LazyCollection：可。ただし 計測のための走査が発生しやすい
- 計算量の目安：通常の
Collection（配列ベース）では O(1)。LazyCollectionは O(n)（件数計測相当）
入出力対応（小さなサンプル）
| 入力 | 例 | isEmpty() |
|---|---|---|
| 空配列のコレクション | collect([]) | true |
| 要素あり | collect([1]) | false |
値が null の要素 | collect([null]) | false |
| Lazy（先頭のみ確認したい） | cursor()->first() === null | 先頭が無ければ「空」相当 |
代替・関連APIとの比較
isNotEmpty()：逆論理（空でなければtrue）。読みやすさ重視で使い分け。first()：先頭要素を返す。Lazy 情報源では 早期判定に有効（first() === null）。count()：件数取得。条件分岐でcount() === 0でも同義だが、可読性はisEmpty()が上。whenEmpty()/whenNotEmpty()：空/非空時の処理をチェーンで分岐したい場合に便利。
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('returns true for empty collection', function () {
expect(collect()->isEmpty())->toBeTrue();
});
it('returns false for non-empty collection', function () {
expect(collect([1])->isEmpty())->toBeFalse();
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
Call to undefined method isEmpty() | 対象が 配列や Paginator 等で、Collection ではない | collect($value)->isEmpty() に変換する／Paginator は count($paginator->items()) など対象型に合わせる |
| 予想外に時間がかかる | cursor() 等の LazyCollection を全走査 | 先頭確認は first() === null、件数が必要なら集約前に条件を絞る・インデックス最適化 |
空なのに false が返る | 要素はあるが 値が空に見える（例：[null]） | 「空＝要素数0」であることを理解し、値の空判定は別途 filter() などで行う |
参考リンク
- Laravel Docs — Collections: isEmpty（12.x）
https://laravel.com/docs/12.x/collections#method-isempty - Laravel Docs — Collections: whenEmpty / whenNotEmpty
https://laravel.com/docs/12.x/collections#method-whenempty - Laravel Docs — Eloquent: Streaming results lazily（cursor）
https://laravel.com/docs/12.x/eloquent#streaming-results-lazily
