Generating Paginated Routes

When rendering a Pagerfanta view, a route generator callable is required to generate the URLs for each item in the pagination list. The route generator can be customized for use within your application if you need to adjust the routing logic.

Position Route Generators

Pagerfanta describes the pages a pager links to with positions, which support both offset and cursor pagination.

The route generators are defined by two interfaces, with their default implementations noted below:

• Pagerfanta\RouteGenerator\PositionRouteGeneratorInterface - The class type that is used to generate routes

  • BabDev\PagerfantaBundle\RouteGenerator\RouterAwarePositionRouteGenerator is used by default, which uses the Symfony Routing component to generate routes

• Pagerfanta\RouteGenerator\PositionRouteGeneratorFactoryInterface - A factory service that is used to generate a PositionRouteGeneratorInterface at runtime

  • BabDev\PagerfantaBundle\RouteGenerator\RequestAwarePositionRouteGeneratorFactory is used by default, which uses the Symfony\Component\HttpFoundation\Request object to attempt to set the default route name and route parameters, this creates a RouterAwarePositionRouteGenerator

The RouterAwarePositionRouteGenerator generates the URLs as follows:

• For a page position, the page number is set to the page parameter and the cursor parameter is removed
• For a cursor position, the signed cursor is set to the cursor parameter and the page parameter is removed

The Twig integration uses the Pagerfanta\RouteGenerator\PositionRouteGeneratorFactoryInterface service to create the route generator used when rendering a Pagerfanta view.

The pagerfanta.position_route_generator_factory service is available for use in your application if you need to create a route generator, and is aliased to the Pagerfanta\RouteGenerator\PositionRouteGeneratorFactoryInterface. To use another factory, including with the Twig integration, point this alias to your service.

# config/services.yaml
services:
    Pagerfanta\RouteGenerator\PositionRouteGeneratorFactoryInterface:
        alias: App\Pagination\RouteGeneratorFactory

Position Route Generator Options

The following options may be passed through a route generator factory when using the BabDev\PagerfantaBundle\RouteGenerator\RouterAwarePositionRouteGenerator in order to customize the generated URLs:

• routeName - Required option (generated by the RequestAwarePositionRouteGeneratorFactory if not given), the name of the route to use for the paginated URLs
• pageParameter - Defaults to "[page]", specifies the name of the routing parameter to use for the page, note that the page parameter MUST be wrapped in brackets (i.e. [other_page]) for the route generator to correctly function
• cursorParameter - Defaults to "[cursor]", specifies the name of the routing parameter to use for the cursor, note that the cursor parameter MUST be wrapped in brackets (i.e. [after]) for the route generator to correctly function
• omitFirstPage - Defaults to false, a boolean value indicating whether the first page should omit the pagination parameter (if true, ?page=1 will not be part of the paginated URL for page 1 of your list)
• routeParams - Defaults to an empty array, an array of additional parameters to pass to the router for generating the URL
• referenceType - Defaults to Symfony\Component\Routing\Generator\UrlGeneratorInterface::ABSOLUTE_PATH, allows specifying the $referenceType parameter when calling Symfony\Component\Routing\Generator\UrlGeneratorInterface::generate()

{{ pagerfanta(pager, {'cursorParameter': '[after]'}) }}

Page Number Based Route Generators

Before PagerfantaBundle 4.7, the route generators were defined by the Pagerfanta\RouteGenerator\RouteGeneratorInterface and Pagerfanta\RouteGenerator\RouteGeneratorFactoryInterface interfaces, which generate routes using page numbers. The pagerfanta.route_generator_factory service (a RequestAwareRouteGeneratorFactory creating RouterAwareRouteGenerator instances) remains available until PagerfantaBundle 5.0, and supports all of the position route generator options except the cursorParameter option.