本文详解 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 的“值”本身。

❌ 错误用法：直接传入变量值

$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']);
});

上述写法不仅存在运行时风险（未检查键是否存在），还违背 when() 的设计意图：它不负责“安全取值”，只负责“基于布尔结果决定是否执行闭包”。

✅ 正确用法：显式判断 + 安全取值

应始终将 isset()（或更健壮的 array_key_exists() / data_get() / Arr::has()）作为 when() 的第一参数：

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']));
    }
);

? 原理说明

when() 方法签名如下（简化版）：

public function when($value, Closure $callback, Closure $default = null)

• $value：必须求值为布尔量。若为 true，执行 $callback；若为 false，跳过。
• 因此 isset($params['game']) 返回 true/false，语义清晰、安全可靠；
• 而 $params['game'] 直接使用，既可能报错（键不存在），又可能因 PHP 类型转换导致意外行为（如 '0'、[]、0 均转为 false，但业务上可能需保留这些值）。

? 最佳实践建议

• 始终优先使用 isset() 或 Arr::has() 检查数组键，避免未定义索引错误；
• 若需处理默认值或嵌套结构，搭配 Arr::get($params, 'game', null) 使用；
• 多个条件可连续链式调用 when()，保持查询构建的可读性与扩展性：

  $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']));

• 注意：when() 返回的是新查询实例（内部调用 clone），因此务必重新赋值给变量（如 $gameQuery = $gameQuery->when(...)），否则链式调用无效。

掌握 when() 的布尔驱动本质，不仅能写出更简洁、更健壮的动态查询，也是深入理解 Laravel 流式 API 设计哲学的关键一步。