Pagerfanta Documentation

Pagerfanta uses the Pagerfanta\View\ViewInterface to abstract the rendering of pagination lists. A view is responsible for generating the HTML markup required to display pagination controls.

To implement a custom view, you must satisfy the ViewInterface which requires two methods:

1. render: Generates the markup. It accepts a PagerfantaInterface instance, a callable for route generation, and an optional array of options.
2. getName: Returns a unique string identifier for the view.

Base Classes for Implementation:

• Pagerfanta\View\View: The recommended base class. It handles the logic for calculating which page items should be displayed.
• Pagerfanta\View\TemplateView: An extension of View designed for use with Pagerfanta\View\Template\TemplateInterface instances (useful for template-based rendering).

<?php

namespace Pagerfanta//... (interface definition)
interface ViewInterface
{
    public function render(PagerfantaInterface $pagerfanta, callable $routeGenerator, array $options = []): string;
    public function getName(): string;
}

To use Pagerfanta with a custom data source (such as a database, an API, or an array), you must implement the Pagerfanta\Adapter\AdapterInterface. This interface acts as the abstraction layer that allows Pagerfanta to interact with your data.

Your implementation must provide two core methods:

1. getNbResults(): Returns the total number of items available in the entire dataset.
   • Note: If the returned count is less than zero, you should throw a Pagerfanta\Exception\NotValidResultCountException.
2. getSlice(int $offset, int $length): Returns an iterable containing only the subset of items requested for the current page, starting at the specified $offset with a maximum of $length items.

By implementing this interface, your data source becomes compatible with all Pagerfanta pagination features, including different pagination strategies and result transformers.

namespace Pagerfanta\Adapter;

use Pagerfanta\Exception\NotValidResultCountException;

interface AdapterInterface
{
    /**
     * Returns the number of results for the list.
     * 
     * @throws NotValidResultCountException if the number of results is less than zero.
     */
    public function getNbResults(): int;

    /**
     * Returns an slice of the results representing the current page of items in the list.
     */
    public function getSlice(int $offset, int $length): iterable;
}

To create custom HTML markup for your pagination list, you must implement the Pagerfanta\View\Template\TemplateInterface. This interface acts as an abstraction layer for building the different components of a pagination UI (e.g., containers, page numbers, next/previous buttons, and separators).

Key responsibilities of an implementation include:

• Route Generation: Using setRouteGenerator to provide a callable or RouteGeneratorInterface so the template knows how to build URLs.
• Configuration: Using setOptions to pass custom data to the template.
• Component Rendering: Implementing specific methods for each UI element (e.g., container(), page(), nextEnabled(), etc.).

Note that the container() method is expected to return a string containing a %pages% placeholder, which is replaced by the rendered list of pages.

<?php

namespace Pagerfanta\View\Template;

use Pagerfanta\RouteGenerator\RouteGeneratorInterface;

interface TemplateInterface
{
    /**
     * Sets the route generator used while rendering the template.
     *
     * @param callable|RouteGeneratorInterface $routeGenerator
     */
    public function setRouteGenerator(callable $routeGenerator): void;

    /**
     * Sets the options for the template, overwriting keys that were previously set.
     */
    public function setOptions(array $options): void;

    /**
     * Renders the container for the pagination.
     *
     * The %pages% placeholder will be replaced by the rendering of pages.
     */
    public function container(): string;

    /**
     * Renders a given page.
     */
    public function page(int $page): string;

    /**
     * Renders a given page with a specified text.
     */
    public function pageWithText(int $page, string $text, ?string $rel = null): string;

    /**
     * Renders the disabled state of the previous page.
     */
    public function previousDisabled(): string;

    /**
     * Renders the enabled state of the previous page.
     */
    public function previousEnabled(int $page): string;

    /**
     * Renders the disabled state of the next page.
     */
    public function nextDisabled(): string;

    /**
     * Renders the enabled state of the next page.
     */
    public function nextEnabled(int $page): string;

    /**
     * Renders the first page.
     */
    public function first(): string;

    /**
     * Renders the last page.
     */
    public function last(int $page): string;

    /**
     * Renders the current page.
     */
    public function current(int $page): string;

    /**
     * Renders the separator between pages.
     */
    public function separator(): string;
}

When creating custom Twig templates, extend @Pagerfanta/default.html.twig and override specific blocks.

Key Blocks:

• pager_widget: Use this to change the wrapping HTML for the entire paginator.
• pager: Contains the structure of the pager (links, separators, etc.). Only extend this if you need to change the logic (e.g., removing ellipsis).

Variables available in the template:

• pagerfanta: The Pagerfanta\PagerfantaInterface object.
• route_generator: A Pagerfanta\RouteGenerator\RouteGeneratorDecorator (used to generate URLs).
• options: The options array passed to the pagerfanta() function.
• start_page / end_page: Calculated range based on proximity.
• current_page: The current active page.
• nb_pages: Total number of pages.

Variables available in page blocks (previous_page_link, page_link, current_page_link, next_page_link):

• page: The specific page number.
• path: The generated URL for that page.