Laravel 8 查询构建器：高效实现条件搜索与动态过滤-php教程-PHP中文网

Laravel 8 查询构建器：高效实现条件搜索与动态过滤

花韻仙語

发布： 2025-11-29 11:01:01

原创

341人浏览过

Laravel 8 查询构建器：高效实现条件搜索与动态过滤

本文详细介绍了在 laravel 8 中如何利用查询构建器（query builder）或 eloquent orm 实现基于 url 查询参数的动态搜索与过滤功能。重点阐述了 `when` 方法的用法，通过条件判断优雅地向查询中添加 `where` 子句，从而避免了冗余代码，提升了代码的可读性和维护性，是处理可选搜索条件的推荐实践。

在开发 Web 应用时，基于用户输入的查询参数实现动态搜索和过滤功能是常见的需求。例如，一个管理系统可能需要根据 URL 中的 q (搜索关键词) 或 gender (性别) 参数来过滤用户列表。在 Laravel 中，优雅地处理这类可选的查询条件，是提升代码质量的关键。

动态查询条件的挑战

当我们需要根据 URL 查询字符串（如 http://127.0.0.1:8000/admin/users/supervisor?q=john&gender=m）来动态构建数据库查询时，一个常见的误区是直接将所有可能的 where 子句链式调用，而不考虑参数是否存在。

例如，以下代码在 q 或 gender 参数不存在时，会导致查询错误或行为异常：

// 潜在问题代码示例
$roles = Role::where('role', '=', $role)
    ->where('name', 'like', "%$request->$q%") // 如果 $request->q 不存在，会出错
    ->where('gender', '=', $request->gender)   // 如果 $request->gender 不存在，会出错
    ->orderBy('id', 'desc')
    ->paginate(20);

登录后复制

其根本原因在于，当 $request-youjiankuohaophpcnq 或 $request->gender 不存在时，它们的值可能为 null，导致 where 子句的条件不正确或抛出异常。为了解决这个问题，一种直观的方法是使用 if 语句进行条件判断：

// 使用 if 语句实现条件查询
public function index (Request $request)
{
    $role = getRoleCode($request->role);
    $rolesQuery = Role::where('role', '=', $role); // 初始化查询构建器

    if ($request->has('q')) { // 使用 has() 方法检查参数是否存在
        $rolesQuery->where('name', 'like', '%'. $request->input('q') .'%'); // 使用 input() 安全获取参数
    }

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

    $roles = $rolesQuery->orderBy('id', 'desc')->paginate(20);

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

登录后复制

这种方法是有效的，但当条件增多时，代码会显得冗长且链式调用的流畅性被中断。

Laravel when 方法：优雅的条件查询

Laravel 的查询构建器和 Eloquent ORM 提供了一个更优雅的解决方案：when 方法。when 方法允许你根据一个布尔条件来决定是否执行某个查询子句，从而使代码更加简洁和富有表现力。

WowTo

用AI建立视频知识库

查看详情

when 方法的签名如下：

->when(mixed $condition, callable $callback, callable $defaultCallback = null)

登录后复制

$condition: 这是一个混合类型的值。如果它评估为 true（或非空、非零），则会执行 $callback。如果它评估为 false（或空、零），则如果提供了 $defaultCallback，则执行 $defaultCallback。
$callback: 这是一个闭包函数，它接收当前的查询构建器实例作为第一个参数，以及 $condition 的值（如果 $condition 不是布尔值）作为第二个参数。
$defaultCallback: （可选）当 $condition 为 false 时执行的闭包函数。

使用 when 方法重构动态搜索：

use Illuminate\Http\Request;
use App\Models\Role; // 假设你的模型是 Role

public function index (Request $request)
{
    // 假设 getRoleCode() 函数用于获取角色编码
    $roleCode = getRoleCode($request->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->q,
        'gender' => $request->gender
    ]);
}

登录后复制

代码解析：

Role::where('role', $roleCode): 首先构建基础查询，筛选出特定角色的用户。
->when($request->input('q'), function ($query, $search) { ... }):
- $request->input('q') 作为 when 方法的第一个参数（$condition）。input() 方法会安全地获取请求参数，如果参数不存在则返回 null。在 PHP 中，null 会被评估为 false，非空字符串则评估为 true。
- 如果 q 参数存在且有值，则闭包会被执行。闭包接收当前查询构建器实例 $query 和 $request->input('q') 的值 $search。
- 在闭包内部，我们通过 $query->where('name', 'like', '%'. $search .'%') 添加了 name 字段的模糊搜索条件。
->when($request->input('gender'), function ($query, $gender) { ... }):
- 类似地，这行代码根据 gender 参数是否存在和有值，来添加 gender 字段的精确匹配条件。
->orderBy('id', 'DESC')->paginate(20): 最后，应用排序和分页。

这种方式的优点在于：

简洁性：将条件判断和查询构建融为一体，代码更紧凑。
可读性：链式调用使得查询逻辑一目了然。
安全性：$request->input() 自动处理参数不存在的情况，when 方法则进一步确保只有在条件满足时才添加查询子句。

注意事项与最佳实践

使用 request()->input() 或 $request->input(): 始终使用这些方法来获取请求参数，它们比直接访问 $request->q 更安全，因为它们在参数不存在时会返回 null，避免潜在的错误。
通配符处理: 对于 LIKE 搜索，确保正确地在搜索关键词前后添加 % 通配符。
默认值与验证: 考虑为搜索参数设置默认值，或者在控制器中对请求参数进行验证，以确保数据的有效性。
复杂条件: 对于更复杂的条件逻辑，你可以在 when 闭包内部使用 orWhere、whereHas 等更高级的查询方法。
代码可维护性: 当搜索条件非常多时，可以考虑将查询逻辑封装到自定义的查询作用域（Scope）中，或者使用管道模式（Pipeline Pattern）来进一步提高代码的可维护性。