[ Laravel 5.3 文档 ] 数据库 —— 分页

1、简介

在其他框架中,分页是件非常痛苦的事,Laravel的分页器集成了查询构建器Eloquent ORM,并且开箱提供了方便的、易于使用的、基于数据库结果集的分页。分页器生成的HTML兼容Bootstrap CSS 框架

2、基本使用

基于查询构建器进行分页

有多种方式实现分页,最简单的方式就是使用查询构建器或Eloquent模型的paginate方法。该方法基于当前用户查看页自动设置合适的偏移(offset)和限制(limit)。默认情况下,当前页通过HTTP请求查询字符串参数?page的值判断。当然,该值由Laravel自动检测,然后自动插入分页器生成的链接中。

让我们先来看看如何在查询上调用paginate方法。在本例中,传递给paginate的唯一参数就是你每页想要显示的数目,这里我们指定每页显示15个:

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use App\Http\Controllers\Controller;

class UserController extends Controller{
    /**
     * 显示应用中的所有用户
     *
     * @return Response
     */
    public function index()
    {
        $users = DB::table('users')->paginate(15);
        return view('user.index', ['users' => $users]);
    }
}

注:目前,使用groupBy的分页操作不能被Laravel有效执行,如果你需要在分页结果中使用groupBy,推荐你手动查询数据库然后创建分页器。

简单分页

如果你只需要在分页视图中简单的显示“下一页”和“上一页”链接,可以使用simplePaginate方法来执行一个更加高效的查询。在渲染包含大数据集的视图且不需要显示每个页码时这一功能非常有用:

$users = DB::table('users')->simplePaginate(15);

基于Eloquent结果集进行分页

你还可以对Eloquent查询结果进行分页,在本例中,我们对User模型进行分页,每页显示15条记录。正如你所看到的,该语法和基于查询构建器的分页差不多:

$users = App\User::paginate(15);

当然,你可以在设置其它约束条件之后调用paginate,比如where子句:

$users = User::where('votes', '>', 100)->paginate(15);

在对Eloquent模型进行分页时你也可以使用simplePaginate方法:

$users = User::where('votes', '>', 100)->simplePaginate(15);

手动创建分页器

有时候你可能想要通过传递数组数据来手动创建分页实例,你可以基于自己的需求通过创建Illuminate\Pagination\PaginatorIlluminate\Pagination\LengthAwarePaginator实例来实现。

Paginator类不需要知道结果集中数据项的总数;不过,正因如此,该类也没有提供获取最后一页索引的方法。

LengthAwarePaginator接收参数和Paginator几乎一样,只是,它要求传入结果集的总数。

换句话说,Paginator 对应simplePaginate方法,而LengthAwarePaginator对应paginate方法。

注:当手动创建分页器实例的时候,应该手动对传递到分页器的结果集进行“切片”,如果你不确定怎么做,查看PHP函数array_slice

3、显示分页结果

当调用paginate方法时,你将获取Illuminate\Pagination\LengthAwarePaginator实例,而调用方法simplePaginate时,将会获取Illuminate\Pagination\Paginator实例。这些对象提供相关方法描述这些结果集,除了这些辅助函数外,分页器实例本身就是迭代器,可以像数组一样对其进行循环调用。

所以,获取到结果后,可以按如下方式使用Blade显示这些结果并渲染页面链接:

<div class="container">
    @foreach ($users as $user)
        {{ $user->name }}
    @endforeach
</div>

{{ $users->links() }}

links方法将会将结果集中的其它页面链接渲染出来。每个链接已经包含了?page查询字符串变量。记住,render方法生成的HTML兼容Bootstrap CSS 框架

自定义分页链接

setPath方法允许你生成分页链接时自定义分页器使用的URI,例如,如果你想要分页器生成形如http://example.com/custom/url?page=N的链接,应该传递custom/urlsetPath方法:

Route::get('users', function () {
    $users = App\User::paginate(15);
    $users->setPath('custom/url');
    //
});

添加参数到分页链接

你可以使用appends方法添加查询参数到分页链接查询字符串。例如,要添加&sort=votes到每个分页链接,应该像如下方式调用appends

{{ $users->appends(['sort' => 'votes'])->links() }}

如果你想要添加”哈希片段”到分页链接,可以使用fragment方法。例如,要添加#foo到每个分页链接的末尾,像这样调用fragment方法:

{{ $users->fragment('foo')->links() }}

将结果转化为JSON

Laravel分页器结果类实现了Illuminate\Contracts\Support\JsonableInterface契约并提供了toJson方法,所以将分页结果转化为JSON非常简单。你还可以简单通过从路由或控制器动作返回分页器实例将转其化为JSON:

Route::get('users', function () {
    return App\User::paginate();
});

从分页器转化来的JSON包含了元信息如totalcurrent_pagelast_page等等,实际的结果对象数据可以通过该JSON数组中的data键访问。下面是一个通过从路由返回的分页器实例创建的JSON例子:

{
    "total": 50,
    "per_page": 15,
    "current_page": 1,
    "last_page": 4,
    "next_page_url": "http://laravel.app?page=2",
    "prev_page_url": null,
    "from": 1,
    "to": 15,
    "data":[
        {
            // Result Object
        },
        {
            // Result Object
        }
    ]
}

4、自定义分页视图

默认情况下,用于渲染分页链接的视图兼容于Bootstrap CSS框架,如果你没有使用Bootstrap,可以自定义视图来渲染这些链接。当调用分页器实例上的links方法时,传递视图名称作为第一个参数:

{{ $paginator->links('view.name') }}

不过,自定义分页视图最简单的方式是使用vendor:publish命令导出视图文件到resources/views/vendor目录:

php artisan vendor:publish --tag=laravel-pagination

该命令会将视图放到resources/views/vendor/pagination目录,该目录下的default.blade.php文件对应默认的视图文件,编辑该文件即可修改分页HTML。

5、分页器实例方法

每个分页器实例都可以通过以下方法提供更多分页信息:

  • $results->count()
  • $results->currentPage()
  • $results->firstItem()
  • $results->hasMorePages()
  • $results->lastItem()
  • $results->lastPage() (使用simplePaginate时无效)
  • $results->nextPageUrl()
  • $results->perPage()
  • $results->previousPageUrl()
  • $results->total() (使用simplePaginate时无效)
  • $results->url($page)

学院君

学院君 has written 548 articles

资深PHP工程师,Laravel学院院长