Laravel分页：Builder转Paginator详解

学习文章要努力，但是不要急！今天的这篇文章《Laravel分页：Builder转Paginator方法解析》将会介绍到等等知识点，如果你想深入学习文章，可以关注我！我会持续更新相关文章的，希望对大家都能有所帮助！

在使用Laravel进行数据分页时，开发者常会遇到“Call to undefined method Illuminate\Database\Eloquent\Builder::links()”错误。这通常是由于未正确捕获paginate()方法返回的分页器（Paginator）实例所致。paginate()是一个终端操作，它会执行查询并返回一个专门用于分页的对象，而不是继续返回查询构建器（Query Builder）实例。本文将深入解析这一问题，并提供正确的解决方案，确保Laravel分页功能正常工作。

理解Laravel查询构建器与分页器

在Laravel中，当我们使用Eloquent模型或DB门面构建查询时，我们操作的是一个Illuminate\Database\Eloquent\Builder（对于Eloquent）或Illuminate\Database\Query\Builder（对于DB门面）实例。这些实例提供了一系列链式方法，如select(), where(), join(), orderBy()等，用于逐步构建SQL查询。

然而，像get(), first(), count()以及paginate()这样的方法是“终端操作”或“执行操作”。它们的作用是执行之前构建的查询，并返回查询结果。特别地，paginate()方法会执行查询并返回一个Illuminate\Pagination\LengthAwarePaginator或Illuminate\Pagination\Paginator实例，而不是原有的查询构建器实例。

Laravel的links()方法是Paginator实例特有的，用于生成分页链接的HTML。如果尝试在一个Builder实例上调用links()，就会抛出Call to undefined method错误，因为Builder类并没有这个方法。

错误示例分析

考虑以下Laravel控制器中的postFilter方法，它用于处理带过滤条件的数据查询：

public function postFilter(Request $request)
{
    try {
        $con = 'mysql_prod';

        $items = Item::on($con)->select(['items.name AS item_name', 'items.slug', 'items.id AS item_id', 'item_details.sticker_number', 'item_details.section', 'item_details.type', 'collections.name AS collections_name', 'collections.sport_type', 'collections.league', 'collections.year as collections_year', 'images.file_name'])
            ->leftJoin('item_details', 'items.id', '=', 'item_details.items_id')
            ->leftJoin('collections', 'items.collections_id', '=', 'collections.id')
            ->leftJoin('images', 'images.items_id', '=', 'items.id');

        // 应用过滤条件
        if (!is_null($request->select_collection_field)) {
            $items->where('collections.id', '=', intval($request->select_collection_field));
        }

        if (!is_null($request->select_filter_field)) {
            if ($request->select_filter_field === "select_all") $items->orderBy('item_name', 'desc');
            if ($request->select_filter_field === "publishing_year") $items->orderBy('collections_year', 'desc');
        }

        // 错误的用法：paginate()的返回值未被捕获
        $items->limit(500)->paginate(10); // $items 变量仍然是 Query Builder 实例

        // ... 其他过滤条件和数据获取 ...

        return view('index', compact('items', 'condition', 'collection'));

    } catch (\Exception $e) {
        Log::error($e);
        report($e);
    }
}

在上述代码中，尽管调用了$items->limit(500)->paginate(10);，但$items变量本身并未被重新赋值为paginate()方法的返回值。因此，当视图中尝试调用$items->links()时，$items仍然是一个Illuminate\Database\Eloquent\Builder实例，而不是期望的分页器实例，从而导致错误。

正确的解决方案

解决此问题的关键在于，必须将paginate()方法的返回值重新赋值给用于视图的变量。

public function postFilter(Request $request)
{
    try {
        $con = 'mysql_prod';

        $query = Item::on($con)->select(['items.name AS item_name', 'items.slug', 'items.id AS item_id', 'item_details.sticker_number', 'item_details.section', 'item_details.type', 'collections.name AS collections_name', 'collections.sport_type', 'collections.league', 'collections.year as collections_year', 'images.file_name'])
            ->leftJoin('item_details', 'items.id', '=', 'item_details.items_id')
            ->leftJoin('collections', 'items.collections_id', '=', 'collections.id')
            ->leftJoin('images', 'images.items_id', '=', 'items.id');

        // 应用过滤条件
        if (!is_null($request->select_collection_field)) {
            $query->where('collections.id', '=', intval($request->select_collection_field));
        }

        if (!is_null($request->select_filter_field)) {
            if ($request->select_filter_field === "select_all") $query->orderBy('item_name', 'desc');
            if ($request->select_filter_field === "publishing_year") $query->orderBy('collections_year', 'desc');
        }

        // 正确的用法：将 paginate() 的返回值赋值给 $items 变量
        $items = $query->limit(500)->paginate(10); // $items 现在是 Paginator 实例

        // ... 其他过滤条件和数据获取 ...
        $condition = Condition::on($con)->select(['id', 'name AS condition_name'])
            ->distinct()
            ->get();
        $collection = Collection::on($con)->select(['id', 'name AS collection_name'])
            ->distinct()
            ->orderBy('collection_name', 'ASC')
            ->get();

        return view('index', compact('items', 'condition', 'collection'));

    } catch (\Exception $e) {
        Log::error($e);
        report($e);
    }
}

在上述修正后的代码中，我们首先将查询构建过程赋值给一个临时变量（例如$query），然后将$query->limit(500)->paginate(10)的执行结果重新赋值给$items变量。这样，当$items被传递到视图时，它就是一个合法的Paginator实例，从而可以成功调用links()方法。

对于初始加载视图的方法getSearchView，也应采用相同的逻辑：

public function getSearchView()
{
    try {
        $con = 'mysql_prod';

        // search results
        $items = Item::on($con)->select(['items.name AS item_name', 'items.slug', 'items.id AS item_id', 'item_details.sticker_number', 'item_details.section', 'item_details.type', 'collections.name AS collections_name', 'collections.sport_type', 'collections.league', 'collections.year as collections_year', 'images.file_name'])
            ->leftJoin('item_details', 'items.id', '=', 'item_details.items_id')
            ->leftJoin('collections', 'items.collections_id', '=', 'collections.id')
            ->leftJoin('images', 'images.items_id', '=', 'items.id')
            ->limit(500)
            ->paginate(10); // 这里已经正确捕获了 paginate() 的返回值

        // filter field
        $condition = Condition::on($con)->select(['id', 'name AS condition_name'])
            ->distinct()
            ->get();
        $collection = Collection::on($con)->select(['id', 'name AS collection_name'])
            ->distinct()
            ->orderBy('collection_name', 'ASC')
            ->get();

        return view('index', compact('items', 'condition', 'collection'));
    } catch (\Exception $e) {
        Log::error($e);
        report($e);
    }
}

可以看到，getSearchView方法中的$items = ... ->paginate(10);这一行本身就是正确的赋值操作，因此它不会出现同样的问题。

注意事项与最佳实践

1. 始终捕获终端操作的返回值： 无论是paginate()、get()、first()还是count()，这些方法都会返回查询结果，而不是原始的查询构建器。务必将它们的返回值赋给相应的变量。
2. 变量命名清晰： 在构建复杂查询时，可以使用不同的变量名来区分查询构建器实例和最终结果，例如$queryBuilder和$results，以增强代码可读性。
3. Blade视图中的分页链接： 在Blade模板中，使用{!! $items->links() !!}（或指定视图{!! $items->links('vendor.pagination.default') !!}）来渲染分页链接。{!! !!}用于输出未转义的HTML。
4. 统一处理： 确保所有返回分页数据的控制器方法都遵循相同的模式，正确处理paginate()的返回值，以保证用户体验的一致性。

总结

Call to undefined method Illuminate\Database\Eloquent\Builder::links()错误是Laravel开发者在使用分页功能时常见的陷阱。其根本原因在于混淆了查询构建器实例和分页器实例。通过理解paginate()方法作为终端操作的特性，并确保将其返回的分页器实例正确赋值给视图所使用的变量，可以有效解决此问题，使Laravel的分页功能正常工作。掌握这一核心概念，将有助于编写更健壮、更符合Laravel框架设计哲学的代码。

理论要掌握，实操不能落！以上关于《Laravel分页：Builder转Paginator详解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！