Weave Code
Laravel Json Api Paginate Laravel Package
spatie/laravel-json-api-paginate
A Laravel package that adds a jsonPaginate method to the Eloquent query builder, so pagination reads page[number] and page[size] request parameters and returns the pagination links required by the JSON:API spec.
A paginator that plays nice with the JSON API spec
Frequently asked questions about Laravel Json Api Paginate
- How do I install spatie/laravel-json-api-paginate in a Laravel app?
- Install it with composer require spatie/laravel-json-api-paginate. On Laravel 5.5 and newer the service provider is auto-discovered, so no manual registration is needed; on older versions add Spatie\JsonApiPaginate\JsonApiPaginateServiceProvider to the providers array in config/app.php. Publishing the config file with php artisan vendor:publish is optional and only needed if you want to change defaults. There are no migrations or schema changes.
- How do I use jsonPaginate instead of paginate on an Eloquent query?
- Replace paginate() with jsonPaginate() on any Eloquent query builder. Instead of the page parameter, it reads page[number] and page[size] from the request and returns a paginator whose links follow the JSON:API pagination example. The rest of your controller and resource code stays the same because it is a thin adapter over Laravel's own paginator.
- How do I set the default page size and maximum page size?
- Publish the config file and set the default and maximum page sizes, or pass them as positional arguments: jsonPaginate($maxResults, $defaultSize, $total). The third argument lets you supply a precomputed total count when you already have one. maxResults caps client-requested page[size] values so a caller cannot request an unbounded page.
- Which Laravel versions does this package support?
- Laravel 5.5 and up auto-register the provider, and the package has a track record of shipping compatibility updates for Laravel 9, 10, 11, 12 and 13 shortly after each release. Check the composer.json constraints for the exact version you install. It requires no framework-level changes, so upgrades are usually just a composer update.
- Does this package make my API fully JSON:API compliant?
- No. It only handles the pagination slice: parsing page[number] and page[size] and generating spec-shaped pagination links. It does not produce the top-level data, links and meta document, handle application/vnd.api+json content negotiation, sparse fieldsets, sorting, filtering, compound documents or error objects. Teams usually pair it with spatie/laravel-query-builder for filtering and sorting; a full-spec implementation such as laravel-json-api or Laravel Orion is a separate, larger decision.
- What happens if another package already defines a jsonPaginate macro?
- The method name is configurable via method_name in the config file. Because jsonPaginate is a macro on a Macroable class, any other package or in-house trait registering the same name will collide, and Laravel's __call resolution makes that failure confusing rather than loud. Claim the name in an ADR and add a boot-time assertion test. The page[number] and page[size] parameter names follow the spec and are not intended to be renamed.
- Why do pagination links point to http or an internal hostname behind a proxy?
- Version 4 removed the base_url option because it used setPath() and clobbered resource paths, producing identical pagination URLs across endpoints. If you sit behind a TLS-terminating proxy or load balancer, use URL::forceScheme('https') and URL::forceRootUrl() in a service provider so links are generated with the correct scheme and host. Treat this as an explicit migration task, because unit tests often pass while production links point at http:// or an internal hostname.
- Can I use jsonPaginate on hasMany and belongsToMany relationship queries?
- Yes. Alongside the query builder macro, the package registers variants for HasMany, BelongsToMany and HasManyThrough relations, so you can call jsonPaginate() on relationship queries too. The same page[number], page[size] and link generation behavior applies.
- How should I test jsonPaginate endpoints and pagination links?
- Write feature tests that hit an endpoint with page[number] and page[size] and assert the returned links, the default size and the maxResults cap. Add a contract test for the exact URL shape your clients depend on, plus a boot-time assertion that jsonPaginate is registered to your expected macro. For existing endpoints, test behind a simulated proxy configuration to catch scheme and host regressions.
- What are the alternatives to this package for JSON:API in Laravel?
- If you need full JSON:API compliance, look at laravel-json-api or Laravel Orion instead; this package covers only the pagination slice. If you want filtering and sorting with the same query-parameter style, pair it with spatie/laravel-query-builder, which is the realistic unit of adoption. Stay with plain Laravel pagination if your API is not committing to JSON:API query semantics.
Weaver
How can I help you explore Laravel packages today?