Weave Code
Pagination Plugin Laravel Package
saloonphp/pagination-plugin
Adds pagination support to Saloon API integrations, letting you iterate through paginated responses with simple, fluent loops. It handles common pagination strategies so you can fetch every page of results without writing repetitive boilerplate, keeping your API integrations clean and easy to mainta...
Saloon PHP Pagination Plugin brings fluent, reusable pagination to Saloon API integrations. It helps you traverse multi-page API responses with configurable strategies, so you can iterate over results without hand-writing page, offset, or cursor logic.
- Saloon-native integration with requests, responses, and connectors
- Configurable pagination strategies for common API patterns
- Lazy iteration over paginated results
- Custom paginators for non-standard APIs
- Lightweight, framework-agnostic PHP API
Frequently asked questions about Pagination Plugin
- How do I install the Saloon pagination plugin with Composer?
- Install it with composer require saloonphp/pagination-plugin alongside Saloon itself. Then register the plugin on the Saloon connector you want to paginate and declare a pagination strategy on that connector. There is no infrastructure change, database migration, or new runtime involved, so the effort is mostly API-specific configuration rather than plugin setup.
- Which Saloon versions does saloonphp/pagination-plugin support?
- The plugin ships parallel release lines that map to Saloon majors: plugin v1 targets Saloon v2, plugin v2 targets Saloon v3, and v2.3.0 adds support for Saloon v4. Your Saloon major version effectively pins the plugin major version, so plan for a recurring upgrade each time Saloon cuts a new major. It is plain PHP, so it works inside Laravel applications without any framework-specific wiring.
- What pagination strategies does the plugin include out of the box?
- It ships paginators for page/limit style APIs, offset-based APIs, and cursor-based APIs, plus a strategy abstraction you can implement for bespoke schemes. That covers the common cases, including cursor-in-body and link-header responses once you map them to a custom strategy. Anything non-standard (for example cursors nested under edges) needs a small custom strategy written and tested against real payloads.
- How do I iterate through all pages of a paginated API response?
- You iterate the paginated result using each, chunk, collect, or lazy, with async variants available for the same operations. That replaces hand-rolled while ($nextPage) loops inside jobs and commands, which is where off-by-one pages and duplicated records tend to creep in. chunk and lazy are the right choice when the dataset may be large, while collect pulls the whole set into memory.
- How do I write a custom pagination strategy for a non-standard API?
- Implement your own strategy that describes how the next page request is built from the previous response, then declare it on the connector. The real work is identifying whether the upstream API is page/limit, offset, cursor, or fully bespoke, and validating that assumption against real payloads. For standard APIs this is a matter of hours; for a non-standard schema budget roughly half a day to a day per strategy including tests.
- Does the plugin detect infinite pagination loops in async requests?
- Automatic infinite-loop detection was introduced in v2 but is explicitly disabled for asynchronous pagination to avoid memory problems. That means the async path, which is the one you would use for large datasets, has no safety net, so any async job must carry its own max-pages, max-records, or wall-clock bounds. It is also worth testing the loop-detection and paginator-state machinery rather than assuming it, since v2.2.2 fixed a false infinite loop caused by body checksums not being reset on rewind.
- How do I unit test pagination without hitting the real API?
- Use Saloon's built-in mocking support to fake responses per page, then assert that your paginator follows the expected sequence of requests. This lets you verify page, cursor, and offset traversal deterministically in your test suite with no upstream calls. It also makes it cheap to confirm behaviour around retries and duplicate records before the code reaches production.
- Does the pagination plugin handle rate limits, retries, and 429 responses?
- No. Rate limiting, retries, and back-off are Saloon's responsibility, not the plugin's, and the plugin will keep paginating into a 429 if nothing stops it. Ownership of those policies should sit explicitly with the connector, for example through Saloon's retry and rate-limiting features. Treat pagination bounds and throttling as two separate concerns in your job design.
- Is the plugin safe for large datasets and memory-constrained jobs?
- Use lazy or chunk iteration so results stream page by page instead of being accumulated, and reserve collect for small, bounded responses. The async variants help throughput but, as noted, they drop the automatic loop detection, so wrap them with explicit page or record ceilings. For very large exports consider a dedicated ETL path rather than an ordinary queued job.
- Is saloonphp/pagination-plugin actively maintained, and what are the alternatives?
- It is the official plugin for Saloon, MIT licensed, authored and maintained by Saloon's own maintainer, with releases tracking Saloon closely including v2.3.0 for Saloon v4. Adoption is still small (roughly ten stars and no dependents), so you will not get much crowd-sourced battle testing, but the code surface is small enough that the blast radius is limited and forking stays cheap. The main alternative is a hand-rolled pagination loop per integration, which is exactly the boilerplate this package is meant to delete.
Weaver
How can I help you explore Laravel packages today?