本文将深入探讨在 laravel 8 中，如何利用 eloquent 或 query builder 的 `when` 方法高效且优雅地处理动态搜索和条件查询。通过讲解 `when` 方法的工作原理及其应用，我们将学习如何根据请求参数的有无，灵活地构建数据库查询语句，从而避免冗余的条件判断，提高代码的可读性和可维护性。
在开发Web应用时，动态搜索和过滤功能是常见的需求。用户可能通过URL查询参数（例如 ?q=keyword&gender=m）来筛选数据。传统的做法是使用一系列 if 语句来判断每个参数是否存在，然后有条件地添加 where 子句。虽然这种方法可行，但当条件增多时，代码会变得冗长且难以管理。
传统条件查询的挑战
考虑以下场景，我们希望根据 q（搜索关键词）和 gender（性别）参数来过滤用户列表：
public function index (Request $request)
{
$role = getRoleCode($request->role);
$rolesQuery = Role::where('role', '=', $role);
if ($request->q) {
$rolesQuery->where('name', 'like', "%$request->q%"); // 注意：这里 $request->$q 是错误的写法，应为 $request->q
}
if ($request->gender) {
$rolesQuery->where('gender', '=', $request->gender);
}
$roles = $rolesQuery->orderBy('id', 'desc')->paginate(20);
return view('admin.users.index', [
'roles' => $roles,
// ... 其他视图数据
]);
}上述代码中存在两个主要问题：
- 变量引用错误："$request->$q%" 试图将 $q 作为一个变量名去访问 $request 对象的属性，这会导致错误。正确的做法应该是 "$request->q%" 或更推荐的 $request->input('q')。
- 代码冗余：每个条件都需要一个 if 语句，当条件数量增加时，代码块会变得很长。
解决方案：利用 when 方法进行条件查询
Laravel 的 Eloquent ORM 和 Query Builder 提供了一个非常强大的 when 方法，专门用于处理这种条件性地向查询中添加子句的场景。when 方法的签名如下：
when(mixed $condition, callable $callback, callable $defaultCallback = null): static
- $condition: 这是一个布尔值或可以被评估为布尔值的值。如果 $condition 为 true（或“真值”），则会执行 $callback。
- $callback: 一个匿名函数，它接收当前查询构建器实例作为第一个参数，以及 $condition 的值作为第二个参数（如果 $condition 是非布尔值）。在这个回调中，你可以添加任何你想要的查询子句。
- $defaultCallback (可选): 如果 $condition 为 false（或“假值”），则会执行这个可选的回调。
通过 when 方法，我们可以将上述的条件查询重构为更简洁、更具可读性的形式。
use Illuminate\Http\Request;
use App\Models\Role; // 假设你的模型是 Role
class UserController extends Controller
{
public function index(Request $request)
{
// 假设 getRoleCode 方法获取角色代码
$roleCode = getRoleCode($request->role);
$roles = Role::where('role', $roleCode)
// 当 $request->input('q') 存在且非空时，执行回调函数
->when($request->input('q'), function ($query, $search) {
return $query->where('name', 'like', '%' . $search . '%');
})
// 当 $request->input('gender') 存在且非空时，执行回调函数
->when($request->input('gender'), function ($query, $gender) {
return $query->where('gender', $gender);
})
->orderBy('id', 'DESC')
->paginate(20);
return view('admin.users.index', [
'roles' => $roles,
'role_name' => config('settings.roles')[$roleCode],
'role_en_name' => $request->role,
'q' => $request->input('q'), // 传递已过滤的搜索参数到视图
'gender' => $request->input('gender') // 传递已过滤的性别参数到视图
]);
}
// 假设这是你的辅助函数
private function getRoleCode($roleName)
{
// 实际逻辑可能更复杂，这里仅作示例
return match ($roleName) {
'supervisor' => 'SUP',
'admin' => 'ADM',
default => 'USR',
};
}
}代码解析：
- $request->input('q')：我们使用 input() 方法来安全地获取请求参数。如果参数不存在，input() 会返回 null，这在 when 方法中被评估为 false，从而不会执行对应的查询回调。
- when($request->input('q'), function ($query, $search) { ... })：
- $request->input('q') 作为第一个参数，如果它有值（即用户在URL中提供了 q 参数），则条件为真。
- 回调函数被执行，并接收当前的 $query 实例和 $search（即 $request->input('q') 的值）。
- 在回调中，我们安全地构建了 where('name', 'like', '%' . $search . '%') 子句。
- 对于 gender 参数也采用了相同的逻辑。
when 方法的优势
- 简洁性：消除了多个 if 语句，使代码更加紧凑和易读。
- 可读性：查询逻辑流更加清晰，一眼就能看出哪些条件是动态添加的。
- 链式调用：完美融入 Laravel 的链式调用风格，提高了开发效率。
- 健壮性：when 方法结合 request()->input() 可以优雅地处理请求参数缺失的情况，避免了不必要的错误或复杂的条件检查。
注意事项
- $request->input() vs. $request->property: 建议使用 $request->input('key') 而不是 $request->key 来获取请求参数。input() 方法在参数不存在时会返回 null，这对于 when 方法的条件判断非常有用。而直接访问属性 $request->key 在参数不存在时可能会导致意外行为或报错（尽管 Laravel 通常会返回 null）。
- 复杂条件: 如果你的条件逻辑本身很复杂，或者需要根据多个请求参数来决定是否添加一个子句，你可以在 when 的第一个参数中放置一个更复杂的布尔表达式。
- 默认回调: 了解 when 方法的第三个参数 defaultCallback。如果你的查询在条件不满足时需要执行不同的逻辑，可以使用它。
总结
Laravel 的 when 方法是处理动态条件查询的强大工具，它使得构建灵活、可维护的搜索和过滤功能变得异常简单。通过将条件判断与查询逻辑分离，when 方法显著提升了代码的简洁性和可读性，是每个 Laravel 开发者都应该掌握的技巧。在需要根据用户输入动态调整查询逻辑的场景下，优先考虑使用 when 方法，它将帮助你编写出更优雅、更专业的 Laravel 代码。
