PauloRB.dev

Formas de Paginação de Dados no Laravel

Por Paulo RB em 21/10/2024

No desenvolvimento de aplicações web, a paginação de dados é um recurso fundamental quando se trabalha com grandes volumes de registros. O Laravel, um dos frameworks PHP mais populares, oferece diversas abordagens para implementar a paginação de maneira eficiente e prática. Neste artigo, vamos explorar as formas mais comuns de paginação no Laravel: o método paginate, a combinação de take e skip, e o uso de limit e offset.

Paginação com paginate

O método mais simples e direto oferecido pelo Laravel é o paginate(), que detecta automaticamente os parâmetros de página e itens por página diretamente da URL da requisição. Ele é ideal para casos em que você deseja implementar uma paginação completa com total de páginas, links para navegação, e controle fácil de quantos registros exibir por página.

A URL típica de uma paginação com paginate teria a seguinte forma:

/?paginacao?page=2&per_page=15

Neste exemplo, a variável page define a página atual e per_page indica a quantidade de itens por página. O Laravel trata esses parâmetros automaticamente e calcula quantos registros devem ser ignorados e quais devem ser retornados.

Exemplo de código:

use Illuminate\Http\Request;
use App\Models\Grupo;

Route::get('/paginacao', function (Request $request) {
    $query = Grupo::query();

    // Aplicar filtros de busca
    foreach (['id', 'nome', 'formula', 'numero', 'checklist_id'] as $field) {
        if ($request->has($field)) {
            $query->where($field, 'ilike', '%' . $request->input($field) . '%');
        }
    }

    // Aplicar ordenação
    if ($request->has('sortColumn') && $request->has('sortDirection')) {
        $query->orderBy($request->input('sortColumn'), $request->input('sortDirection'));
    }

    // Retornar a paginação em JSON
    return response()->json($query->paginate($request->input('per_page', 10)));
});

No exemplo acima, aplicamos filtros e ordenações à query e utilizamos o método paginate(), que receberá como parâmetro o número de itens por página. Caso o parâmetro per_page não seja passado, o valor padrão será 10.

Paginação com skip e take

Outra abordagem comum no Laravel é o uso de skip() e take(). Esses métodos oferecem mais controle sobre como os registros são paginados, sendo úteis em situações específicas, como quando você não precisa de uma paginação completa com links ou metadados, mas deseja carregar apenas uma parte dos registros.

• skip(): Define quantos registros serão ignorados.
• take(): Define quantos registros serão retornados após os ignorados.

Exemplo de código:

use Illuminate\Http\Request;
use App\Models\Grupo;

Route::get('/paginacao-custom', function (Request $request) {
    $query = Grupo::query();

    // Aplicar filtros de busca
    foreach (['id', 'nome', 'formula', 'numero', 'checklist_id'] as $field) {
        if ($request->has($field)) {
            $query->where($field, 'ilike', '%' . $request->input($field) . '%');
        }
    }

    // Aplicar ordenação
    if ($request->has('sortColumn') && $request->has('sortDirection')) {
        $query->orderBy($request->input('sortColumn'), $request->input('sortDirection'));
    }

    $page = $request->input('page', 1);
    $perPage = $request->input('per_page', 10);

    // Paginação usando skip e take
    $query->skip(($page - 1) * $perPage)->take($perPage);

    return response()->json($query->get());
});

Neste exemplo, skip() ignora os registros da página anterior e take() define quantos registros devem ser retornados.

Paginação com limit e offset

A combinação de limit e offset funciona de maneira similar ao skip e take, sendo mais próxima do SQL puro. Essa abordagem também é útil quando se busca otimização em consultas, especialmente em cenários que envolvem bancos de dados grandes ou customizações complexas.

• limit(): Define o número máximo de registros a serem retornados.
• offset(): Define quantos registros devem ser ignorados no início.

Exemplo de código:

use Illuminate\Http\Request;
use App\Models\Grupo;

Route::get('/paginacao-sql', function (Request $request) {
    $query = Grupo::query();

    // Aplicar filtros de busca
    foreach (['id', 'nome', 'formula', 'numero', 'checklist_id'] as $field) {
        if ($request->has($field)) {
            $query->where($field, 'ilike', '%' . $request->input($field) . '%');
        }
    }

    // Aplicar ordenação
    if ($request->has('sortColumn') && $request->has('sortDirection')) {
        $query->orderBy($request->input('sortColumn'), $request->input('sortDirection'));
    }

    $page = $request->input('page', 1);
    $perPage = $request->input('per_page', 10);

    // Paginação usando limit e offset
    $query->limit($perPage)->offset(($page - 1) * $perPage);

    return response()->json($query->get());
});

A diferença principal entre skip/take e limit/offset está na forma de funcionamento, onde limit e offset são mais comumente usados em queries SQL brutas, enquanto skip e take são métodos encadeáveis dentro do Eloquent.

Qual método escolher?

• paginate: Ideal para a maioria das situações em que se deseja uma paginação automática, com links e total de registros.
• skip/take: Útil quando você deseja uma paginação simples, sem necessidade de metadados ou links.
• limit/offset: Preferível quando você trabalha diretamente com queries SQL e precisa de controle total sobre a execução da consulta.

Cada uma dessas abordagens oferece flexibilidade, dependendo da necessidade do projeto. O Laravel facilita a implementação de qualquer uma dessas técnicas, garantindo que você tenha o melhor desempenho possível na exibição dos dados.

Com essas opções, você poderá escolher a melhor forma de implementar a paginação no seu projeto Laravel, levando em consideração o tamanho do dataset, a complexidade da query, e a experiência de navegação que deseja proporcionar ao usuário.