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

Blog / Keamanan / Cara Menerapkan Role dan Permi...
Keamanan

Cara Menerapkan Role dan Permission Menggunakan Spatie Laravel Permission

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
11 min read
11 views

Instalasi, desain nama permission, seeder idempoten dengan enum, pengecekan di route, controller, Blade, dan API, cache, multi-guard, sampai test. Ditulis untuk spatie/laravel-permission v8 di Laravel 13.

Overview

Hampir setiap aplikasi bisnis butuh pembagian hak akses: siapa boleh melihat laporan keuangan, siapa boleh menyetujui pengeluaran, siapa hanya boleh melihat datanya sendiri. Tanpa sistem yang jelas, kode berakhir penuh dengan:

if ($user->type === 'admin' || $user->type === 'bendahara' || $user->id === 7) { ... }

Kondisi seperti ini tersebar di puluhan file, sulit diaudit, dan setiap perubahan aturan bisnis membutuhkan deploy.

spatie/laravel-permission menyimpan peran (role) dan izin (permission) di database, menghubungkannya ke pengguna, dan mengintegrasikannya dengan sistem otorisasi Laravel (Gate, can(), @can, Policy). Artikel ini membahas penerapan yang rapi dan bisa dirawat.

Hasil akhir:

  • paket terpasang dan terkonfigurasi untuk Laravel 13,
  • konvensi nama permission yang konsisten,
  • daftar role dan permission sebagai PHP enum, di-seed secara idempoten,
  • pengecekan izin di route, controller, Blade, dan API,
  • pemahaman cache permission, guard, dan direct permission,
  • test untuk aturan akses.

Studi kasus lengkap untuk aplikasi RW (admin, bendahara, pengurus, warga) dibahas di artikel berikutnya. Artikel ini fokus pada mekanisme paket.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x (paket v8 mendukung Laravel 12 dan 13)
spatie/laravel-permission ^8.0
Database MySQL 8.0+ / PostgreSQL 15+
Cache Redis atau database untuk production
Testing Pest 4

Sudah ada autentikasi yang berjalan (lihat artikel Panduan Implementasi Login dan Logout Laravel).

Step-by-step Tutorial

Langkah 1: Pahami Model Datanya

Paket ini membuat lima tabel:

roles                    permissions
  id, name, guard_name     id, name, guard_name
        │                        │
        └──── role_has_permissions ────┘

model_has_roles          model_has_permissions
  role_id, model_type,     permission_id, model_type,
  model_id                 model_id

Seorang pengguna mendapatkan izin dari dua sumber:

  1. Lewat role: pengguna punya role bendahara, role itu punya izin kas.create.
  2. Langsung (direct permission): izin diberikan ke pengguna tanpa role.

Aturan utama: kode aplikasi memeriksa permission, bukan role. Role adalah cara mengelompokkan permission untuk memudahkan admin. Bila besok "pengurus" juga boleh mencatat kas, cukup tambahkan permission ke role tersebut, tanpa mengubah kode.

// Kurang baik: aturan bisnis tertanam di kode
if ($user->hasRole('bendahara')) { ... }

// Baik: kode hanya bertanya "boleh atau tidak"
if ($user->can('kas.create')) { ... }

Langkah 2: Instalasi

composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
php artisan optimize:clear
php artisan migrate

Perintah publish menghasilkan config/permission.php dan file migration. Tambahkan trait ke model User:

// app/Models/User.php
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasFactory, Notifiable, HasRoles;
}

Bila Anda memakai UUID/ULID untuk primary key users, sesuaikan kolom model_id di migration yang dipublish sebelum menjalankan migrate.

Langkah 3: Tetapkan Konvensi Nama Permission

Konvensi yang konsisten membuat daftar izin mudah dibaca dan bisa difilter. Gunakan pola sumber.aksi:

Permission Arti
warga.view Melihat daftar warga
warga.create / warga.update / warga.delete Mengelola data warga
kas.view Melihat buku kas
kas.create Mencatat transaksi kas
kas.approve Menyetujui pengeluaran
laporan.export Mengekspor laporan
pengguna.manage Mengelola akun dan peran

Hindari nama seperti admin-panel atau menu-keuangan. Izin sebaiknya mewakili tindakan atas data, bukan elemen tampilan.

Langkah 4: Daftarkan Role dan Permission sebagai Enum

Mulai v8, method findByName() dan findOrCreate() menerima BackedEnum. Ini mencegah salah ketik nama izin di seluruh aplikasi.

// app/Enums/Permission.php
namespace App\Enums;

enum Permission: string
{
    case WargaView     = 'warga.view';
    case WargaCreate   = 'warga.create';
    case WargaUpdate   = 'warga.update';
    case WargaDelete   = 'warga.delete';
    case KasView       = 'kas.view';
    case KasCreate     = 'kas.create';
    case KasApprove    = 'kas.approve';
    case LaporanExport = 'laporan.export';
    case PenggunaManage = 'pengguna.manage';
}
// app/Enums/Role.php
namespace App\Enums;

enum Role: string
{
    case Admin     = 'admin';
    case Bendahara = 'bendahara';
    case Pengurus  = 'pengurus';
    case Warga     = 'warga';

    /** @return list<Permission> */
    public function permissions(): array
    {
        return match ($this) {
            self::Admin     => Permission::cases(),
            self::Bendahara => [Permission::KasView, Permission::KasCreate, Permission::LaporanExport, Permission::WargaView],
            self::Pengurus  => [Permission::WargaView, Permission::WargaCreate, Permission::WargaUpdate, Permission::KasView, Permission::KasApprove],
            self::Warga     => [],
        };
    }
}

Pemetaan role ke permission di enum adalah nilai awal. Bila admin boleh mengubah izin per role lewat UI, perlakukan pemetaan ini hanya sebagai bawaan untuk instalasi baru (lihat Langkah 5).

Langkah 5: Seeder yang Idempoten

// database/seeders/RolePermissionSeeder.php
namespace Database\Seeders;

use App\Enums\{Permission as P, Role as R};
use Illuminate\Database\Seeder;
use Spatie\Permission\Models\{Permission, Role};
use Spatie\Permission\PermissionRegistrar;

class RolePermissionSeeder extends Seeder
{
    public function run(): void
    {
        app(PermissionRegistrar::class)->forgetCachedPermissions();

        foreach (P::cases() as $permission) {
            Permission::findOrCreate($permission, 'web');
        }

        foreach (R::cases() as $role) {
            $model = Role::findOrCreate($role, 'web');

            // Hanya isi izin bawaan bila role baru dibuat,
            // agar perubahan admin lewat UI tidak tertimpa saat seeder dijalankan ulang.
            if ($model->wasRecentlyCreated) {
                $model->syncPermissions(array_map(fn (P $p) => $p->value, $role->permissions()));
            }
        }

        app(PermissionRegistrar::class)->forgetCachedPermissions();
    }
}

Jalankan di semua lingkungan, termasuk production:

php artisan db:seed --class=RolePermissionSeeder --force
php artisan permission:show
+-----------------+-------+-----------+----------+-------+
|                 | admin | bendahara | pengurus | warga |
+-----------------+-------+-----------+----------+-------+
| kas.approve     | ✔     | ·         | ✔        | ·     |
| kas.create      | ✔     | ✔         | ·        | ·     |
| kas.view        | ✔     | ✔         | ✔        | ·     |
| laporan.export  | ✔     | ✔         | ·        | ·     |
| ...             |       |           |          |       |
+-----------------+-------+-----------+----------+-------+

Bila ingin selalu menyamakan izin dengan kode (tanpa pengelolaan lewat UI), ganti kondisi wasRecentlyCreated dengan syncPermissions() biasa.

Langkah 6: Memberi dan Mencabut Akses

$user->assignRole(\App\Enums\Role::Bendahara->value);
$user->syncRoles(['pengurus']);              // ganti semua role menjadi pengurus
$user->removeRole('bendahara');

$user->givePermissionTo('laporan.export');   // direct permission
$user->revokePermissionTo('laporan.export');

$role = Role::findByName('pengurus', 'web');
$role->givePermissionTo('kas.approve');

Sejak v7, method-method ini mengembalikan static, sehingga bisa dirangkai:

$user->syncRoles(['bendahara'])->givePermissionTo('laporan.export');

Gunakan direct permission dengan hemat, misalnya untuk akses sementara. Izin langsung yang menumpuk sulit diaudit, karena tidak terlihat dari daftar role.

Langkah 7: Memeriksa Izin

Di kode PHP, gunakan API otorisasi Laravel. Paket mendaftarkan semua permission ke Gate, sehingga can() bekerja:

$user->can('kas.create');                    // true / false
$user->hasRole('admin');                     // pemeriksaan role (hindari untuk aturan bisnis)
$user->hasAnyPermission(['kas.view', 'kas.create']);
$user->getAllPermissions()->pluck('name');   // gabungan izin dari role + langsung

Di controller:

use Illuminate\Support\Facades\Gate;

public function store(StoreKasRequest $request)
{
    Gate::authorize('kas.create');           // 403 bila tidak berizin
    // ...
}

Di route, daftarkan alias middleware paket terlebih dahulu:

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'role'               => \Spatie\Permission\Middleware\RoleMiddleware::class,
        'permission'         => \Spatie\Permission\Middleware\PermissionMiddleware::class,
        'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
    ]);
})
// routes/web.php
Route::middleware(['auth', 'permission:kas.view'])->group(function () {
    Route::get('kas', [KasController::class, 'index'])->name('kas.index');

    Route::post('kas', [KasController::class, 'store'])
        ->middleware('permission:kas.create');
});

// Beberapa izin: salah satu cukup (pemisah |)
Route::get('laporan', LaporanController::class)->middleware('permission:kas.view|laporan.export');

Middleware bawaan Laravel can: juga bisa dipakai dan tidak membutuhkan alias:

Route::post('kas', [KasController::class, 'store'])->middleware('can:kas.create');

Di Blade:

@can('kas.create')
    <a href="{{ route('kas.create') }}">Catat Transaksi</a>
@endcan

@canany(['laporan.export', 'kas.approve'])
    <x-menu-keuangan />
@endcanany

Menyembunyikan tombol hanyalah kenyamanan tampilan. Pemeriksaan sesungguhnya harus selalu ada di server (route, controller, atau Policy), karena request bisa dikirim langsung tanpa melalui tampilan.

Langkah 8: Super Admin Lewat Gate::before

Daripada memberikan semua permission ke admin satu per satu (dan lupa menambahkan izin baru), beri akses penuh lewat Gate::before:

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::before(fn ($user, $ability) => $user->hasRole('super-admin') ? true : null);
}

Mengembalikan null (bukan false) penting: pemeriksaan biasa tetap berjalan untuk pengguna lain. Batasi jumlah akun super-admin seminimal mungkin dan wajibkan 2FA untuknya.

Gate::before hanya berlaku untuk pemeriksaan lewat Gate (can(), @can, Gate::authorize, middleware can:/permission:). Pemeriksaan langsung seperti hasPermissionTo() dan hasRole() tidak melewatinya.

Langkah 9: Cache Permission

Paket menyimpan seluruh daftar permission di cache selama 24 jam (bawaan) agar pengecekan tidak memukul database. Cache dibersihkan otomatis saat role atau permission diubah lewat method paket. Bersihkan manual bila Anda mengubah tabel langsung lewat SQL atau seeder:

php artisan permission:cache-reset

Untuk aplikasi multi-server, pastikan cache store yang dipakai bersama (Redis atau database), bukan file atau array:

// config/permission.php
'cache' => [
    'expiration_time' => \DateInterval::createFromDateString('24 hours'),
    'key'             => 'spatie.permission.cache',
    'store'           => 'default',
],

Langkah 10: Guard untuk Web dan API

Setiap role dan permission terikat ke satu guard_name. Bila aplikasi punya web (session) dan API (Sanctum), ada dua pilihan:

  1. Satu guard (web) untuk keduanya. Sanctum memakai provider users yang sama; paket akan memakai guard bawaan model. Ini pilihan paling sederhana dan cukup untuk sebagian besar aplikasi.
  2. Guard terpisah bila pengguna API berbeda model atau aturan. Seed permission untuk masing-masing guard dan sebutkan guard secara eksplisit.

Kesalahan umum adalah membuat permission dengan guard api sementara pengguna login lewat web, sehingga muncul There is no permission named ... for guard .... Konsistenlah dengan satu guard kecuali benar-benar butuh lebih.

Langkah 11: Halaman Kelola Peran Pengguna

Contoh controller sederhana untuk admin mengubah role pengguna:

// app/Http/Controllers/Admin/UserRoleController.php
use App\Enums\Role as R;
use Illuminate\Validation\Rule;

public function update(Request $request, User $user)
{
    Gate::authorize('pengguna.manage');

    $validated = $request->validate([
        'roles'   => ['array'],
        'roles.*' => [Rule::enum(R::class)],
    ]);

    if ($user->is($request->user()) && ! in_array(R::Admin->value, $validated['roles'] ?? [], true)) {
        return back()->withErrors(['roles' => 'Anda tidak dapat mencabut peran admin dari akun sendiri.']);
    }

    $user->syncRoles($validated['roles'] ?? []);

    activity('akses')->performedOn($user)->causedBy($request->user())
        ->withProperties(['roles' => $validated['roles'] ?? []])
        ->log('Peran pengguna diubah');

    return back()->with('status', 'Peran diperbarui.');
}

Tiga pengaman di atas: izin pengguna.manage, validasi bahwa role yang dikirim memang ada (Rule::enum), dan larangan admin mengunci dirinya sendiri. Perubahan hak akses juga dicatat ke activity log.

Langkah 12: Test Aturan Akses

// tests/Feature/KasAccessTest.php
use App\Models\User;
use Database\Seeders\RolePermissionSeeder;

beforeEach(fn () => $this->seed(RolePermissionSeeder::class));

it('bendahara boleh mencatat kas', function () {
    $bendahara = User::factory()->create()->assignRole('bendahara');

    $this->actingAs($bendahara)
        ->post('/kas', ['jenis' => 'masuk', 'jumlah' => 50000, 'keterangan' => 'Iuran'])
        ->assertRedirect();
});

it('warga tidak boleh mencatat kas', function () {
    $warga = User::factory()->create()->assignRole('warga');

    $this->actingAs($warga)->post('/kas', [])->assertForbidden();
});

it('setiap role memiliki izin sesuai enum', function (string $role, array $expected) {
    $user = User::factory()->create()->assignRole($role);

    foreach ($expected as $permission) {
        expect($user->can($permission))->toBeTrue("{$role} seharusnya punya {$permission}");
    }
})->with([
    ['bendahara', ['kas.view', 'kas.create', 'laporan.export']],
    ['pengurus',  ['warga.view', 'kas.approve']],
]);

Test terakhir berfungsi sebagai dokumentasi hidup matriks akses: bila seseorang mengubah pemetaan role, test akan memberi tahu.

Troubleshooting

Error / Gejala Penyebab Solusi
There is no permission named 'kas.create' for guard 'web' Permission belum di-seed atau dibuat dengan guard lain Jalankan seeder; samakan guard_name; permission:cache-reset
There is no role named 'bendahara' Role belum di-seed di lingkungan tersebut (sering di test) Seed di beforeEach atau di DatabaseSeeder
Izin baru tidak berlaku Cache permission belum dibersihkan setelah perubahan lewat SQL php artisan permission:cache-reset
Target class [permission] does not exist Alias middleware belum didaftarkan Tambahkan alias di bootstrap/app.php, atau pakai can:
Gate::before super admin tidak bekerja Pemeriksaan memakai hasPermissionTo() langsung Gunakan can() / Gate::authorize()
Error kolom model_id saat assign role Primary key users memakai UUID/ULID Ubah tipe model_id di migration paket sebelum migrate
Event kustom tidak terpanggil setelah upgrade Nama class event berubah di v7 (RoleAttached → RoleAttachedEvent) Perbarui listener sesuai nama baru
Class "...\Commands\CacheReset" not found Nama class command berubah di v7 Perbarui referensi; signature Artisan tetap sama

Best Practices

Keamanan

  • Periksa permission di server untuk setiap aksi; tampilan hanya menyembunyikan tombol.
  • Kode memeriksa permission, bukan role.
  • Batasi akun super admin, wajibkan 2FA, dan catat setiap perubahan role/permission ke activity log.
  • Validasi nama role/permission yang dikirim dari form dengan Rule::enum() atau exists:roles,name.
  • Terapkan prinsip least privilege: role baru dimulai tanpa izin, lalu ditambah seperlunya.

Performa

  • Gunakan cache store bersama (Redis) di production.
  • Eager load relasi saat menampilkan daftar pengguna beserta role: User::with('roles')->paginate().
  • Hindari memanggil getAllPermissions() di dalam loop besar.

Maintainability

  • Simpan nama role dan permission sebagai enum; jangan menulis string bebas di kode.
  • Gunakan konvensi sumber.aksi yang konsisten.
  • Jalankan seeder role/permission sebagai bagian dari proses deploy.
  • Pertahankan test matriks akses di CI.
  • Untuk aturan yang bergantung pada data (misalnya "hanya boleh mengedit iuran miliknya"), gunakan Policy, bukan permission tambahan. Lihat artikel Cara Mengamankan Route, Controller, dan API Laravel.

Related Articles

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

Bagikan artikel:

Artikel lainnya