Getting Started

Install with composer require sbsedv/paginator-bundle. In Symfony Flex, the bundle is auto-registered; otherwise add it to config/bundles.php.
Check composer.json constraints after upgrading. v1.7.0 only adds Symfony 8 compatibility, so existing Symfony 6.4/7.x applications should see no behavioral change.
Look first at the bundle’s default configuration: page parameter name, default page size, and any service aliases. These determine the request/response shape your controllers and templates will use.
First use case: paginate a Doctrine query in a controller or read service, convert the request’s page parameters into the bundle’s page request object, and pass the resulting page DTO to Twig or an API response.

Implementation Patterns

Keep pagination out of templates. Build the page request in the controller, call the paginator service, and pass a page object with items and metadata to the view.
Centralize page-request creation. Read page and limit from the request once, clamp the limit, and reuse that logic across controllers instead of duplicating query-parameter handling.
Paginate in repositories or query services when the query is reusable. Return the bundle’s page result rather than an array so callers retain total count, current page, and next/previous information.
For APIs, map the page result to a stable JSON envelope such as data, meta.current_page, meta.per_page, and meta.total. Do not leak Doctrine query objects into the response.
Apply filters and ordering before pagination. Pagination should be the last step in query construction so counts and page boundaries remain correct.
Use the same paginator for HTML and JSON endpoints where possible. This keeps page-size limits and parameter names consistent across the application.
On Symfony 8 projects, verify the rest of the dependency graph supports Symfony 8 before relying on v1.7.0. Use composer why-not symfony/framework-bundle 8.0 to find blockers.
Add functional tests with explicit page requests, including first page, last page, out-of-range page, and custom page sizes.

Joins can inflate row counts and produce duplicate items. Use distinct() or a separate count query when paginating queries with collection joins.
Large offsets become slow on big tables. If the bundle exposes cursor or keyset pagination, prefer it for high-traffic endpoints; otherwise keep page depth bounded.
Never trust user-supplied limit values. Clamp them to a maximum and fall back to a configured default when invalid.
Changing the page parameter name or default page size can break existing links, bookmarks, and API clients. Treat those settings as part of your public contract.
v1.7.0 is a compatibility release, not a feature release. There are no documented breaking changes, but the Symfony 8 constraint may pull in newer transitive dependencies, so run the full test suite after upgrading.
This is a Symfony bundle, not a Laravel package. Laravel applications should use Laravel’s native paginator or a Doctrine-oriented alternative rather than expecting framework integration here.
Debug pagination issues by inspecting the executed query and count query separately. A correct item list with an incorrect total usually points to a count-query or join problem.
Use service decoration if you need to customize pagination behavior. Prefer decorating the paginator service over forking bundle internals, which keeps future Symfony compatibility upgrades straightforward.