laravel的when方法可动态添加查询条件，仅在条件为true时执行对应闭包，支持链式调用多条件、回调判断及else处理，提升查询构造灵活性。
如果您在构建数据库查询时需要根据不同的条件动态添加查询语句，Laravel 提供了 when 方法来简化这一过程。该方法仅在给定条件为 true 时执行对应的查询逻辑，避免了冗余的 if 判断结构。
本文运行环境：macBook Pro，macOS Sonoma
一、基础用法：使用 when 添加条件分支
when 方法接收两个参数：第一个是条件表达式，第二个是闭包函数，用于定义当条件成立时要执行的查询操作。若条件为 false，则跳过该闭包。
1、调用查询构造器并使用 when() 方法传入判断条件和回调函数。
2、在回调函数中通过变量 $query 添加相应的 where 条件。
3、示例代码如下：
User::query()->when($request->has('name'), function ($query) use ($request) {<br> $query->where('name', $request->input('name'));<br> })->get();
二、配合多条件实现复杂筛选逻辑
可以在同一个查询中链式调用多个 when 方法，每个方法处理一个独立的输入参数或业务判断，从而组合出灵活的查询结构。
1、针对不同请求参数分别设置 when 分支。
2、例如同时处理名称、状态和角色过滤：
User::query()<br> ->when($request->filled('name'), fn($q) => $q->where('name', 'like', "%{$request->name}%"))<br> ->when($request->filled('status'), fn($q) => $q->where('status', $request->status))<br> ->when($request->filled('role'), fn($q) => $q->whereHas('roles', fn($r) => $r->where('name', $request->role)))<br> ->get();
三、使用回调返回值作为判断依据
when 的第一个参数可以是一个返回布尔值的回调函数，适用于更复杂的判断场景，比如比较两个字段或调用服务类方法。
2、示例中检查用户是否具有管理员权限：
$isAdmin = fn() => auth()->user()->role === 'admin';<br> User::query()->when($isAdmin(), function ($query) {<br> $query->where('is_active', 1);<br> })->get();
四、提供第三个参数用于 else 情况下的处理
when 方法支持第三个参数，也是一个闭包，用于在条件不满足时执行替代查询逻辑，相当于实现了“if-else”结构。
1、在 when 中添加第三个闭包参数以定义否则操作。
2、示例：根据是否有搜索词决定排序方式：
User::query()<br> ->when(<br> $request->has('search'),<br> fn($q) => $q->where('name', 'like', "%{$request->search}%"),<br> fn($q) => $q->orderBy('created_at', 'desc') // 无搜索时按创建时间排序<br> )<br> ->get();