susantokun/lir-kit
| Install | |
|---|---|
composer require susantokun/lir-kit |
|
| Latest Version: | v0.1.0 |
| PHP: | ^8.3 |
| Laravel: | 12 · 13 |
| License: | MIT |
| Last Updated: | Nov 17, 2026 |
| Links: | GitHub · Packagist |
lir-kit
Paket Laravel + Inertia + React yang berisi tiga fitur siap pakai:
- Login tanpa kata sandi (email + OTP) yang bisa diatur: kata sandi saja, kode email saja, atau keduanya. Kode disimpan ter-hash, sekali pakai, kedaluwarsa, dibatasi percobaan, dan tidak membocorkan apakah email terdaftar.
- Email pengirim dari UI: server SMTP, alamat pengirim, kata sandi terenkripsi, tombol kirim email uji, dan template email kode (subjek + isi) yang bisa diubah, dengan layout HTML yang sudah rapi.
- Editor menu sidebar: ganti judul dan ikon, ubah urutan, sembunyikan, tambah tautan atau folder sendiri (sampai tiga level), per tenant bila aplikasi Anda multi-tenant.
Di kode kit, teks sumber ditulis Bahasa Indonesia (__() dan t()); terjemahan Inggris ikut dikirim.
Isi paket
| Bagian | Lokasi | Cara sampai ke aplikasi |
|---|---|---|
| Backend (rute, controller, model, migrasi, notifikasi, layanan) | src/, routes/, database/ |
otomatis (service provider + composer update) |
| Konfigurasi | config/lir-kit.php |
vendor:publish --tag=lir-kit-config |
| Layout email | resources/views/mail |
otomatis; salin bila ingin mengubah: --tag=lir-kit-views |
| Komponen dan layout React (shell, layout auth, kartu pengaturan) | resources/js |
disalin ke resources/js/lir-kit dengan --tag=lir-kit-js (boleh ditimpa saat update) |
| Starter (halaman auth, layout aplikasi, menu, merek) | stubs/starter |
diterbitkan sekali dengan --tag=lir-kit-starter; setelah itu milik proyek Anda |
Syarat
PHP 8.3+, Laravel 12/13, Inertia (React), Tailwind v4 + komponen shadcn/ui (gaya base-nova, Base UI) di @/components/ui:
alert, avatar, badge, breadcrumb, button, card, collapsible, dialog, dropdown-menu, field, input, input-group, kbd, table, checkbox,
popover, radio-group, scroll-area, separator, sheet, sidebar, skeleton, spinner, switch, textarea, tooltip.
Tambah yang belum ada dengan npx shadcn@latest add <nama> (sidebar ikut membawa @/hooks/use-mobile). Ikon memakai lucide-react.
1. Pasang
Paket ada di Packagist, jadi cukup:
composer require susantokun/lir-kit
php artisan migrate
php artisan vendor:publish --tag=lir-kit-config
php artisan vendor:publish --tag=lir-kit-js
migrate membuat tabel berawalan lir_: lir_login_codes, lir_settings, lir_menu_settings, ditambah lir_roles, lir_role_permissions, lir_role_user (peran).
1a. Pilih bagian yang dipakai (opsional)
Secara bawaan semua bagian aktif. Bila hanya butuh sebagian, jalankan installer, atau ubah features di config/lir-kit.php:
php artisan lir-kit:install # pilih lewat daftar, bisa diulang untuk mengubah pilihan
php artisan lir-kit:install --only=otp,audit --starter # tanpa tanya (untuk skrip dan CI); --all untuk semuanya
| Bagian | Isi | Catatan |
|---|---|---|
otp |
login kode email dan pengaturan metode masuk | butuh mail (ikut dinyalakan otomatis) |
mail |
email pengirim dan template email | saat mati, MAIL_* di .env tidak ditimpa |
menu |
editor menu sidebar | |
access |
pengguna, peran, hak akses | perintah lir-kit:grant |
audit |
log audit tahan-ubah | perintah lir-kit:audit-verify; mati = aksi hanya masuk Log::info |
site |
nama, logo, favicon | |
license |
license aplikasi | perintah lir-kit:license-check; tetap tidak membatasi apa pun sebelum license.enforce |
Bagian yang dimatikan tidak mendaftarkan rute dan perintah artisan (jawabannya 404, bukan 403). Menunya hilang di starter bila Anda membagikan prop features
('features' => fn () => \Lir\Kit\LirKit::features() di middleware Inertia); tanpa prop itu semua menu tampil. Mode "OTP saja" yang pernah tersimpan diabaikan bila otp dimatikan.
Tabel lir_* tetap dibuat oleh migrate walau bagiannya mati (kosong dan tidak berbahaya). Installer: menulis features, menjalankan migrate (kecuali --no-migrate),
menyalin komponen React (kecuali --no-js), dan dengan --starter menyalin hanya halaman starter milik bagian yang dipilih (berkas yang ada tidak ditimpa tanpa --force).
Proyek yang sudah berjalan tidak perlu apa-apa: tanpa features, semuanya tetap aktif seperti sebelumnya.
1b. Pasang starter (UI siap pakai, opsional tetapi disarankan)
Starter memberi proyek baru tampilan lengkap seperti aplikasi jadi: halaman masuk berpanel merek, lupa dan atur ulang kata sandi, tantangan 2FA, verifikasi email, serta kerangka aplikasi (sidebar tiga level yang bisa diciutkan, bilah atas dengan breadcrumb dan pencarian Ctrl K, menu akun, tema terang/gelap, tampilan ponsel).
php artisan vendor:publish --tag=lir-kit-js # komponen dan layout inti: resources/js/lir-kit (diperbarui lewat update)
php artisan vendor:publish --tag=lir-kit-starter # halaman, layout aplikasi, config merek dan menu: milik Anda
Tag lir-kit-starter menaruh berkas ini (tidak menimpa berkas yang sudah ada kecuali dengan --force):
| Berkas | Isi |
|---|---|
resources/js/pages/auth/{login,forgot-password,reset-password,two-factor-challenge,verify-email}.tsx |
halaman auth (memanggil URL bawaan Fortify: /login, /forgot-password, /reset-password, /two-factor-challenge, /email/verification-notification) |
resources/js/pages/settings/{login-method,mail,menu,profile,security,appearance}.tsx |
halaman pengaturan: metode masuk, email pengirim dan template, editor menu, profil, keamanan (kata sandi dan 2FA), tema |
resources/js/layouts/app-layout.tsx, settings-page.tsx |
bingkai halaman: <AppLayout title="...">, dan <SettingsPage title="..."> untuk halaman pengaturan (menu samping dari folder menu yang memuatnya) |
resources/js/config/brand.ts |
nama aplikasi dan teks panel kiri halaman masuk |
resources/js/config/nav.ts |
menu aplikasi (tiga level); satu baris per halaman |
resources/css/lir-kit-starter.css |
animasi panel masuk; @import dari app.css Anda |
Halaman profil, keamanan, dan 2FA memanggil endpoint akun Fortify (PUT /user/profile-information, PUT /user/password, /user/two-factor-*); bagikan prop twoFactor: { enabled, pending } ke halaman (mis. di middleware Inertia). Halaman pengaturan kit (metode masuk, email, menu) tetap memerlukan ability lir-kit.manage di server.
Halaman Inertia dipetakan dari resources/js/pages, jadi di Laravel Fortify cukup Fortify::loginView(fn () => Inertia::render('auth/login', LirKit::loginProps(request()))) dan seterusnya.
Pembagian tugasnya: layout dan komponen inti ada di paket (@/lir-kit/layouts/app-shell, auth-split-layout, shell/*) dan ikut diperbarui; halaman dan konfigurasi ada di proyek Anda dan boleh diubah bebas.
Kerangka menerima merek, menu, pengguna, dan slot (sidebarHeader, headerActions, userMenuExtra, toaster, onSearch) lewat props, jadi fitur khusus aplikasi (pilih perusahaan, notifikasi) dipasang di app-layout.tsx tanpa mengubah kit.
1c. Pengguna, peran, dan hak akses (opsional)
Kit membawa layar Pengguna (cari, undang, ubah, nonaktifkan, hapus) dan Peran (kumpulan hak akses), lengkap dengan komponen UsersPanel/RolesPanel dan halaman starter pages/access/{users,roles}.tsx. Setelah php artisan migrate (membuat lir_roles, lir_role_permissions, lir_role_user):
- Daftarkan hak akses aplikasi di
config/lir-kit.php. Kunci hak akses sama dengan nama ability Gate:
Tanpa'users_ability' => 'lir-kit.users', 'roles_ability' => 'lir-kit.roles', 'permissions' => ['Laporan' => ['laporan.lihat' => 'Melihat laporan']], 'register_gate' => true, // pemegang hak akses (atau Superadmin) otomatis lolos ability ituregister_gate, panggil$user->hasLirPermission('laporan.lihat')(traitLir\Kit\Concerns\HasLirRolesdi model User) dari Gate Anda sendiri. - Buat Superadmin pertama dari terminal:
php artisan lir-kit:grant email@anda.co.id(peransuperadminbawaan memegang semua hak akses dan tidak bisa diubah). - Bagikan hak akses ke halaman supaya menu menyembunyikan yang tidak boleh dibuka:
'permissions' => fn () => \Lir\Kit\LirKit::permissions($request->user())di middleware Inertia (danauth.user.id).config/nav.tsstarter memetakan halaman ke hak akses lewatREQUIRES.
Pengguna tetap milik aplikasi: kit membacanya lewat Lir\Kit\Contracts\UserDirectory (bawaan: model Eloquent di user_model dengan kolom name, email, dan status bila ada). Ikat implementasi sendiri bila pengguna Anda hidup di tempat lain. Undangan mengirim email berisi tautan masuk; bila masuk dengan kode email aktif, pengguna cukup memakai kode, jika tidak email membawa tautan atur kata sandi (rute password.reset milik aplikasi). Peran dipisah per tenant mengikuti tenant_resolver; Superadmin terakhir dan akun yang sedang dipakai tidak bisa dihapus atau dinonaktifkan.
2. Beri izin (wajib)
Semua layar pengaturan dijaga ability lir-kit.manage. Tanpa definisi, semuanya tertutup (403). Di AppServiceProvider::boot():
Gate::define('lir-kit.manage', fn ($user) => $user->isSuperadmin());
3. Hubungkan ke aturan aplikasi (opsional tapi disarankan)
Kit bekerja apa adanya, tetapi aplikasi Anda mungkin punya aturan sendiri: akun nonaktif, SSO wajib, satu sesi
per orang, 2FA, riwayat login, audit. Buat satu kelas yang mengimplementasikan Lir\Kit\Contracts\LoginHooks:
class AppLoginHooks implements LoginHooks
{
public function canReceiveCode(Authenticatable $user): bool { return $user->isActive() && ! $user->mustUseSso(); }
public function sessionConflict(Authenticatable $user): ?array { /* ['ip','device','location','last_activity'] atau null */ }
public function requiresSecondFactor(Authenticatable $user): bool { return $user->two_factor_confirmed_at !== null; }
public function signedIn(Authenticatable $user): void { /* akhiri sesi lain, catat login terakhir */ }
public function recordLogin(string $event, ?Authenticatable $user, ?string $identifier, ?string $detail): void { /* riwayat login */ }
public function audit(string $action, ?Authenticatable $actor, mixed $before = null, mixed $after = null): void { /* log audit */ }
}
// AppServiceProvider::register()
$this->app->bind(\Lir\Kit\Contracts\LoginHooks::class, AppLoginHooks::class);
Pengaturan lain di config/lir-kit.php: menu_ability (izin terpisah untuk editor menu), user_model, guard, login_route, two_factor_route, redirect_after_login,
tenant_resolver (mis. fn () => app(CurrentCompany::class)->id()), dan menu_locked.
4. Pakai login OTP
Server. Di tempat Anda merender halaman login, gabungkan props kit; dan tutup form kata sandi saat mode "OTP saja":
Inertia::render('auth/login', [/* props Anda */] + \Lir\Kit\LirKit::loginProps($request));
Middleware lir.password-allowed (alias dari kit) menutup login kata sandi bila admin memilih "OTP saja". Pasang di rute POST login Anda;
dengan Fortify, tambahkan Lir\Kit\Http\Middleware\EnsurePasswordLoginAllowed::class paling awal di Fortify::authenticateThrough().
React. Di halaman login Anda:
import { OtpLoginForm } from '@/lir-kit/otp-login-form';
const { loginMode, otpEmail, otpLength, resendIn, devCode } = usePage().props;
const showOtp = loginMode === 'otp' || (loginMode === 'both' && (chooseOtp || !!otpEmail));
{showOtp
? <OtpLoginForm otpEmail={otpEmail} length={otpLength} resendIn={resendIn} devCode={devCode} />
: /* form kata sandi Anda */}
{loginMode === 'both' && <Button onClick={() => setChooseOtp(!chooseOtp)}>…</Button>}
Rute yang dipakai (sudah terdaftar kit): POST /login/otp/send|verify|resend|cancel.
Saat APP_ENV=local, kode juga ditampilkan di halaman (matikan dengan LIR_SHOW_CODE_LOCALLY=false). Di environment lain tidak pernah.
5. Pakai layar pengaturan
Kit hanya menyediakan komponen; Anda menaruhnya di halaman pengaturan sendiri:
import { LoginMethodCard } from '@/lir-kit/login-method-card';
import { MailSettingsCard } from '@/lir-kit/mail-settings-card';
import { LoginCodeEmailCard } from '@/lir-kit/login-code-email-card';
<LoginMethodCard /> <LoginCodeEmailCard /> <MailSettingsCard />
Komponen memanggil GET/PUT /lir-kit/... (ubah awalan lewat routes.api_prefix dan KIT_API di adapters.ts).
Email pengirim yang disimpan menimpa MAIL_* di .env untuk semua email aplikasi saat saklarnya menyala.
Menyimpan mode OTP ditolak di server produksi bila email belum bisa terkirim (mailer log/array), supaya tidak mengunci semua orang.
6. Pakai editor menu
- Bagikan susunan tersimpan ke semua halaman (Inertia middleware
share()):'menuOverrides' => fn () => $request->user() ? \Lir\Kit\LirKit::menuOverrides() : [], - Terapkan ke menu Anda. Beri tiap kelompok dan folder
keyyang tetap (halaman: kuncinyahref), lalu:
Tautan buatan sendiri ke situs luar punyaimport { applyMenu, setLockedKeys } from '@/lir-kit/menu'; setLockedKeys(['/dashboard', '/settings/menu']); // samakan dengan config 'menu_locked' const groups = applyMenu(buildMyNav(permissions), menuOverrides);external/newTab; render sebagai<a target="_blank" rel="noopener noreferrer">. - Halaman editor:
import { MenuEditor } from '@/lir-kit/menu-editor'; <MenuEditor base={buildMyNav(ALL_PERMISSIONS)} onSaved={() => router.reload({ only: ['menuOverrides'] })} />baseadalah menu bawaan lengkap (semua izin dianggap ada) supaya editor melihat semua entri.
Menyembunyikan menu hanya soal tampilan; rute dan izin tetap menjadi pagar yang sebenarnya.
Tautan buatan sendiri hanya menerima https://, http://, atau alamat internal berawalan / (tidak javascript:, tidak //host).
6b. Pakai Log Audit
Setiap aksi yang dicatat kit (pengguna, peran, menu, metode masuk, email, situs) masuk ke tabel lir_audit_logs lewat LoginHooks::audit() bawaan
(php artisan migrate). Tiap entri menyimpan hash entri sebelumnya, jadi entri yang diubah, dihapus, atau rantai yang ditulis ulang ketahuan saat Verifikasi integritas;
setiap verifikasi bersih menyimpan titik acuan (salin ke luar database sebagai bukti tambahan). Halamannya: <AuditPanel /> dari @/lir-kit/access/audit-panel
(starter: pages/access/audit.tsx), dijaga audit_ability (null = ability).
- Jadwalkan pemeriksaan harian:
Schedule::command('lir-kit:audit-verify')->dailyAt('03:00');(gagal bila rantai rusak; kejadian juga masukLog::critical). - Aksi dari aplikasi Anda sendiri: panggil
app(\Lir\Kit\Services\AuditTrail::class)->log('nama_aksi', $user, $before, $after, 'objek', $id). Nilai berkuncipassword/token/secretdisamarkan otomatis. - Bila Anda mengikat
LoginHookssendiri,audit()milik Anda tetap yang dipakai; teruskan keAuditTrailbila ingin tabel ini.
6c. Pakai Pengaturan Situs
Nama, deskripsi, email kontak, logo, dan favicon: <SiteSettingsCard /> dari @/lir-kit/site-settings-card (starter: pages/settings/site.tsx). Bagikan hasilnya ke semua halaman:
'site' => fn () => \Lir\Kit\LirKit::site(), // name (nama aplikasi bila belum diisi), tagline, contact_email, logo, favicon (URL atau null)
Starter memakainya di sidebar dan favicon (layouts/app-layout.tsx). Berkas disimpan di disk lir-kit.disk (null = disk bawaan) dan disajikan lewat rute kit, jadi disk privat pun aman.
Foto profil adalah urusan aplikasi: halaman Profil starter memakai ImagePicker dan memanggil POST|DELETE /profile/avatar (simpan berkasnya, bagikan URL-nya sebagai auth.user.avatar).
6d. Pakai License
Halaman License (<LicensePanel /> dari @/lir-kit/license-panel; starter: pages/settings/license.tsx) mengaktifkan aplikasi dengan license key ke portal license,
atau dengan berkas .lic offline. Berkas diperiksa tanda tangan Ed25519-nya dengan kunci publik produk Anda, terikat ke domain, dan disimpan di storage/app/private/lir-license.
Semuanya mati secara bawaan; nyalakan lewat .env:
LIR_LICENSE_SERVER_URL=https://license.perusahaan.id # portal: POST /api/licenses/activate dan /validate
LIR_LICENSE_PUBLIC_KEY=... # kunci publik Ed25519 (base64), bukan rahasia
LIR_LICENSE_ENFORCE=true # tanpa ini license hanya ditampilkan, tidak membatasi apa pun
Dengan enforce: tanpa license yang berlaku (belum aktif, habis lewat masa tenggang, dicabut) aplikasi baca-saja untuk rute yang memakai middleware lir.license-writable
(tambahkan ke grup rute Anda; rute License kit dan lir.otp.* selalu terbuka, tambah lainnya di license.exempt_routes), batas user aktif dari license berlaku di layar Pengguna,
dan app(LicenseState::class)->allows('MODUL.fitur') memeriksa modul. Bagikan 'license' => fn () => \Lir\Kit\LirKit::license() agar starter menampilkan strip peringatan.
Jadwalkan Schedule::command('lir-kit:license-check --jitter=300')->daily();. Butuh ekstensi PHP sodium.
7. Sesuaikan tampilan ke aplikasi Anda: adapters.ts
resources/js/lir-kit/adapters.ts adalah satu-satunya file kit yang sebaiknya Anda ubah: isi t() dengan sistem terjemahan Anda,
notify() dengan toast Anda, dan KIT_API bila awalan rute berbeda. Terjemahan Inggris kit ada di resources/js/lang.en.json (gabungkan ke kamus Anda).
Cara update (penting)
Kit memakai semver dan CHANGELOG.md mencatat tiap rilis. Alurnya:
composer update susantokun/lir-kit # backend + migrasi baru ikut otomatis
php artisan migrate # selalu jalankan setelah update
php artisan vendor:publish --tag=lir-kit-js --force # hanya bila CHANGELOG menyebut perubahan komponen React
git diff resources/js/lir-kit # tinjau; kembalikan perubahan lokal Anda ke adapters.ts bila tertimpa
php artisan test && pnpm run build
Aturan supaya update mulus:
- Backend tidak perlu disalin; ia hidup di
vendor/dan diperbarui lewat Composer. Perilaku diubah lewatconfig/lir-kit.phpdanLoginHooks, bukan dengan mengedit paket. - Frontend disalin (karena memakai komponen UI dan gaya milik aplikasi Anda). Jangan edit file kit selain
adapters.ts; bila perlu mengubah, bungkus komponennya di file Anda sendiri. Dengan begitu--forceaman. - Migrasi tidak pernah diubah; perubahan skema datang sebagai file migrasi baru, jadi
migratecukup. - Versi mayor (2.0) boleh memecah kompatibilitas; baca bagian "Upgrade" di CHANGELOG.
- Kunci pengaturan yang tersimpan di tabel
lir_settings(login_method,mail,login_code_email) dijaga kompatibel; kunci baru selalu punya default.
Rilis (untuk pemilik paket)
# ubah CHANGELOG.md, lalu
git tag v0.1.1 && git push --tags
Pengembangan paket: playground
Kit punya aplikasi Laravel mini sendiri (playground, di folder workbench/) untuk melihat dan mencoba perubahan tanpa membuka proyek lain.
Isinya starter apa adanya: halaman masuk (kata sandi dan kode OTP, kode tampil di layar), lupa dan atur ulang kata sandi (tautan tampil di halaman saat lokal),
tantangan 2FA (kode demo 123456), verifikasi email, kerangka aplikasi dengan sidebar, pencarian, dan tema, lalu halaman pengaturan dan editor menu.
Yang tampil adalah source asli: komponen di resources/js dan halaman starter di stubs/starter (alias @/lir-kit, @/config, @/layouts), jadi ubahan langsung terlihat (hot reload)
dan hasilnya persis seperti yang diterima proyek lewat vendor:publish. Rute playground meniru URL Fortify (workbench/routes/web.php) karena playground tidak memakai Fortify.
Pertama kali:
composer install
pnpm install
composer build # buat database SQLite, migrasi, dan isi akun demo
Tiap kali bekerja, cukup satu terminal:
composer run dev # backend (http://127.0.0.1:8000) dan Vite (hot reload React) sekaligus
Atau jalankan terpisah di dua terminal: composer serve dan pnpm dev.
Masuk dengan demo@lir-kit.test (kata sandi password), atau pilih mode "kode email" di Pengaturan lalu pakai kode yang tampil di halaman.
Akun nonaktif@lir-kit.test dipakai untuk mencoba akun yang tidak boleh masuk. Isi workbench/ tidak ikut terpasang ke proyek lain (.gitattributes).
Memeriksa dan menguji:
vendor/bin/pest # tes backend (Orchestra Testbench)
pnpm types:check # tsc untuk komponen React dan playground
Alur merilis: ubah dan coba di playground, perbarui CHANGELOG.md, commit, git tag vX.Y.Z, git push --tags.
Packagist memperbaruinya sendiri; proyek yang memakai kit tinggal composer update susantokun/lir-kit.
Related Packages
Passwordless email magic-link & OTP authentication for Laravel — standalone, or...
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v0.1.0 | ^8.3 | ^12.0| | MIT |