Cara Membuat Filter, Search, Sorting, dan Pagination yang Efisien di Laravel
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
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.
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:
WargaFilter) yang dipakai halaman, API, dan ekspor,paginate, simplePaginate, atau cursorPaginate,| 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 |
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.
// 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.
// 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:
sort dipetakan lewat daftar putih ke kolom SQL; nilai dari URL tidak pernah langsung masuk ke orderBy.tanggal_lahir (kolom berindeks), bukan menghitung usia per baris dengan fungsi SQL yang tidak bisa memakai indeks.| 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:
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%'.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.
| 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.
// 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).
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.
{{-- 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.<x-table> (artikel Reusable Blade Components) menampilkan tautan pagination dan empty state.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()".
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.
// 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&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.
| 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) |
Keamanan
LIKE dan bersihkan operator FULLTEXT dari input.per_page ke beberapa pilihan tetap.Performa
id.paginate() tanpa berpikir pada tabel jutaan baris.select() kolom yang ditampilkan saja dan eager load relasi.Maintainability
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| Laravel Scout | 10.x |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Panduan Membuat Dashboard Statistik Laravel dengan Chart, Filter, dan Data Real-Time
Berikutnya
Upload Gambar, Media Library, dan Image Preview: Panduan Pengelolaan Media Laravel
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk