Dari matriks hak akses di atas kertas menjadi kode: role dan permission, pembatasan data per RT, kepemilikan data warga, alur persetujuan kas dengan pemisahan tugas, menu dinamis, dan test yang membuktikan setiap aturan.
Overview
Artikel sebelumnya membahas cara kerja spatie/laravel-permission. Kenyataannya, aturan akses aplikasi sungguhan jarang berhenti di "role X boleh aksi Y". Di aplikasi administrasi RW, aturannya terdengar seperti ini:
- Bendahara boleh mencatat pengeluaran, tetapi tidak boleh menyetujui pengeluaran yang ia catat sendiri.
- Pengurus RT hanya boleh mengelola warga di RT-nya.
- Warga hanya boleh melihat tagihan iuran keluarganya sendiri.
- Seorang pengurus juga warga, sehingga ia punya lebih dari satu peran.
Aturan seperti ini membutuhkan tiga lapisan yang bekerja bersama:
| Lapisan | Pertanyaan | Alat |
|---|---|---|
| Fungsional | Apakah peran ini boleh melakukan aksi ini sama sekali? | Permission (Spatie) |
| Data | Apakah boleh terhadap data yang ini? | Policy |
| Visibilitas | Data mana saja yang boleh dilihat dalam daftar? | Query scope |
Hasil akhir: modul RW dengan empat peran, matriks akses yang terdokumentasi, Policy untuk aturan data, query scope untuk penyaringan daftar, alur persetujuan kas dengan pemisahan tugas, dan test yang mencakup seluruh matriks.
Prerequisites
| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| spatie/laravel-permission | ^8.0 |
| Database | MySQL 8.0+ / PostgreSQL 15+ |
| Testing | Pest 4 |
Diasumsikan Anda sudah mengikuti Cara Menerapkan Role dan Permission Menggunakan Spatie Laravel Permission (paket terpasang, trait HasRoles di model User).
Step-by-step Tutorial
Langkah 1: Tulis Matriks Akses Sebelum Menulis Kode
Duduk bersama pengurus RW dan sepakati matriks ini. Dokumen ini nanti menjadi dasar test.
| Aksi | Admin | Bendahara | Pengurus RT | Warga |
|---|---|---|---|---|
| Melihat daftar warga | Semua | Semua | RT sendiri | — |
| Menambah/mengubah warga | Semua | — | RT sendiri | — |
| Melihat data keluarga sendiri | ✔ | ✔ | ✔ | ✔ |
| Melihat buku kas | ✔ | ✔ | ✔ (ringkasan) | Ringkasan publik |
| Mencatat pemasukan | ✔ | ✔ | — | — |
| Mencatat pengeluaran | ✔ | ✔ | — | — |
| Menyetujui pengeluaran | ✔ | — | ✔ (bukan catatan sendiri) | — |
| Melihat tagihan iuran | Semua | Semua | RT sendiri | Keluarga sendiri |
| Mengekspor laporan | ✔ | ✔ | — | — |
| Mengelola akun & peran | ✔ | — | — | — |
Dua aturan tambahan yang tidak muat di tabel:
- Pemisahan tugas (separation of duties): pencatat pengeluaran tidak boleh menyetujuinya, apa pun perannya.
- Pengeluaran di atas Rp 1.000.000 membutuhkan persetujuan pengurus, tidak cukup admin saja. (Batas ini disimpan sebagai pengaturan, bukan di kode.)
Langkah 2: Struktur Data
// Migration ringkas
Schema::create('rukun_tetangga', function (Blueprint $table) {
$table->id();
$table->string('nomor', 5); // "001"
$table->string('nama_ketua')->nullable();
$table->timestamps();
});
Schema::create('keluarga', function (Blueprint $table) {
$table->id();
$table->foreignId('rukun_tetangga_id')->constrained('rukun_tetangga')->restrictOnDelete();
$table->string('nomor_kk', 16)->unique();
$table->string('alamat');
$table->timestamps();
});
Schema::table('users', function (Blueprint $table) {
$table->foreignId('keluarga_id')->nullable()->constrained('keluarga')->nullOnDelete();
$table->foreignId('rukun_tetangga_id')->nullable()->constrained('rukun_tetangga')->nullOnDelete(); // RT yang diurus (khusus pengurus)
});
Schema::create('transaksi_kas', function (Blueprint $table) {
$table->id();
$table->string('jenis', 10); // masuk | keluar
$table->unsignedBigInteger('jumlah');
$table->string('keterangan');
$table->string('status', 15)->default('draft'); // draft | menunggu | disetujui | ditolak
$table->foreignId('dicatat_oleh')->constrained('users');
$table->foreignId('disetujui_oleh')->nullable()->constrained('users');
$table->timestamp('disetujui_pada')->nullable();
$table->timestamps();
$table->index(['status', 'created_at']);
});
Schema::create('iuran', function (Blueprint $table) {
$table->id();
$table->foreignId('keluarga_id')->constrained('keluarga')->cascadeOnDelete();
$table->string('periode', 7); // "2026-10"
$table->unsignedBigInteger('jumlah');
$table->timestamp('dibayar_pada')->nullable();
$table->timestamps();
$table->unique(['keluarga_id', 'periode']);
});
Perhatikan users.keluarga_id (setiap warga milik satu keluarga) dan users.rukun_tetangga_id (RT yang diurus, hanya terisi untuk pengurus RT). Keduanya berbeda: seorang pengurus RT 003 bisa tinggal di RT 003 atau RT lain.
Langkah 3: Role dan Permission
// app/Enums/Permission.php
enum Permission: string
{
case WargaView = 'warga.view';
case WargaManage = 'warga.manage';
case KasView = 'kas.view';
case KasCreate = 'kas.create';
case KasApprove = 'kas.approve';
case IuranView = 'iuran.view';
case IuranRecord = 'iuran.record';
case LaporanExport = 'laporan.export';
case PenggunaManage = 'pengguna.manage';
}
// app/Enums/Role.php
enum Role: string
{
case Admin = 'admin';
case Bendahara = 'bendahara';
case Pengurus = 'pengurus';
case Warga = 'warga';
public function permissions(): array
{
return match ($this) {
self::Admin => Permission::cases(),
self::Bendahara => [Permission::WargaView, Permission::KasView, Permission::KasCreate,
Permission::IuranView, Permission::IuranRecord, Permission::LaporanExport],
self::Pengurus => [Permission::WargaView, Permission::WargaManage, Permission::KasView,
Permission::KasApprove, Permission::IuranView],
self::Warga => [],
};
}
}
Warga tidak punya permission sama sekali. Akses warga ke data keluarganya sendiri ditentukan oleh kepemilikan data di Policy, bukan oleh permission. Ini pola penting: "boleh melihat miliknya sendiri" hampir tidak pernah perlu dijadikan permission.
Seed dengan seeder idempoten dari artikel sebelumnya. Seorang pengurus yang juga warga cukup diberi dua role:
$user->syncRoles([Role::Pengurus->value, Role::Warga->value]);
Langkah 4: Query Scope untuk Visibilitas Daftar
Policy menjawab pertanyaan per data. Untuk daftar, Anda butuh query yang hanya mengambil data yang boleh dilihat. Jangan mengambil semua lalu menyaring di PHP.
// app/Models/Keluarga.php
use Illuminate\Database\Eloquent\Builder;
public function scopeVisibleTo(Builder $query, User $user): void
{
if ($user->hasRole(Role::Admin->value) || $user->hasRole(Role::Bendahara->value)) {
return; // lihat semua
}
if ($user->can(Permission::WargaView->value) && $user->rukun_tetangga_id) {
$query->where('rukun_tetangga_id', $user->rukun_tetangga_id); // pengurus: RT sendiri
return;
}
$query->whereKey($user->keluarga_id ?? 0); // warga: keluarga sendiri
}
// app/Models/Iuran.php
public function scopeVisibleTo(Builder $query, User $user): void
{
$query->whereHas('keluarga', fn ($q) => $q->visibleTo($user));
}
Di sini pemeriksaan role dipakai secara sadar: cakupan data "semua RT" memang ditentukan oleh jabatan. Bila cakupan ini sering berubah, jadikan permission tersendiri, misalnya warga.view-all.
Langkah 5: Policy untuk Aturan Per Data
php artisan make:policy KeluargaPolicy --model=Keluarga
php artisan make:policy TransaksiKasPolicy --model=TransaksiKas
// app/Policies/KeluargaPolicy.php
namespace App\Policies;
use App\Enums\{Permission, Role};
use App\Models\{Keluarga, User};
class KeluargaPolicy
{
public function viewAny(User $user): bool
{
return $user->can(Permission::WargaView->value);
}
public function view(User $user, Keluarga $keluarga): bool
{
return $user->keluarga_id === $keluarga->id // keluarga sendiri
|| $this->dalamCakupan($user, $keluarga);
}
public function update(User $user, Keluarga $keluarga): bool
{
return $user->can(Permission::WargaManage->value)
&& $this->dalamCakupan($user, $keluarga);
}
private function dalamCakupan(User $user, Keluarga $keluarga): bool
{
if (! $user->can(Permission::WargaView->value)) {
return false;
}
if ($user->hasAnyRole([Role::Admin->value, Role::Bendahara->value])) {
return true;
}
return $user->rukun_tetangga_id !== null
&& $user->rukun_tetangga_id === $keluarga->rukun_tetangga_id;
}
}
// app/Policies/TransaksiKasPolicy.php
namespace App\Policies;
use App\Enums\Permission;
use App\Models\{TransaksiKas, User};
use Illuminate\Auth\Access\Response;
class TransaksiKasPolicy
{
public function create(User $user): bool
{
return $user->can(Permission::KasCreate->value);
}
public function update(User $user, TransaksiKas $trx): bool
{
return $user->can(Permission::KasCreate->value)
&& $trx->dicatat_oleh === $user->id
&& $trx->status === 'draft'; // yang sudah diajukan tidak bisa diubah
}
public function approve(User $user, TransaksiKas $trx): Response
{
if (! $user->can(Permission::KasApprove->value)) {
return Response::deny('Anda tidak memiliki izin menyetujui transaksi.');
}
if ($trx->status !== 'menunggu') {
return Response::deny('Transaksi ini tidak dalam status menunggu persetujuan.');
}
if ($trx->dicatat_oleh === $user->id) {
return Response::deny('Pencatat tidak boleh menyetujui transaksinya sendiri.');
}
// Diambil dari pengaturan aplikasi (misalnya SettingsStore pada artikel starter kit) atau config
$batas = (int) config('rw.batas_persetujuan_pengurus', 1_000_000);
if ($trx->jumlah > $batas && ! $user->hasRole('pengurus')) {
return Response::deny('Pengeluaran di atas batas wajib disetujui pengurus.');
}
return Response::allow();
}
}
Mengembalikan Response::deny('alasan') memberi pesan jelas ke pengguna, yang sangat membantu di aplikasi seperti ini: pengurus langsung tahu kenapa tombol setuju ditolak.
Catatan: aturan
approvesengaja tidak di-bypass oleh admin. Bila Anda memakaiGate::beforeuntuk super admin, pemisahan tugas ikut terlewati. Untuk aturan seperti ini, tambahkan pengecualian diGate::before, misalnyafn ($user, $ability) => $ability !== 'approve' && $user->hasRole('super-admin') ? true : null.
Langkah 6: Alur Persetujuan di Controller
// app/Http/Controllers/TransaksiKasController.php
public function index(Request $request)
{
Gate::authorize(Permission::KasView->value);
$items = TransaksiKas::query()
->with(['pencatat:id,name', 'penyetuju:id,name'])
->latest()
->paginate(20);
return view('kas.index', compact('items'));
}
public function ajukan(TransaksiKas $trx)
{
Gate::authorize('update', $trx);
$trx->update(['status' => 'menunggu']);
return back()->with('status', 'Transaksi diajukan untuk persetujuan.');
}
public function setujui(Request $request, TransaksiKas $trx)
{
Gate::authorize('approve', $trx);
DB::transaction(function () use ($trx, $request) {
$trx = TransaksiKas::lockForUpdate()->findOrFail($trx->id); // cegah persetujuan ganda bersamaan
Gate::forUser($request->user())->authorize('approve', $trx); // periksa ulang setelah dikunci
$trx->update([
'status' => 'disetujui',
'disetujui_oleh' => $request->user()->id,
'disetujui_pada' => now(),
]);
});
return back()->with('status', 'Transaksi disetujui.');
}
// routes/web.php
Route::middleware(['auth', 'auth.session'])->group(function () {
Route::get('kas', [TransaksiKasController::class, 'index'])->name('kas.index');
Route::post('kas', [TransaksiKasController::class, 'store'])->can('create', TransaksiKas::class);
Route::post('kas/{trx}/ajukan', [TransaksiKasController::class, 'ajukan'])->name('kas.ajukan');
Route::post('kas/{trx}/setujui', [TransaksiKasController::class, 'setujui'])->name('kas.setujui');
Route::get('keluarga', [KeluargaController::class, 'index'])->can('viewAny', Keluarga::class);
Route::get('keluarga/{keluarga}', [KeluargaController::class, 'show'])->can('view', 'keluarga');
});
lockForUpdate() di dalam transaksi mencegah dua pengurus menyetujui transaksi yang sama pada saat bersamaan.
Langkah 7: Halaman Warga, Hanya Data Sendiri
// app/Http/Controllers/IuranController.php
public function index(Request $request)
{
$iuran = Iuran::query()
->visibleTo($request->user())
->with('keluarga:id,nomor_kk,alamat')
->latest('periode')
->paginate(24);
return view('iuran.index', compact('iuran'));
}
Controller yang sama melayani admin, bendahara, pengurus, dan warga. Yang berbeda hanyalah data yang dikembalikan scope. Tidak ada percabangan if ($user->hasRole(...)) di controller.
Jangan pernah membaca keluarga_id dari query string untuk warga, misalnya /iuran?keluarga_id=12. Itu pintu IDOR (Insecure Direct Object Reference): warga cukup mengganti angka untuk melihat data tetangganya.
Langkah 8: Menu Dinamis Berdasarkan Izin
// app/View/Composers/NavigationComposer.php
namespace App\View\Composers;
use Illuminate\View\View;
class NavigationComposer
{
public function compose(View $view): void
{
$user = auth()->user();
$menu = collect([
['label' => 'Dasbor', 'route' => 'dashboard', 'can' => null],
['label' => 'Data Warga', 'route' => 'keluarga.index', 'can' => 'warga.view'],
['label' => 'Buku Kas', 'route' => 'kas.index', 'can' => 'kas.view'],
['label' => 'Iuran', 'route' => 'iuran.index', 'can' => null],
['label' => 'Laporan', 'route' => 'laporan.index', 'can' => 'laporan.export'],
['label' => 'Pengguna', 'route' => 'pengguna.index', 'can' => 'pengguna.manage'],
])->filter(fn ($item) => $item['can'] === null || $user?->can($item['can']));
$view->with('menu', $menu);
}
}
// app/Providers/AppServiceProvider.php
View::composer('layouts.app', NavigationComposer::class);
Sekali lagi: menu hanyalah kenyamanan. Setiap route di belakang menu tetap memiliki pemeriksaan sendiri.
Langkah 9: Test Seluruh Matriks
// tests/Feature/Rbac/KeluargaAccessTest.php
use App\Models\{Keluarga, RukunTetangga, User};
use Database\Seeders\RolePermissionSeeder;
beforeEach(function () {
$this->seed(RolePermissionSeeder::class);
$this->rt1 = RukunTetangga::factory()->create();
$this->rt2 = RukunTetangga::factory()->create();
$this->keluargaRt1 = Keluarga::factory()->for($this->rt1)->create();
$this->keluargaRt2 = Keluarga::factory()->for($this->rt2)->create();
});
it('pengurus RT hanya melihat keluarga di RT-nya', function () {
$pengurus = User::factory()->create(['rukun_tetangga_id' => $this->rt1->id])->assignRole('pengurus');
$this->actingAs($pengurus)->get("/keluarga/{$this->keluargaRt1->id}")->assertOk();
$this->actingAs($pengurus)->get("/keluarga/{$this->keluargaRt2->id}")->assertForbidden();
expect(Keluarga::visibleTo($pengurus)->pluck('id')->all())->toBe([$this->keluargaRt1->id]);
});
it('warga hanya melihat keluarganya sendiri', function () {
$warga = User::factory()->create(['keluarga_id' => $this->keluargaRt1->id])->assignRole('warga');
$this->actingAs($warga)->get("/keluarga/{$this->keluargaRt1->id}")->assertOk();
$this->actingAs($warga)->get("/keluarga/{$this->keluargaRt2->id}")->assertForbidden();
$this->actingAs($warga)->get('/keluarga')->assertForbidden();
});
// tests/Feature/Rbac/PersetujuanKasTest.php
use App\Models\{TransaksiKas, User};
beforeEach(fn () => $this->seed(\Database\Seeders\RolePermissionSeeder::class));
it('pencatat tidak bisa menyetujui transaksinya sendiri', function () {
$pengurus = User::factory()->create()->assignRole(['pengurus', 'bendahara']);
$trx = TransaksiKas::factory()->menunggu()->create(['dicatat_oleh' => $pengurus->id, 'jumlah' => 200_000]);
$this->actingAs($pengurus)->post("/kas/{$trx->id}/setujui")->assertForbidden();
});
it('pengurus lain bisa menyetujui', function () {
$bendahara = User::factory()->create()->assignRole('bendahara');
$pengurus = User::factory()->create()->assignRole('pengurus');
$trx = TransaksiKas::factory()->menunggu()->create(['dicatat_oleh' => $bendahara->id, 'jumlah' => 2_500_000]);
$this->actingAs($pengurus)->post("/kas/{$trx->id}/setujui")->assertRedirect();
expect($trx->fresh())->status->toBe('disetujui')->disetujui_oleh->toBe($pengurus->id);
});
it('admin tidak bisa menyetujui pengeluaran di atas batas', function () {
$admin = User::factory()->create()->assignRole('admin');
$trx = TransaksiKas::factory()->menunggu()->create(['jumlah' => 5_000_000]);
$this->actingAs($admin)->post("/kas/{$trx->id}/setujui")->assertForbidden();
});
Setiap baris matriks di Langkah 1 sebaiknya punya minimal satu test "boleh" dan satu test "tidak boleh".
Troubleshooting
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Pengurus melihat warga RT lain di daftar | Daftar tidak memakai visibleTo() |
Terapkan scope di setiap query daftar, termasuk ekspor dan pencarian |
| Warga bisa melihat data tetangga lewat ganti ID di URL | Hanya daftar yang disaring, detail tidak diperiksa | Tambahkan ->can('view', 'keluarga') atau Gate::authorize('view', ...) di setiap route detail |
| Pesan 403 generik, pengguna bingung | Policy mengembalikan false |
Kembalikan Response::deny('alasan') |
| Admin bisa menyetujui transaksi sendiri | Gate::before super admin melewati Policy |
Kecualikan ability sensitif dari Gate::before |
| Transaksi disetujui dua kali | Dua request bersamaan | lockForUpdate() dalam transaksi dan periksa ulang status |
Pengurus RT tanpa rukun_tetangga_id melihat semua data |
Scope tidak menangani nilai kosong | Pastikan cabang default selalu membatasi (seperti whereKey($user->keluarga_id ?? 0)) |
| Ekspor laporan berisi data di luar cakupan | Ekspor memakai query terpisah tanpa scope | Pakai scope yang sama untuk tampilan dan ekspor |
Best Practices
Keamanan
- Default menolak: setiap scope dan Policy harus berakhir dengan cabang paling ketat.
- Periksa akses di daftar (scope) dan di detail (Policy); keduanya wajib.
- Terapkan pemisahan tugas untuk transaksi keuangan dan jangan biarkan super admin melewatinya.
- Jangan pernah menerima ID pemilik data dari input untuk pengguna biasa; ambil dari pengguna yang login.
- Catat persetujuan, penolakan, dan perubahan peran di activity log.
Performa
- Scope
visibleTo()harus tetap berupa kondisi SQL agar bisa dipaginasi dan diindeks; pasang indeks padarukun_tetangga_iddankeluarga_id. - Cache izin pengguna sudah ditangani Spatie; hindari query role berulang di dalam loop tampilan dengan memuatnya sekali (
$user->loadMissing('roles')).
Maintainability
- Matriks akses adalah dokumen hidup: simpan di
docs/akses.mddan jadikan dasar test. - Permission untuk aksi fungsional, Policy untuk aturan data, scope untuk visibilitas daftar. Jangan mencampur ketiganya.
- Simpan angka bisnis (batas persetujuan) di pengaturan aplikasi, bukan konstanta di kode.
- Satu controller untuk semua peran; perbedaan akses ditangani scope dan Policy, bukan percabangan.
Related Articles
- Cara Menerapkan Role dan Permission Menggunakan Spatie Laravel Permission
- Cara Mengamankan Route, Controller, dan API Laravel Menggunakan Middleware dan Policy
- Soft Delete, Audit Trail, dan Activity Log: Cara Melacak Perubahan Data Aplikasi
- Membangun Laravel Starter Kit yang Reusable untuk Berbagai Jenis Aplikasi Bisnis
Last Tested
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| spatie/laravel-permission | 8.x |
| MySQL | 8.4 LTS |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |