{"id":19324997,"url":"https://github.com/spatie/laravel-json-api-paginate","last_synced_at":"2025-05-15T05:00:15.225Z","repository":{"id":21891792,"uuid":"94352951","full_name":"spatie/laravel-json-api-paginate","owner":"spatie","description":"A paginator that plays nice with the JSON API spec","archived":false,"fork":false,"pushed_at":"2025-02-26T07:30:09.000Z","size":142,"stargazers_count":599,"open_issues_count":0,"forks_count":48,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-14T05:56:56.959Z","etag":null,"topics":["api","json","laravel","paginate","php","spec"],"latest_commit_sha":null,"homepage":"https://spatie.be/en/opensource/laravel","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"https://spatie.be/open-source/support-us"}},"created_at":"2017-06-14T16:46:25.000Z","updated_at":"2025-04-09T13:00:36.000Z","dependencies_parsed_at":"2025-04-14T04:12:47.740Z","dependency_job_id":"de46dd0b-4f8e-44ae-96c1-66693662f231","html_url":"https://github.com/spatie/laravel-json-api-paginate","commit_stats":{"total_commits":129,"total_committers":28,"mean_commits":4.607142857142857,"dds":0.4418604651162791,"last_synced_commit":"f829d8ef15e9ca2842b4c74e5b56ea900550e2e7"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-json-api-paginate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-json-api-paginate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-json-api-paginate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-json-api-paginate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/laravel-json-api-paginate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276444,"owners_count":22043866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","json","laravel","paginate","php","spec"],"created_at":"2024-11-10T02:08:31.703Z","updated_at":"2025-05-15T05:00:15.199Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":["https://spatie.be/open-source/support-us"],"categories":[],"sub_categories":[],"readme":"# A paginator that plays nice with the JSON API spec\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/laravel-json-api-paginate.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-json-api-paginate)\n[![Check \u0026 fix styling](https://github.com/spatie/laravel-json-api-paginate/actions/workflows/php-cs-fixer.yml/badge.svg)](https://github.com/spatie/laravel-json-api-paginate/actions/workflows/php-cs-fixer.yml)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-json-api-paginate.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-json-api-paginate)\n\nIn a vanilla Laravel application [the query builder paginators will listen to `page` request parameter](https://laravel.com/docs/master/pagination#paginating-query-builder-results). This works great, but it does not follow the example solution of [the json:api spec](http://jsonapi.org/). That example [expects](http://jsonapi.org/examples/#pagination) the query builder paginator to listen to the `page[number]` and `page[size]` request parameters.\n\nThis package adds a `jsonPaginate` method to the Eloquent query builder that listens to those parameters and adds [the pagination links the spec requires](http://jsonapi.org/format/#fetching-pagination).\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/laravel-json-api-paginate.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/laravel-json-api-paginate)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/laravel-json-api-paginate\n```\n\nIn Laravel 5.5 and above the service provider will automatically get registered. In older versions of the framework just add the service provider in `config/app.php` file:\n\n```php\n'providers' =\u003e [\n    ...\n    Spatie\\JsonApiPaginate\\JsonApiPaginateServiceProvider::class,\n];\n```\n\nOptionally you can publish the config file with:\n\n```bash\nphp artisan vendor:publish --provider=\"Spatie\\JsonApiPaginate\\JsonApiPaginateServiceProvider\" --tag=\"config\"\n```\n\nThis is the content of the file that will be published in `config/json-api-paginate.php`\n\n```php\n\u003c?php\n\nreturn [\n\n    /*\n     * The maximum number of results that will be returned\n     * when using the JSON API paginator.\n     */\n    'max_results' =\u003e 30,\n\n    /*\n     * The default number of results that will be returned\n     * when using the JSON API paginator.\n     */\n    'default_size' =\u003e 30,\n\n    /*\n     * The key of the page[x] query string parameter for page number.\n     */\n    'number_parameter' =\u003e 'number',\n\n    /*\n     * The key of the page[x] query string parameter for page size.\n     */\n    'size_parameter' =\u003e 'size',\n\n    /*\n     * The key of the page[x] query string parameter for cursor.\n     */\n    'cursor_parameter' =\u003e 'cursor',\n\n    /*\n     * The name of the macro that is added to the Eloquent query builder.\n     */\n    'method_name' =\u003e 'jsonPaginate',\n\n    /*\n     * If you only need to display Next and Previous links, you may use\n     * simple pagination to perform a more efficient query.\n     */\n    'use_simple_pagination' =\u003e false,\n\n    /*\n     * If you want to use cursor pagination, set this to true.\n     * This would override use_simple_pagination.\n     */\n    'use_cursor_pagination' =\u003e false,\n\n    /*\n     * use simpleFastPaginate() or fastPaginate from https://github.com/aarondfrancis/fast-paginate\n     * use may installed it via `composer require aaronfrancis/fast-paginate`\n     */\n    'use_fast_pagination' =\u003e false,\n\n    /*\n     * Here you can override the base url to be used in the link items.\n     */\n    'base_url' =\u003e null,\n\n    /*\n     * The name of the query parameter used for pagination\n     */\n    'pagination_parameter' =\u003e 'page',\n];\n\n```\n\n## Usage\n\nTo paginate the results according to the json API spec, simply call the `jsonPaginate` method.\n\n```php\nYourModel::jsonPaginate();\n```\n\nOf course you may still use all the builder methods you know and love:\n\n```php\nYourModel::where('my_field', 'myValue')-\u003ejsonPaginate();\n```\n\nYou can also paginate results for relations:\n\n```php\n$model = YourModel::find(1);\n\n$model-\u003erelation()-\u003ejsonPaginate();\n```\n\n### Override default behavior\n\nBy default the maximum page size is set to 30. You can change this number in the `config` file or just pass the value to  `jsonPaginate`.\n\n```php\n$maxResults = 60;\n\nYourModel::jsonPaginate($maxResults);\n```\n\nBy default the default page size is set to 30. You can change this number in the `config` file or just pass the value to  `jsonPaginate`.\n\n```php\n$defaultSize = 15;\n\nYourModel::jsonPaginate(null, $defaultSize);\n```\n\nYou can also pass the total count to the `paginate` function directly. This can be useful for performance reasons or to prevent issues with `DISTINCT` keyword ([more info](https://github.com/laravel/framework/issues?q=is%3Aissue+paginate+total)).\n\n⚠️ This is effective only with basic pagination (no effect with cursor, simple or fast pagination)\n\n```php\n$total = 42;\n\nYourModel::jsonPaginate(null, null, $total);\n```\n\n### Cursor pagination\n\nThis package also supports cursor pagination, which can be briefly defined by the Laravel Framework as follows:\n\n\u003e While paginate and simplePaginate create queries using the SQL \"offset\" clause, cursor pagination works by constructing \"where\" clauses that compare the values of the ordered columns contained in the query, providing the most efficient database performance available amongst all of Laravel's pagination methods.\n\nYou can find more about cursor pagination in the [Laravel Documentation](https://laravel.com/docs/9.x/pagination#cursor-pagination).\n\nIf you want to use cursor pagination, you can set the `use_cursor_pagination` to true in the `config` file.\n\nIt's also possible to modify the pagination parameter in the `config` file, by modifying the `cursor_parameter` value.\n\n```php\n\u003c?php\n\nreturn [\n    // ..... other config options .....\n\n    /*\n     * The key of the page[x] query string parameter for cursor.\n     */\n    'cursor_parameter' =\u003e 'cursor',\n\n    /*\n     * If you want to cursor pagination, set this to true.\n     * This would override use_simple_pagination.\n     */\n    'use_cursor_pagination' =\u003e true,\n\n    // ..... other config options .....\n];\n\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security\n\nIf you've found a bug regarding security please mail [security@spatie.be](mailto:security@spatie.be) instead of using the issue tracker.\n\n## Credits\n\n- [Freek Van der Herten](https://github.com/freekmurze)\n- [All Contributors](../../contributors)\n\nThe base code of this page was published on [this Laracasts forum thread](https://laracasts.com/discuss/channels/laravel/pagination-using-json-api-strategy?page=1#reply-346619) by [Joram van den Boezem](https://twitter.com/@hongaar)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-json-api-paginate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Flaravel-json-api-paginate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-json-api-paginate/lists"}