README

在纯 Laravel 应用中 查询构建器的分页器会监听 page 请求参数。这很好，但它并不遵循 json:api 规范 的示例解决方案。该示例 预期 查询构建器的分页器监听 page[number] 和 page[size] 请求参数。

此包向 Eloquent 查询构建器添加了一个 jsonPaginate 方法，这些参数会监听并添加规范所需的分页链接。

支持我们

我们投入了大量资源来创建 一流的开放式源代码包。您可以通过 购买我们的付费产品之一 来支持我们。

我们非常感谢您从您的家乡寄给我们明信片，注明您正在使用我们的哪些包。您可以在 我们的联系页面 上找到我们的地址。我们将所有收到的明信片发布在我们的 虚拟明信片墙上。

安装

您可以通过 composer 安装此包

composer require spatie/laravel-json-api-paginate

在 Laravel 5.5 及以上版本中，服务提供程序将自动注册。在框架的旧版本中，只需在 config/app.php 文件中添加服务提供程序即可

'providers' => [
    ...
    Spatie\JsonApiPaginate\JsonApiPaginateServiceProvider::class,
];

可选地，您可以使用以下命令发布配置文件：

php artisan vendor:publish --provider="Spatie\JsonApiPaginate\JsonApiPaginateServiceProvider" --tag="config"

这是将要发布到 config/json-api-paginate.php 的文件内容

<?php

return [

    /*
     * The maximum number of results that will be returned
     * when using the JSON API paginator.
     */
    'max_results' => 30,

    /*
     * The default number of results that will be returned
     * when using the JSON API paginator.
     */
    'default_size' => 30,

    /*
     * The key of the page[x] query string parameter for page number.
     */
    'number_parameter' => 'number',

    /*
     * The key of the page[x] query string parameter for page size.
     */
    'size_parameter' => 'size',

    /*
     * The key of the page[x] query string parameter for cursor.
     */
    'cursor_parameter' => 'cursor',

    /*
     * The name of the macro that is added to the Eloquent query builder.
     */
    'method_name' => 'jsonPaginate',

    /*
     * If you only need to display Next and Previous links, you may use
     * simple pagination to perform a more efficient query.
     */
    'use_simple_pagination' => false,

    /*
     * If you want to use cursor pagination, set this to true.
     * This would override use_simple_pagination.
     */
    'use_cursor_pagination' => false,

    /*
     * use simpleFastPaginate() or fastPaginate from https://github.com/hammerstonedev/fast-paginate
     * use may installed it via `composer require hammerstone/fast-paginate`
     */
    'use_fast_pagination' => false,

    /*
     * Here you can override the base url to be used in the link items.
     */
    'base_url' => null,

    /*
     * The name of the query parameter used for pagination
     */
    'pagination_parameter' => 'page',
];

用法

要按照 json API 规范分页结果，只需调用 jsonPaginate 方法。

YourModel::jsonPaginate();

当然，您仍然可以使用您所熟知和喜爱的所有构建器方法

YourModel::where('my_field', 'myValue')->jsonPaginate();

您也可以对关系进行分页

$model = YourModel::find(1);

$model->relation()->jsonPaginate();

默认最大页面大小设置为 30。您可以在配置文件中更改此数字，或者只需将值传递给 jsonPaginate。

$maxResults = 60;

YourModel::jsonPaginate($maxResults);

游标分页

此包还支持游标分页，Laravel 框架可以简要定义为以下内容

虽然 paginate 和 simplePaginate 使用 SQL "offset" 子句创建查询，但游标分页通过构建比较查询中包含的排序列值的 "where" 子句来工作，在 Laravel 的所有分页方法中提供最有效的数据库性能。

您可以在 Laravel 文档 中找到有关游标分页的更多信息。

如果您想使用游标分页，可以在配置文件中将 use_cursor_pagination 设置为 true。

您还可以在配置文件中修改分页参数，通过修改 cursor_parameter 的值。

<?php

return [
    // ..... other config options .....

    /*
     * The key of the page[x] query string parameter for cursor.
     */
    'cursor_parameter' => 'cursor',

    /*
     * If you want to cursor pagination, set this to true.
     * This would override use_simple_pagination.
     */
    'use_cursor_pagination' => true,

    // ..... other config options .....
];

变更日志

请参阅 CHANGELOG 了解最近更改的更多信息。

测试

composer test

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

如果您发现与安全相关的错误，请通过电子邮件发送至 [email protected]，而不是使用问题跟踪器。

致谢

• Freek Van der Herten
• 所有贡献者

本页面的基础代码由 这个Laracasts论坛主题 发布，发布者是 Joram van den Boezem

许可证

MIT许可证（MIT）。请参阅 许可证文件 获取更多信息。