掌握 Laravel 查询构建器中的条件查询技巧

本文深入探讨了在 Laravel 8 中利用查询构建器（Query Builder）或 Eloquent 进行动态搜索的最佳实践。针对根据可选请求参数构建复杂查询的场景，文章详细介绍了如何使用 `when` 方法优雅地实现条件查询，避免冗余的 `if` 语句，从而编写出更简洁、可读性更强的代码。

在开发基于 Laravel 的应用程序时，经常需要根据用户提供的可选参数（例如搜索关键词、筛选条件等）动态构建数据库查询。传统的做法是使用一系列 if 语句来判断参数是否存在，然后有条件地向查询链中添加 where 子句。然而，这种方法在面对多个可选条件时，可能导致代码冗长且难以维护。Laravel 提供了一种更为优雅和强大的解决方案：when 方法。

动态查询构建的挑战

考虑一个常见的场景：用户可以通过 URL 查询字符串（如 ?q=john&gender=m）来搜索用户列表。如果 q 或 gender 参数不存在，则不应将其作为查询条件。

初始的尝试可能如下所示：

public function index (Request $request)
{
    $role = getRoleCode($request->role);
    $rolesQuery = Role::where('role', '=', $role); // 注意：这里应是 $rolesQuery 而非 $roles

    if ($request->q) {
        // 错误：$request->$q 是错误的变量引用方式
        $rolesQuery->where('name', 'like', "%$request->$q%");
    }

    if ($request->gender) {
        $rolesQuery->where('gender', '=', $request->gender);
    }

    // 在实际执行查询之前，可能需要将结果赋值给一个变量
    $roles = $rolesQuery->orderBy('id', 'desc')->paginate(20);

    return view('admin.users.index', [
        'roles' => $roles,
        // ... 其他视图数据
    ]);
}

上述代码中存在几个问题：

变量命名不一致，$roles 在条件语句中被当做查询构建器实例，但在最后又被赋值为分页结果。
$request->$q 是一种错误的变量引用方式，正确的应是 $request->q 或 $request->input('q')。
虽然 if 语句可以实现条件查询，但当条件增多时，代码的层级和复杂度会增加，降低可读性。

优雅的解决方案：使用 when 方法

Laravel 的查询构建器和 Eloquent 模型都提供了 when 方法，用于实现条件性地向查询中添加子句。when 方法的签名如下：

when(mixed $value, callable $callback, callable $default = null): static

它接受三个参数：

$value：一个用于判断条件的布尔值或可以被评估为布尔值的值。如果此值为 true（或“真值”），则执行第二个参数 $callback。
$callback：一个闭包函数，它将接收当前查询构建器实例作为第一个参数，以及 $value 作为第二个参数（如果 $value 是一个非布尔值且为真）。
$default (可选)：如果 $value 为 false（或“假值”），则执行此闭包函数。

利用 when 方法，我们可以将上述动态查询重构为以下简洁且高效的形式：

role);

        $roles = Role::where('role', $roleCode)
            // 当 $request->input('q') 非空时，执行闭包添加 name 搜索条件
            ->when($request->input('q'), function ($query, $search) {
                return $query->where('name', 'like', '%' . $search . '%');
            })
            // 当 $request->input('gender') 非空时，执行闭包添加 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'),
        ]);
    }

    // 假设这是一个辅助函数，用于获取角色代码
    protected function getRoleCode($roleName)
    {
        // 实现根据角色名称获取角色代码的逻辑
        // 例如：
        switch ($roleName) {
            case 'supervisor': return 'SUP';
            case 'admin': return 'ADM';
            default: return 'USR';
        }
    }
}

代码解析：

Role::where('role', $roleCode)：这是所有查询的基础条件。
->when($request->input('q'), function ($query, $search) { ... })：
- $request->input('q')：安全地从请求中获取 q 参数的值。如果 q 参数不存在或为空字符串，input() 方法将返回 null 或空字符串，这在布尔上下文中被评估为 false。
- function ($query, $search) { ... }：这是一个闭包函数。
  - $query：代表当前的查询构建器实例。
  - $search：如果 $request->input('q') 的值是“真值”，那么 $search 将接收到 $request->input('q') 的实际值。
  - return $query->where('name', 'like', '%' . $search . '%');：在这个闭包中，我们向查询中添加了 name 字段的模糊搜索条件。务必从闭包中返回 $query 实例，以便继续链式调用。
->when($request->input('gender'), function ($query, $gender) { ... })：同理，这会根据 gender 参数的值添加精确匹配条件。
->orderBy('id', 'DESC')->paginate(20)：最后，应用排序和分页。

注意事项与最佳实践

使用 $request->input()：始终建议使用 $request->input('param_name') 来获取请求参数，因为它比 $request->param_name 更健壮，可以处理 GET 和 POST 请求，并且在参数不存在时返回 null 而不是抛出错误。
链式调用：when 方法的强大之处在于它保持了查询构建器的链式调用特性，使得代码流程清晰。
闭包返回值：在 when 方法的闭包中，一定要返回修改后的 $query 实例，否则后续的链式操作将无法生效。
可读性：when 方法显著提高了代码的可读性和简洁性，特别是当有多个可选条件时。
PHP 7.4+ 箭头函数：如果你的项目使用 PHP 7.4 或更高版本，可以使用箭头函数进一步简化闭包的写法，如示例答案中所示：fn ($query, $search) => $query->where('name', 'like', '%'. $search .'%')。

总结

Laravel 的 when 方法是处理动态条件查询的利器，它提供了一种优雅、高效且可读性强的方式来构建复杂的数据库查询。通过合理运用 when 方法，开发者可以避免冗余的 if 语句，使控制器代码更加简洁和专业，从而提升应用程序的可维护性和开发效率。掌握这一技巧对于任何 Laravel 开发者来说都至关重要。

# php # laravel # app # switch # NULL # if # 字符串 # 闭包 # function # default # input # 数据库 # 重构 # 链式 # 可选 # 不存在 # 子句 # 多个 # 包中 # 这是一个 # 第二个 # 分页 # 所示

返回目录在线咨询

上一篇：网站建设合同关键条款解析与注意事项
下一篇：Vue和Bootstrap的整合思路详解

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

全网整合营销服务商

掌握 Laravel 查询构建器中的条件查询技巧

动态查询构建的挑战

优雅的解决方案：使用 when 方法

注意事项与最佳实践

总结

您的项目需求