Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Dashboard Admin, CRUD & Frontend / Cara Membuat Filter, Search, S...
Dashboard Admin, CRUD & Frontend

Cara Membuat Filter, Search, Sorting, dan Pagination yang Efisien di Laravel

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
16 min read
23 views

Halaman daftar yang tetap cepat saat data tumbuh: filter yang divalidasi dan tersimpan di URL, pencarian yang memakai indeks (prefix, FULLTEXT, atau Scout), pengurutan lewat daftar putih, dan pemilihan jenis pagination yang tepat. Disusun dalam class filter yang dapat dipakai ulang untuk tampilan web, API, dan ekspor.

Overview

Hampir setiap halaman admin adalah halaman daftar: data warga, iuran, transaksi kas, pengumuman. Kodenya sering dimulai seperti ini:

$warga = Warga::when($request->q, fn ($q) => $q->where('nama', 'like', "%{$request->q}%"))
    ->orderBy($request->sort ?? 'nama')
    ->paginate(15);

Kode di atas berjalan, tetapi bermasalah:

Masalah Dampak
orderBy($request->sort) Celah injeksi lewat nama kolom
LIKE '%kata%' Tidak bisa memakai indeks; memindai seluruh tabel
paginate() menghitung COUNT(*) setiap halaman Lambat untuk tabel jutaan baris
Filter tidak ikut ke tautan halaman berikutnya Halaman 2 menampilkan data tanpa filter
Logika filter disalin ke ekspor dan API Hasil ekspor berbeda dari yang terlihat

Hasil akhir:

  • Form Request untuk memvalidasi parameter daftar,
  • class filter terpusat (WargaFilter) yang dipakai halaman, API, dan ekspor,
  • tiga strategi pencarian beserta kapan memakainya,
  • pengurutan aman dengan tie-breaker,
  • pemilihan paginate, simplePaginate, atau cursorPaginate,
  • indeks yang sesuai dengan pola query,
  • UI filter berbasis URL dengan Blade,
  • test.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
Database MySQL 8.0+ (InnoDB FULLTEXT) / PostgreSQL 15+
Laravel Scout 10.x (opsional)
Testing Pest 4

Step-by-step Tutorial

Langkah 1: Tentukan Parameter Daftar

Untuk halaman Data Warga:

Parameter Contoh Fungsi
q budi Pencarian nama, NIK, atau nomor KK
rt 3 Filter RT
status aktif, pindah, meninggal Filter status kependudukan
jk L, P Filter jenis kelamin
usia_min / usia_max 17 / 60 Rentang usia
sort nama, -tanggal_lahir Urutan; awalan - berarti menurun
per_page 15, 25, 50 Jumlah per halaman

Semua parameter ada di query string, sehingga URL bisa disimpan, dibagikan, dan tombol kembali browser bekerja.

Langkah 2: Validasi dengan Form Request

// app/Http/Requests/DaftarWargaRequest.php
namespace App\Http\Requests;

use App\Filters\WargaFilter;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class DaftarWargaRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()->can('warga.view');
    }

    protected function prepareForValidation(): void
    {
        $this->merge([
            'q' => $this->filled('q') ? trim((string) $this->q) : null,
        ]);
    }

    public function rules(): array
    {
        return [
            'q'        => ['nullable', 'string', 'min:2', 'max:50'],
            'rt'       => ['nullable', 'integer'],
            'status'   => ['nullable', Rule::in(['aktif', 'pindah', 'meninggal'])],
            'jk'       => ['nullable', Rule::in(['L', 'P'])],
            'usia_min' => ['nullable', 'integer', 'between:0,120'],
            'usia_max' => ['nullable', 'integer', 'between:0,120', 'gte:usia_min'],
            'sort'     => ['nullable', Rule::in(WargaFilter::sortOptions())],
            'per_page' => ['nullable', 'integer', Rule::in([15, 25, 50])],
        ];
    }

    /** Untuk halaman web: parameter tidak valid dibuang, bukan menghasilkan halaman error */
    protected function failedValidation(\Illuminate\Contracts\Validation\Validator $validator): void
    {
        if ($this->expectsJson()) {
            parent::failedValidation($validator);
        }

        foreach (array_keys($validator->failed()) as $field) {
            $this->offsetUnset($field);
        }
        $validator->setData($this->all());
    }
}

Untuk API, parameter tidak valid menghasilkan 422 seperti biasa. Untuk halaman web, parameter yang tidak valid (misalnya hasil mengetik URL manual) dibuang diam-diam sehingga pengguna tetap melihat daftar, bukan halaman error. Bila Anda lebih suka perilaku 422 di semua tempat, hapus method failedValidation().

Bila pendekatan failedValidation() terasa terlalu "pintar", alternatif sederhana adalah tetap memakai validasi standar dan menampilkan pesan error di atas daftar.

Langkah 3: Class Filter Terpusat

// app/Filters/WargaFilter.php
namespace App\Filters;

use App\Models\{User, Warga};
use Illuminate\Database\Eloquent\Builder;

final class WargaFilter
{
    /** Kunci yang boleh dipakai di ?sort= → kolom SQL */
    private const SORTS = [
        'nama'          => 'warga.nama',
        'tanggal_lahir' => 'warga.tanggal_lahir',
        'rt'            => 'warga.rukun_tetangga_id',
        'dibuat'        => 'warga.created_at',
    ];

    public function __construct(private readonly array $params) {}

    public static function sortOptions(): array
    {
        return collect(array_keys(self::SORTS))->flatMap(fn ($k) => [$k, "-{$k}"])->all();
    }

    public function apply(Builder $query, User $user): Builder
    {
        $p = $this->params;

        $query->visibleTo($user)
            ->when($p['rt'] ?? null, fn ($q, $rt) => $q->where('warga.rukun_tetangga_id', $rt))
            ->when($p['status'] ?? null, fn ($q, $s) => $q->where('warga.status', $s))
            ->when($p['jk'] ?? null, fn ($q, $jk) => $q->where('warga.jenis_kelamin', $jk))
            ->when(isset($p['usia_min']), fn ($q) => $q->where('warga.tanggal_lahir', '<=', now()->subYears($p['usia_min'])->toDateString()))
            ->when(isset($p['usia_max']), fn ($q) => $q->where('warga.tanggal_lahir', '>', now()->subYears($p['usia_max'] + 1)->toDateString()));

        $this->search($query, $p['q'] ?? null);
        $this->sort($query, $p['sort'] ?? 'nama');

        return $query;
    }

    private function search(Builder $query, ?string $term): void
    {
        if (blank($term)) {
            return;
        }

        if (ctype_digit($term)) {
            // Angka: cari NIK atau nomor KK dengan prefix (memakai indeks)
            $query->where(fn ($q) => $q
                ->where('warga.nik', 'like', $this->escape($term).'%')
                ->orWhere('warga.nomor_kk', 'like', $this->escape($term).'%'));
            return;
        }

        // Teks: FULLTEXT pada nama (lihat Langkah 4)
        $query->whereFullText('warga.nama', $this->booleanTerm($term), ['mode' => 'boolean']);
    }

    private function sort(Builder $query, string $sort): void
    {
        $desc = str_starts_with($sort, '-');
        $kolom = self::SORTS[ltrim($sort, '-')] ?? self::SORTS['nama'];

        $query->orderBy($kolom, $desc ? 'desc' : 'asc')
              ->orderBy('warga.id', $desc ? 'desc' : 'asc');     // tie-breaker: urutan stabil
    }

    private function escape(string $v): string
    {
        return str_replace(['\\', '%', '_'], ['\\\\', '\%', '\_'], $v);
    }

    /** "budi san" → "+budi* +san*" : semua kata wajib, dengan pencocokan awalan */
    private function booleanTerm(string $term): string
    {
        return collect(preg_split('/\s+/', preg_replace('/[^\pL\pN\s]/u', ' ', $term)))
            ->filter(fn ($w) => mb_strlen($w) >= 2)
            ->map(fn ($w) => "+{$w}*")
            ->implode(' ');
    }
}

Poin desain:

  • Satu class memegang semua aturan filter. Controller halaman, controller API, dan ekspor memanggil class yang sama, sehingga hasilnya konsisten.
  • sort dipetakan lewat daftar putih ke kolom SQL; nilai dari URL tidak pernah langsung masuk ke orderBy.
  • Filter usia diterjemahkan menjadi kondisi pada tanggal_lahir (kolom berindeks), bukan menghitung usia per baris dengan fungsi SQL yang tidak bisa memakai indeks.
  • Karakter operator FULLTEXT dibersihkan dari input pengguna sebelum menyusun kueri boolean.

Langkah 4: Pilih Strategi Pencarian

Strategi Contoh Pakai indeks? Cocok untuk
Prefix LIKE 'kata%' NIK, nomor KK, kode Ya (B-tree) Kode/angka, awal kata
Contains LIKE '%kata%' Bagian di tengah teks Tidak Tabel kecil (< puluhan ribu baris)
FULLTEXT (whereFullText) Nama, judul, isi pengumuman Ya (indeks FULLTEXT) Teks bebas, kata-kata
Laravel Scout Pencarian toleran salah ketik Mesin terpisah Pencarian utama aplikasi, relevansi

Membuat indeks:

// migration
Schema::table('warga', function (Blueprint $table) {
    $table->index(['nik']);
    $table->index(['nomor_kk']);
    $table->fullText('nama');
});

Catatan untuk MySQL InnoDB:

  • Kata yang lebih pendek dari innodb_ft_min_token_size (bawaan 3 karakter) tidak diindeks. Nama seperti "Al" atau "Ed" tidak akan ditemukan lewat FULLTEXT; untuk input pendek, fallback ke prefix LIKE 'kata%'.
  • Daftar stopword bawaan berbahasa Inggris. Untuk teks Indonesia, pertimbangkan mematikan atau mengganti stopword (innodb_ft_enable_stopword) di konfigurasi server.

Bila membutuhkan pencarian yang toleran salah ketik ("budy" menemukan "Budi") atau pengurutan berdasarkan relevansi, gunakan Laravel Scout dengan Meilisearch atau Typesense. Driver database milik Scout juga tersedia sebagai langkah awal tanpa server tambahan:

composer require laravel/scout
// app/Models/Warga.php
use Laravel\Scout\Searchable;

class Warga extends Model
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return ['nama' => $this->nama, 'nik' => $this->nik, 'nomor_kk' => $this->nomor_kk];
    }
}
$ids = Warga::search($term)->keys();            // dari mesin pencari
$query->whereKey($ids);                         // lalu filter & scope lain tetap di SQL

Menggabungkan hasil Scout dengan scope SQL seperti ini praktis untuk hasil yang tidak terlalu banyak. Untuk skala besar, terapkan filter (termasuk cakupan RT) langsung di mesin pencari.

Langkah 5: Pilih Jenis Pagination

Method Query tambahan Tampilan Cocok untuk
paginate() COUNT(*) Nomor halaman + total Daftar admin dengan jumlah data wajar
simplePaginate() Tidak ada Sebelumnya / Berikutnya Tabel besar, total tidak penting
cursorPaginate() Tidak ada; tanpa OFFSET Sebelumnya / Berikutnya Tabel sangat besar, feed, API, infinite scroll

Mengapa ini penting:

  • paginate() menjalankan COUNT(*) dengan semua filter di setiap request. Pada tabel jutaan baris, query hitung ini sering lebih lambat daripada query datanya.
  • OFFSET 200000 memaksa database membaca dan membuang 200.000 baris. cursorPaginate() memakai kondisi WHERE (kolom, id) > (nilai_terakhir) yang memanfaatkan indeks, sehingga halaman ke-10.000 secepat halaman pertama.

Syarat cursorPaginate(): urutan harus berdasarkan kolom yang unik secara gabungan (karena itu ada tie-breaker id), dan pengguna tidak bisa melompat ke halaman tertentu.

Langkah 6: Controller untuk Web, API, dan Ekspor

// app/Http/Controllers/WargaController.php
namespace App\Http\Controllers;

use App\Filters\WargaFilter;
use App\Http\Requests\DaftarWargaRequest;
use App\Http\Resources\WargaResource;
use App\Models\{RukunTetangga, Warga};

class WargaController extends Controller
{
    public function index(DaftarWargaRequest $request)
    {
        $filter = new WargaFilter($request->validated());

        $warga = $filter->apply(Warga::query(), $request->user())
            ->select(['warga.id', 'warga.nama', 'warga.nik', 'warga.jenis_kelamin', 'warga.tanggal_lahir',
                      'warga.status', 'warga.rukun_tetangga_id'])
            ->with('rukunTetangga:id,nomor')
            ->paginate($request->integer('per_page', 15))
            ->withQueryString();                        // filter ikut di tautan halaman

        if ($request->expectsJson()) {
            return WargaResource::collection($warga);
        }

        return view('warga.index', [
            'warga'    => $warga,
            'filter'   => $request->validated(),
            'daftarRt' => RukunTetangga::visibleTo($request->user())->orderBy('nomor')->get(['id', 'nomor']),
        ]);
    }
}

Untuk API yang dipakai aplikasi mobile dengan infinite scroll:

// app/Http/Controllers/Api/WargaController.php
public function index(DaftarWargaRequest $request)
{
    $warga = (new WargaFilter($request->validated()))
        ->apply(Warga::query(), $request->user())
        ->with('rukunTetangga:id,nomor')
        ->cursorPaginate($request->integer('per_page', 25));

    return WargaResource::collection($warga);
}

Untuk ekspor, gunakan filter yang sama dengan lazyById() (lihat artikel Server-Side Processing DataTables untuk contoh ekspor CSV yang aman).

Langkah 7: Indeks yang Sesuai Pola Query

Indeks harus mendukung kombinasi filter (kesamaan) → urutan → tie-breaker:

Schema::table('warga', function (Blueprint $table) {
    $table->index(['rukun_tetangga_id', 'status', 'nama', 'id']);   // filter RT + status, urut nama
    $table->index(['status', 'nama', 'id']);                         // filter status saja, urut nama
    $table->index(['tanggal_lahir', 'id']);                          // urut / rentang usia
});

Jangan membuat indeks untuk setiap kombinasi yang mungkin. Ukur query yang benar-benar sering dipakai (lewat log query lambat atau Telescope), periksa dengan EXPLAIN, lalu tambahkan indeks yang paling berdampak.

Warga::query()->where('rukun_tetangga_id', 3)->where('status', 'aktif')
    ->orderBy('nama')->orderBy('id')->limit(15)->explain()->dd();

Hasil yang baik menunjukkan type: ref atau range dengan nama indeks di kolom key, dan tanpa Using filesort untuk urutan yang sudah tercakup indeks.

Langkah 8: UI Filter Berbasis URL

{{-- resources/views/warga/index.blade.php --}}
<x-layouts.app title="Data Warga">
    <form method="GET" action="{{ route('warga.index') }}" class="mb-4 grid gap-3 sm:grid-cols-6" role="search">
        <x-form.input name="q" label="Cari" :value="$filter['q'] ?? ''" placeholder="Nama, NIK, atau No. KK"
                      class="sm:col-span-2" autocomplete="off" />
        <x-form.select name="rt" label="RT" :value="$filter['rt'] ?? null" placeholder="Semua"
                       :options="$daftarRt->mapWithKeys(fn ($r) => [$r->id => 'RT '.$r->nomor])" />
        <x-form.select name="status" label="Status" :value="$filter['status'] ?? null" placeholder="Semua"
                       :options="['aktif' => 'Aktif', 'pindah' => 'Pindah', 'meninggal' => 'Meninggal']" />
        <x-form.select name="sort" label="Urutkan" :value="$filter['sort'] ?? 'nama'"
                       :options="['nama' => 'Nama A–Z', '-nama' => 'Nama Z–A', '-dibuat' => 'Terbaru', 'tanggal_lahir' => 'Tertua']" />
        <div class="flex items-end gap-2">
            <x-button type="submit">Terapkan</x-button>
            @if (array_filter($filter))
                <x-button variant="ghost" :href="route('warga.index')">Reset</x-button>
            @endif
        </div>
    </form>

    @if (array_filter(\Illuminate\Support\Arr::except($filter, ['sort', 'per_page'])))
        <p class="mb-3 text-sm text-slate-600">
            Menampilkan {{ number_format($warga->total(), 0, ',', '.') }} warga sesuai filter.
        </p>
    @endif

    <x-table :rows="$warga">
        <x-slot:head>
            <th class="px-4 py-3">Nama</th><th class="px-4 py-3">NIK</th>
            <th class="px-4 py-3">RT</th><th class="px-4 py-3">Status</th>
        </x-slot:head>
        @foreach ($warga as $w)
            <tr>
                <x-table.cell><a href="{{ route('warga.show', $w) }}" class="font-medium hover:underline">{{ $w->nama }}</a></x-table.cell>
                <x-table.cell class="tabular-nums">{{ $w->nik_tersamar }}</x-table.cell>
                <x-table.cell>RT {{ $w->rukunTetangga->nomor }}</x-table.cell>
                <x-table.cell>{{ ucfirst($w->status) }}</x-table.cell>
            </tr>
        @endforeach
        <x-slot:empty>
            <x-empty-state title="Tidak ada warga yang cocok" description="Ubah kata kunci atau reset filter." />
        </x-slot:empty>
    </x-table>
</x-layouts.app>

Detail yang membuat halaman ini nyaman dan aman:

  • withQueryString() di controller memastikan tautan halaman 2, 3, dan seterusnya membawa semua filter.
  • Komponen <x-table> (artikel Reusable Blade Components) menampilkan tautan pagination dan empty state.
  • NIK ditampilkan tersamar lewat accessor (3276 •••• •••• 0001) di halaman daftar. Data pribadi lengkap hanya di halaman detail dengan izin yang sesuai.
// app/Models/Warga.php
protected function nikTersamar(): Attribute
{
    return Attribute::get(fn () => $this->nik ? substr($this->nik, 0, 4).' •••• •••• '.substr($this->nik, -4) : null);
}

Untuk pencarian langsung saat mengetik tanpa reload, tambahkan Alpine.js dengan debounce yang mengirim form GET yang sama, misalnya x-on:input.debounce.400ms="$el.form.requestSubmit()".

Langkah 9: Kurangi Biaya Hitung Total

Bila paginate() tetap dibutuhkan (pengguna ingin melihat total) tetapi COUNT(*) mahal:

// Cache total untuk kombinasi filter yang sama selama 1 menit
$key = 'warga:count:'.md5(json_encode([$request->validated(), $request->user()->rukun_tetangga_id]));

$total = Cache::remember($key, 60, fn () =>
    $filter->apply(Warga::query(), $request->user())->toBase()->getCountForPagination());

$warga = $filter->apply(Warga::query(), $request->user())
    ->paginate(perPage: 15, total: $total)
    ->withQueryString();

Parameter total pada paginate() membuat Laravel memakai angka yang Anda berikan alih-alih menjalankan COUNT(*) sendiri.

Langkah 10: Test

// tests/Feature/Warga/DaftarWargaTest.php
beforeEach(function () {
    $this->seed(\Database\Seeders\RolePermissionSeeder::class);
    $this->admin = User::factory()->create()->assignRole('admin');
});

it('menyaring berdasarkan RT dan status', function () {
    $rt = RukunTetangga::factory()->create();
    Warga::factory()->count(3)->for($rt)->create(['status' => 'aktif']);
    Warga::factory()->count(2)->for($rt)->create(['status' => 'pindah']);
    Warga::factory()->count(4)->create(['status' => 'aktif']);

    $this->actingAs($this->admin)
        ->getJson("/warga?rt={$rt->id}&status=aktif")
        ->assertOk()
        ->assertJsonCount(3, 'data');
});

it('mencari berdasarkan awalan NIK', function () {
    Warga::factory()->create(['nik' => '3276011503900001']);
    Warga::factory()->create(['nik' => '3171011503900002']);

    $this->actingAs($this->admin)->getJson('/warga?q=3276')->assertJsonCount(1, 'data');
});

it('menolak kolom urutan di luar daftar putih untuk API', function () {
    $this->actingAs($this->admin)
        ->getJson('/warga?sort='.urlencode('(select 1)'))
        ->assertUnprocessable()
        ->assertJsonValidationErrors('sort');
});

it('membuang parameter tidak valid di halaman web', function () {
    $this->actingAs($this->admin)->get('/warga?sort=password&per_page=100000')->assertOk();
});

it('tautan pagination membawa filter', function () {
    Warga::factory()->count(20)->create(['status' => 'aktif']);

    $this->actingAs($this->admin)->get('/warga?status=aktif')
        ->assertSee('status=aktif&amp;page=2', false);
});

it('urutan stabil antar halaman untuk nama yang sama', function () {
    Warga::factory()->count(30)->create(['nama' => 'Budi Santoso']);

    $hal1 = $this->actingAs($this->admin)->getJson('/warga?per_page=15&page=1')->json('data.*.id');
    $hal2 = $this->actingAs($this->admin)->getJson('/warga?per_page=15&page=2')->json('data.*.id');

    expect(array_intersect($hal1, $hal2))->toBeEmpty();
});

Test pencarian FULLTEXT perlu dijalankan di MySQL/PostgreSQL, bukan SQLite, karena whereFullText() bergantung pada fitur database.

Troubleshooting

Error / Gejala Penyebab Solusi
Halaman 2 kehilangan filter Tidak memakai withQueryString() Tambahkan ->withQueryString() atau ->appends($filters)
Data muncul ganda / hilang antar halaman Urutan tidak unik Tambahkan tie-breaker orderBy('id')
Can't find FULLTEXT index matching the column list Indeks FULLTEXT belum dibuat untuk kolom yang sama persis Buat $table->fullText('nama') sesuai kolom di whereFullText
Pencarian nama pendek ("Al") tidak menemukan hasil Kata di bawah panjang token minimum FULLTEXT Fallback ke prefix LIKE untuk kata pendek
whereFullText error di test SQLite SQLite tidak mendukung FULLTEXT MySQL Jalankan test pencarian di MySQL/PostgreSQL
Halaman daftar lambat walau data sedikit per halaman COUNT(*) mahal atau OFFSET besar Cache total, simplePaginate(), atau cursorPaginate()
cursorPaginate mengembalikan urutan aneh Urutan memakai kolom nullable atau ekspresi Gunakan kolom non-null dan sertakan id sebagai urutan terakhir
Column 'id' in order clause is ambiguous Ada join tanpa prefiks tabel Prefiks semua kolom (warga.id)
Filter usia tidak akurat di sekitar ulang tahun Batas tanggal dihitung keliru Gunakan <= now()->subYears(min) dan > now()->subYears(max + 1)

Best Practices

Keamanan

  • Validasi semua parameter daftar; pengurutan selalu lewat daftar putih.
  • Escape wildcard LIKE dan bersihkan operator FULLTEXT dari input.
  • Terapkan scope cakupan pengguna di class filter, sehingga web, API, dan ekspor otomatis terlindungi.
  • Batasi per_page ke beberapa pilihan tetap.
  • Samarkan data pribadi di halaman daftar.

Performa

  • Pilih strategi pencarian sesuai jenis data: prefix untuk kode, FULLTEXT untuk teks, Scout untuk pencarian utama.
  • Indeks komposit mengikuti pola filter → urutan → id.
  • Pilih jenis pagination sesuai kebutuhan; jangan memakai paginate() tanpa berpikir pada tabel jutaan baris.
  • select() kolom yang ditampilkan saja dan eager load relasi.

Maintainability

  • Satu class filter per sumber data, dipakai ulang di semua tempat.
  • Parameter di URL, bukan session, agar daftar dapat dibagikan dan dapat di-bookmark.
  • Test untuk filter, pencarian, pengurutan tidak valid, dan stabilitas urutan.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4 LTS
Laravel Scout 10.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya