Laravel Pagination

Tempo de leitura: 4 minutos

Laravel Pagination: A Paginação é fundamental em aplicações que precisam exibir grandes volumes de dados. O Laravel Pagination simplifica o processo de dividir resultados em pedaços menores, melhorando drasticamente a performance (carregando apenas os dados necessários para a página atual) e a experiência do usuário.

O Laravel oferece uma API fluente para paginar resultados, seja com o Query Builder ou com o Eloquent ORM.

1. 🔍 Paginação Básica com Query Builder e Eloquent

O método paginate() é a chave para a paginação e funciona de forma idêntica tanto para o Query Builder quanto para o Eloquent ORM.

A. Query Builder

Use o método paginate(itensPorPagina) após a construção da sua query.

PHP

use Illuminate\Support\Facades\DB;

// Pagina os usuários em grupos de 10
$users = DB::table('users')->where('active', true)->paginate(10);

B. Eloquent ORM

A paginação é aplicada diretamente no modelo.

PHP

use App\Models\User;

// Pagina os usuários em grupos de 15, com todos os filtros aplicados anteriormente
$users = User::where('status', 'premium')->paginate(15);

Ambos os métodos retornam uma instância de LengthAwarePaginator, que contém metadados importantes (total de itens, número da página atual, última página, etc.).

C. Paginação Simples (`simplePaginate`)

Para conjuntos de dados extremamente grandes onde o número total de itens não é crucial, use simplePaginate().

PHP

$users = User::simplePaginate(15);

O simplePaginate não calcula o número total de páginas, apenas verifica se há mais resultados (botões “Próximo” e “Anterior”), o que pode ser mais rápido em algumas situações.

2. 🖥️ Exibindo os Links de Paginação

O objeto Paginator retornado pelo Laravel possui métodos prontos para serem usados diretamente na sua view Blade.

A. Renderizando os Links (`links()`)

O método links() renderiza a barra de navegação completa, incluindo os números das páginas e botões de navegação.

Blade

@if ($users->hasPages())
    {{-- Exibe os links de paginação --}}
    {{ $users->links() }} 
@endif

<ul>
    {{-- Itera sobre os itens da página atual --}}
    @foreach ($users->items() as $user) 
        <li>{{ $user->name }}</li>
    @endforeach
</ul>

Por padrão, o Laravel utiliza templates compatíveis com o Tailwind CSS.

B. Personalização e Estilo

Você pode especificar um template de view diferente para os links de paginação, como o estilo Bootstrap:

PHP

// Usa o template Bootstrap 5
{{ $users->links('pagination::bootstrap-5') }}

Se precisar de personalização profunda, você pode publicar as views de paginação:

Bash

php artisan vendor:publish --tag=laravel-pagination
# Views agora estarão em resources/views/vendor/pagination/

C. Parâmetros de Query e Nomeação

Para manter os parâmetros de query (como filtros de busca) nos links de paginação, use o método withQueryString():

PHP

// Mantém o parâmetro 'search' em todos os links gerados
{{ $users->appends(request()->query())->links() }} 
// OU (a partir do Laravel 8)
{{ $users->withQueryString()->links() }}

Se você tiver múltiplos paginadores na mesma página, nomeie-os para evitar conflito de URL:

PHP

// Query Builder: usa 'usersPage' como parâmetro na URL (?usersPage=...)
$users = DB::table('users')->paginate(10, ['*'], 'usersPage');

// Eloquent: usa 'postsPage' como parâmetro na URL (?postsPage=...)
$posts = Post::paginate(5, ['*'], 'postsPage');

3. ✍️ Paginação Manual

Para paginar um array ou uma Collection que não veio do banco de dados (ex: dados de uma API externa), você pode criar um paginador manualmente.

Você precisa de três informações: os itens da página atual, o total de itens e o número de itens por página.

PHP

use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Collection;
use Illuminate\Pagination\Paginator;

$items = Collection::make([/* ... todos os 100 itens ... */]);
$perPage = 10;
$currentPage = Paginator::resolveCurrentPage('page'); // 1, 2, 3...

$paginatedItems = new LengthAwarePaginator(
    $items->slice(($currentPage - 1) * $perPage, $perPage)->values(), // Itens da página atual
    $items->count(),                                                 // Total de itens
    $perPage,                                                        // Itens por página
    $currentPage,                                                    // Número da página atual
    ['path' => request()->url()]                                     // Opções, define o caminho base
);

// $paginatedItems está pronto para ser usado como qualquer outro paginador

4. 🧭 Exemplo Completo com Filtro e Paginação

Este exemplo mostra a combinação de filtros dinâmicos e paginação.

PHP

// App\Http\Controllers\UserController.php

public function index(Request $request)
{
    // 1. Inicia a query do Eloquent
    $query = User::query(); 

    // 2. Aplica filtro condicionalmente
    if ($request->has('search') && $request->search != '') {
        $search = $request->input('search');
        $query->where('name', 'like', "%$search%")
              ->orWhere('email', 'like', "%$search%");
    }

    // 3. Pagina a query final, preservando os parâmetros de busca na URL
    $users = $query->paginate(10)->withQueryString(); 

    return view('users.index', compact('users'));
}

✅ Conclusão Laravel Pagination

Laravel Pagination: O sistema de paginação do Laravel é uma solução robusta e de fácil implementação, crucial para lidar com grandes volumes de dados. Utilizando paginate() ou simplePaginate() no Query Builder ou Eloquent, você pode rapidamente otimizar a carga de dados. O uso do método withQueryString() garante que os filtros sejam mantidos, proporcionando uma experiência de navegação fluida e moderna para o usuário.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: