Pagination

Paginez vos listes de résultats avec des liens de navigation générés automatiquement.

Usage basique

Créez un Paginator en passant le nombre total d'items, le nombre par page, la page courante et l'URL de base.

use River\Paginator;

$paginator = new Paginator(
    total: 150,
    per_page: 15,
    current_page: 3,
    base_url: '/admin/users'
);

Factory depuis la Request

La méthode from_request() récupère automatiquement la page courante depuis le query string et préserve les autres paramètres (filtres, recherche, etc.).

use River\Paginator;

class Users_ctrl extends Controller
{
    public function index(Database $db): Response
    {
        $total = $db->query("SELECT COUNT(*) FROM users")->fetchColumn();

        $paginator = Paginator::from_request($this->request, $total, per_page: 20);

        $users = $db->query(
            "SELECT * FROM users LIMIT ? OFFSET ?",
            [$paginator->per_page(), $paginator->offset()]
        )->fetchAll();

        return $this->render('users/index', compact('users', 'paginator'));
    }
}

Astuce : from_request() conserve automatiquement les query params existants (ex: ?search=foo&page=2). Pas besoin de les gérer manuellement.

Affichage dans un template

Utilisez les méthodes de navigation pour construire votre pagination. Voici un exemple avec Bootstrap 5 :

<?php if ($paginator->has_pages()): ?>

<p class="text-muted"><?= $paginator->info() ?></p>

<nav>
  <ul class="pagination">

    <!-- Précédent -->
    <li class="page-item <?= $paginator->has_previous() ? '' : 'disabled' ?>">
      <a class="page-link" href="<?= $paginator->previous_url() ?>">&laquo;</a>
    </li>

    <!-- Pages -->
    <?php foreach ($paginator->pages() as $page): ?>
      <?php if ($page === '...'): ?>
        <li class="page-item disabled"><span class="page-link">...</span></li>
      <?php else: ?>
        <li class="page-item <?= $paginator->is_current($page) ? 'active' : '' ?>">
          <a class="page-link" href="<?= $paginator->url($page) ?>"><?= $page ?></a>
        </li>
      <?php endif ?>
    <?php endforeach ?>

    <!-- Suivant -->
    <li class="page-item <?= $paginator->has_next() ? '' : 'disabled' ?>">
      <a class="page-link" href="<?= $paginator->next_url() ?>">&raquo;</a>
    </li>

  </ul>
</nav>

<?php endif ?>

La méthode info() affiche un texte comme "Affichage de 31 à 45 sur 150 résultats".

Liste des pages intelligente

La méthode pages() génère un tableau avec des ellipsis '...' pour les grandes listes. Par défaut, elle affiche 2 pages de chaque côté de la page courante.

// Page courante = 5, total = 10
$paginator->pages();
// → [1, '...', 3, 4, 5, 6, 7, '...', 10]

// Afficher plus de pages autour de la courante
$paginator->set_side_pages(3);
$paginator->pages();
// → [1, 2, 3, 4, 5, 6, 7, 8, '...', 10]

Référence API

Méthode	Retour	Description
`total()`	`int`	Nombre total d'items
`per_page()`	`int`	Items par page
`current_page()`	`int`	Page courante (1-indexed)
`total_pages()`	`int`	Nombre total de pages
`offset()`	`int`	Offset pour SQL `LIMIT x OFFSET y`
`has_items()`	`bool`	Y a-t-il des items ?
`has_pages()`	`bool`	Y a-t-il plus d'une page ?
Navigation
`has_previous()`	`bool`	Page précédente disponible ?
`has_next()`	`bool`	Page suivante disponible ?
`previous_page()`	`int`	Numéro de la page précédente
`next_page()`	`int`	Numéro de la page suivante
`first_page()`	`int`	Première page (1)
`last_page()`	`int`	Dernière page
URLs
`url($page)`	`string`	URL pour une page donnée
`previous_url()`	`string`	URL de la page précédente
`next_url()`	`string`	URL de la page suivante
`first_url()`	`string`	URL de la première page
`last_url()`	`string`	URL de la dernière page
Affichage
`pages()`	`array`	Liste des pages avec ellipsis `'...'`
`is_current($page)`	`bool`	La page est-elle la courante ?
`first_item()`	`int`	Premier item de la page (1-indexed)
`last_item()`	`int`	Dernier item de la page
`info()`	`string`	"Affichage de X à Y sur Z résultats"
Configuration
`set_side_pages($n)`	`self`	Pages affichées de chaque côté (défaut: 2)
Factory
`from_request($request, $total, $per_page, $base_url)`	`self`	Crée un paginator depuis la requête HTTP

Paramètres du constructeur

Paramètre	Type	Défaut	Description
`total`	`int`	-	Nombre total d'items
`per_page`	`int`	`15`	Items par page
`current_page`	`int`	`1`	Page courante
`base_url`	`string`	`''`	URL de base pour les liens
`query_params`	`array`	`[]`	Query params à préserver
`page_param`	`string`	`'page'`	Nom du paramètre de page

Migrations Middleware