本文详解 Laravel 中 when() 条件查询方法的正确使用方式，重点纠正常见误区：when() 第一个参数必须是布尔表达式（如 isset($params['key'])），而非直接传入可能为 null 或空字符串的值，否则条件将被跳过。
本文详解 laravel 中 `when()` 条件查询方法的正确使用方式，重点纠正常见误区：`when()` 第一个参数必须是布尔表达式（如 `isset($params['key'])`），而非直接传入可能为 `null` 或空字符串的值，否则条件将被跳过。
在 Laravel 开发中，动态构建 Eloquent 查询是高频场景。传统写法常依赖 isset() + if 判断来控制 where 子句的添加，代码冗长且不易维护。为此，Laravel 提供了链式、函数式风格的 when() 方法，但其行为常被误解——
when() 的第一个参数必须是一个明确返回 true 或 false 的布尔表达式，而不是一个可能为 null、''、0 或 false 的“值”本身
。
❌ 错误用法：直接传入变量值
上述写法不仅存在运行时风险（未检查键是否存在），还违背 when() 的设计意图：它不负责“安全取值”，只负责“基于布尔结果决定是否执行闭包”。
✅ 正确用法：显式判断 + 安全取值
应始终将 isset()（或更健壮的 array_key_exists() / data_get() / Arr::has()）作为 when() 的第一参数：
? 原理说明
when() 方法签名如下（简化版）：
$value：
必须求值为布尔量
。若为 true，执行 $callback；若为 false，跳过。
因此 isset($params['game']) 返回 true/false，语义清晰、安全可靠；
而 $params['game'] 直接使用，既可能报错（键不存在），又可能因 PHP 类型转换导致意外行为（如 '0'、[]、0 均转为 false，但业务上可能需保留这些值）。
? 最佳实践建议
始终优先使用 isset() 或 Arr::has() 检查数组键
，避免未定义索引错误；
若需处理默认值或嵌套结构，搭配 Arr::get($params, 'game', null) 使用；
多个条件可连续链式调用 when()，保持查询构建的可读性与扩展性：
注意：when() 返回的是新查询实例（内部调用 clone），因此
务必重新赋值给变量
（如 $gameQuery = $gameQuery->when(...)），否则链式调用无效。
掌握 when() 的布尔驱动本质，不仅能写出更简洁、更健壮的动态查询，也是深入理解 Laravel 流式 API 设计哲学的关键一步。
$params['game'] = 'fallout';
$gameQuery = Gaming::query();
// ⚠️ 错误！$params['game'] 是字符串 'fallout'，PHP 中非空字符串转布尔为 true —— 看似可行，
// 但若 $params['game'] = null / '' / 0 / false，该条件仍会执行（因 PHP 的松散比较），
// 更严重的是：当键不存在时，$params['game'] 会触发 Undefined Index 警告！
$gameQuery->when($params['game'], function ($query) use ($params) {
$query->where('game', $params['game']);
});use Illuminate\Support\Arr;
$params['game'] = 'fallout';
$gameQuery = Gaming::query();
// ✅ 推荐：使用 isset() 显式检查键存在性
$gameQuery = $gameQuery->when(isset($params['game']), function ($query) use ($params) {
$query->where('game', $params['game']);
});
// ✅ 进阶：支持默认值与类型安全（推荐用于复杂场景）
$gameQuery = $gameQuery->when(Arr::has($params, 'game'), function ($query) use ($params) {
$query->where('game', Arr::get($params, 'game'));
});
// ✅ 扩展：支持多条件 & 复杂逻辑（例如仅当非空字符串时才过滤）
$gameQuery = $gameQuery->when(
isset($params['game']) && trim((string)$params['game']) !== '',
function ($query) use ($params) {
$query->where('game', trim($params['game']));
}
);public function when($value, Closure $callback, Closure $default = null)$query = Gaming::query()
->when(isset($params['game']), fn($q) => $q->where('game', $params['game']))
->when(isset($params['status']), fn($q) => $q->where('status', $params['status']))
->when($params['limit'] ?? null, fn($q) => $q->limit((int)$params['limit']));