@extends('layouts.docs') @section('title', 'Paginação - OG Framework') @section('body')
@include('docs.partials.sidebar')
Voltar para Documentação

Database

Sistema de Paginação

Componente simples e eficiente para paginação de resultados de queries, especialmente importante para listagens com milhares de registos.

{{-- Introduction --}}

Porquê Paginar?

Imagina que tens uma tabela com 50.000 facturas. Se fizeres um SELECT * sem limites, vais transferir megabytes de dados, sobrecarregar o servidor, e travar o browser do utilizador. A paginação resolve isto: em vez de trazer tudo, traz apenas 20 ou 50 registos de cada vez.

O sistema de paginação do OfficeGest integra-se directamente com o Query Builder, tornando trivial implementar listagens eficientes.

{{-- Quick Start --}}

Uso Básico

O método paginate() do Query Builder faz tudo automaticamente: adiciona LIMIT e OFFSET à query, conta o total de registos, e devolve um objecto Paginator com toda a informação necessária.

Exemplo Completo

public function index(Request $request)
{
    // O método paginate() lê automaticamente ?page=X do request
    // O segundo parâmetro define quantos registos por página (default: 15)
    $results = $this->db->table('invoices')
        ->where('status', 'pending')
        ->orderBy('created_at', 'desc')
        ->paginate(20);

    // $results é um objecto Paginator
    // Pode ser devolvido directamente como JSON
    return response()->json($results);
}
{{-- Paginator Object --}}

O Objecto Paginator

Quando chamas paginate(), recebes um objecto Paginator que contém não só os dados, mas também metadados sobre a paginação. Isto é essencial para o frontend construir a navegação.

Métodos Disponíveis

Método Descrição
items() Devolve o array com os registos da página actual
total() Número total de registos (todas as páginas)
perPage() Quantos registos por página
currentPage() Número da página actual (começa em 1)
lastPage() Número da última página
hasMorePages() True se existem mais páginas depois desta
links() Array de links para navegação (útil para o frontend)
{{-- JSON Response --}}

Estrutura da Resposta JSON

O Paginator implementa JsonSerializable, por isso podes devolvê-lo directamente numa resposta. O formato é pensado para ser fácil de consumir no frontend.

Estrutura Típica

{
    "items": [
        {"id": 1, "number": "FT 2024/001", "total": 150.00},
        {"id": 2, "number": "FT 2024/002", "total": 230.50}
    ],
    "total": 1532,
    "per_page": 20,
    "current_page": 3,
    "last_page": 77,
    "has_more_pages": true,
    "links": [
        {"page": 1, "url": "?page=1&limit=20"},
        {"page": 2, "url": "?page=2&limit=20"},
        {"page": 3, "url": "?page=3&limit=20", "active": true},
        {"page": 4, "url": "?page=4&limit=20"}
    ]
}

No frontend (Vue, React, etc.), podes usar estes dados para mostrar "Página 3 de 77" e construir botões de navegação.

{{-- Manual Pagination --}}

Paginação Manual

Por vezes tens dados que não vêm de uma query SQL — por exemplo, resultados de uma API externa, ou dados em memória. Nestes casos, podes criar um Paginator manualmente. 

use Og\Modules\Common\Pagination\Paginator;

// Imagina que tens um array com todos os resultados
$allItems = $this->externalApi->fetchAllProducts();
$total = count($allItems);

// Calcular qual fatia mostrar
$page = $request->get('page', 1);
$perPage = 10;
$items = array_slice($allItems, ($page - 1) * $perPage, $perPage);

// Criar o Paginator manualmente
$paginator = new Paginator($items, $total, $perPage, $page);

return response()->json($paginator);
{{-- Navigation --}}
CLI Crawler
@include('docs.partials.toc', ['sections' => [ 'introducao' => 'Porquê Paginar?', 'quick-start' => 'Uso Básico', 'paginator' => 'Paginator', 'json' => 'Resposta JSON', 'manual' => 'Paginação Manual', ]])
@endsection