Membangun Integrasi Antar-Modul Laravel dengan Event, Listener, Queue, dan API
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Menghubungkan modul Iuran, Kas, dan Notifikasi tanpa saling mengikat erat: kapan memakai pemanggilan langsung lewat kontrak, kapan memakai event dan listener, cara membuat listener ber-queue yang aman dari transaksi gagal dan eksekusi ganda, pola outbox untuk event yang tidak boleh hilang, serta kapan modul layak dipisah menjadi layanan yang berbicara lewat API.
Di artikel multi-module, aplikasi RW dipecah menjadi modul: Iuran, Kas, Notifikasi, Warga, dan Laporan. Pemecahan itu baru setengah jalan. Masalah sebenarnya muncul saat modul harus bekerja sama.
Contoh alur nyata ketika warga melunasi iuran:
Cara paling cepat adalah memanggil semuanya dari satu tempat:
// ❌ Modul Iuran tahu terlalu banyak
public function lunasi(Iuran $iuran, Pembayaran $pembayaran): void
{
$iuran->update(['status' => 'lunas']);
TransaksiKas::create([...]); // masuk ke tabel milik modul Kas
$iuran->keluarga->kepala->notify(new TandaTerima()); // tahu detail Notifikasi
Cache::forget('dasbor:ringkasan'); // tahu detail Laporan
}
Akibatnya:
Artikel ini membahas pilihan cara integrasi dan kapan memakai masing-masing.
Hasil akhir:
IuranDilunasi dengan listener di modul Kas, Notifikasi, dan Laporan,Event::fake() dan test kontrak.| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| MySQL | 8.4 |
| Redis | 7.x (queue) |
| Testing | Pest 4 |
Struktur modul mengikuti artikel multi-module:
app/Modules/
├── Iuran/
│ ├── Contracts/ # yang boleh dipakai modul lain
│ ├── Events/ # event yang diumumkan modul ini
│ ├── Models/
│ └── Services/
├── Kas/
│ ├── Contracts/
│ ├── Listeners/
│ └── ...
├── Notifikasi/
└── Laporan/
| Cara | Sifat | Kapan dipakai | Contoh |
|---|---|---|---|
| Pemanggilan langsung lewat kontrak | Sinkron; pemanggil butuh hasilnya sekarang | Membaca data atau validasi yang menentukan alur | Iuran menanyakan Warga: "apakah keluarga ini aktif?" |
| Event + listener sinkron | Sinkron, tetapi pengirim tidak tahu siapa pendengarnya | Reaksi yang harus satu transaksi dengan aksi utama | Jarang; lebih baik dihindari |
| Event + listener ber-queue | Asinkron; kegagalan pendengar tidak menggagalkan pengirim | Reaksi yang boleh terlambat beberapa detik | Kas mencatat pemasukan, Notifikasi mengirim tanda terima |
| Outbox + queue | Asinkron, terjamin tidak hilang | Event penting yang harus sampai, termasuk ke sistem luar | Pelunasan diteruskan ke sistem akuntansi kelurahan |
| API (HTTP) | Antar-proses, antar-aplikasi | Modul sudah dipisah menjadi layanan atau aplikasi lain | Aplikasi mobile pengurus, layanan laporan terpisah |
Aturan praktis:
Tentukan arah sebelum menulis kode:
Warga ← Iuran ← Kas
↑ ↑ ↑
└──── Notifikasi ──┘ (Notifikasi & Laporan mendengar event semua modul)
Laporan
Tegakkan aturan ini dengan test arsitektur Pest:
// tests/Arch/ModulTest.php
arch('modul Iuran tidak bergantung pada modul hilir')
->expect('App\Modules\Iuran')
->not->toUse(['App\Modules\Kas', 'App\Modules\Notifikasi', 'App\Modules\Laporan']);
arch('modul Kas hanya memakai kontrak dan event Iuran')
->expect('App\Modules\Kas')
->not->toUse(['App\Modules\Iuran\Models', 'App\Modules\Iuran\Services']);
arch('event modul Iuran bersifat immutable')
->expect('App\Modules\Iuran\Events')
->toBeFinal()
->toBeReadonly();
Modul Iuran perlu memastikan keluarga aktif sebelum membuat tagihan. Ia butuh jawaban sekarang, jadi gunakan kontrak milik modul Warga:
// app/Modules/Warga/Contracts/DirektoriKeluarga.php
namespace App\Modules\Warga\Contracts;
interface DirektoriKeluarga
{
public function aktif(int $keluargaId): bool;
/** @return array{id:int, nama_kepala:string, rt:string, wa_opt_in:bool}|null */
public function ringkasan(int $keluargaId): ?array;
}
// app/Modules/Warga/Services/DirektoriKeluargaEloquent.php
namespace App\Modules\Warga\Services;
use App\Modules\Warga\Contracts\DirektoriKeluarga;
use App\Modules\Warga\Models\Keluarga;
final class DirektoriKeluargaEloquent implements DirektoriKeluarga
{
public function aktif(int $keluargaId): bool
{
return Keluarga::whereKey($keluargaId)->where('status', 'aktif')->exists();
}
public function ringkasan(int $keluargaId): ?array
{
$k = Keluarga::with('kepala:id,keluarga_id,nama', 'rukunTetangga:id,nomor')->find($keluargaId);
return $k ? [
'id' => $k->id,
'nama_kepala' => $k->kepala?->nama ?? '-',
'rt' => $k->rukunTetangga->nomor,
'wa_opt_in' => (bool) $k->wa_opt_in,
] : null;
}
}
// app/Modules/Warga/WargaServiceProvider.php
public function register(): void
{
$this->app->bind(DirektoriKeluarga::class, DirektoriKeluargaEloquent::class);
}
Perhatikan bahwa kontrak mengembalikan data sederhana (bool, array, DTO), bukan model Eloquent. Bila mengembalikan model Keluarga, modul Iuran bisa memanggil $keluarga->update() dan aturan kepemilikan data pun runtuh.
Event mengumumkan fakta yang sudah terjadi, dinamai dalam bentuk lampau.
// app/Modules/Iuran/Events/IuranDilunasi.php
namespace App\Modules\Iuran\Events;
use Illuminate\Foundation\Events\Dispatchable;
final readonly class IuranDilunasi
{
use Dispatchable;
public function __construct(
public string $eventId, // UUID, untuk idempotensi listener
public int $iuranId,
public int $keluargaId,
public string $periode,
public int $nominal, // rupiah, integer
public string $metode, // tunai | transfer | midtrans
public ?int $pembayaranId,
public \DateTimeImmutable $dilunasiPada,
) {}
}
Prinsip event yang baik:
Iuran. Bila listener butuh nominal, nominal ada di event.readonly).eventId agar listener bisa mendeteksi pemrosesan ganda.Dispatch dari service modul Iuran, di dalam transaksi:
// app/Modules/Iuran/Services/LunasiIuran.php
namespace App\Modules\Iuran\Services;
use App\Modules\Iuran\Events\IuranDilunasi;
use App\Modules\Iuran\Models\Iuran;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;
final class LunasiIuran
{
public function handle(Iuran $iuran, string $metode, ?int $pembayaranId = null): Iuran
{
return DB::transaction(function () use ($iuran, $metode, $pembayaranId) {
$iuran = Iuran::whereKey($iuran->id)->lockForUpdate()->firstOrFail();
if ($iuran->status === 'lunas') {
return $iuran; // idempoten
}
$iuran->update(['status' => 'lunas', 'dilunasi_pada' => now()]);
IuranDilunasi::dispatch(
(string) Str::uuid(),
$iuran->id,
$iuran->keluarga_id,
$iuran->periode,
$iuran->nominal,
$metode,
$pembayaranId,
now()->toImmutable(),
);
return $iuran;
});
}
}
Modul Iuran selesai di sini. Ia tidak tahu siapa yang mendengar.
Listener di modul Kas:
// app/Modules/Kas/Listeners/CatatPemasukanIuran.php
namespace App\Modules\Kas\Listeners;
use App\Modules\Iuran\Events\IuranDilunasi;
use App\Modules\Kas\Models\TransaksiKas;
use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Database\UniqueConstraintViolationException;
final class CatatPemasukanIuran implements ShouldQueue, ShouldHandleEventsAfterCommit
{
public string $queue = 'default';
public int $tries = 5;
public array $backoff = [10, 60, 300];
public function handle(IuranDilunasi $event): void
{
try {
TransaksiKas::create([
'sumber' => 'iuran',
'sumber_id' => $event->iuranId,
'event_id' => $event->eventId, // unique index
'jenis' => 'masuk',
'nominal' => $event->nominal,
'keterangan' => "Iuran {$event->periode} keluarga #{$event->keluargaId} ({$event->metode})",
'tanggal' => $event->dilunasiPada,
]);
} catch (UniqueConstraintViolationException) {
// event yang sama sudah pernah dicatat: abaikan
}
}
public function failed(IuranDilunasi $event, \Throwable $e): void
{
logger()->critical('kas.gagal_catat_iuran', ['event_id' => $event->eventId, 'iuran_id' => $event->iuranId, 'error' => $e->getMessage()]);
}
}
// migration modul Kas
$table->uuid('event_id')->nullable()->unique();
$table->unique(['sumber', 'sumber_id']); // satu iuran hanya satu transaksi kas
Tiga hal yang membuat listener ini aman:
ShouldQueue: dikerjakan worker. Bila pencatatan kas gagal, pelunasan iuran tetap berhasil, dan listener dicoba ulang sesuai tries dan backoff.ShouldHandleEventsAfterCommit: listener baru masuk antrean setelah transaksi di LunasiIuran commit. Tanpa ini, worker bisa mencatat kas untuk pelunasan yang akhirnya di-rollback.Listener lain di modul berbeda:
// app/Modules/Notifikasi/Listeners/KirimTandaTerimaIuran.php
final class KirimTandaTerimaIuran implements ShouldQueue, ShouldHandleEventsAfterCommit
{
public string $queue = 'notifikasi';
public function __construct(private DirektoriKeluarga $direktori) {}
public function handle(IuranDilunasi $event): void
{
$keluarga = $this->direktori->ringkasan($event->keluargaId);
if (! $keluarga) {
return;
}
Notification::send(
User::where('keluarga_id', $event->keluargaId)->where('kepala_keluarga', true)->get(),
new TandaTerimaIuran($event->eventId, $event->periode, $event->nominal),
);
}
}
// app/Modules/Laporan/Listeners/SegarkanRingkasanDasbor.php
final class SegarkanRingkasanDasbor implements ShouldHandleEventsAfterCommit
{
public function handle(IuranDilunasi $event): void
{
Cache::tags(['dasbor'])->flush(); // ringan, tidak perlu queue
}
}
Cache::tags membutuhkan driver Redis atau memcached; bila memakai driver lain, hapus kunci secara eksplisit.
Laravel menemukan listener secara otomatis di app/Listeners. Karena listener berada di folder modul, daftarkan di service provider masing-masing modul agar setiap modul memiliki daftarnya sendiri:
// app/Modules/Kas/KasServiceProvider.php
use Illuminate\Support\Facades\Event;
public function boot(): void
{
Event::listen(IuranDilunasi::class, CatatPemasukanIuran::class);
Event::listen(IuranDibatalkan::class, BatalkanPemasukanIuran::class);
}
// app/Modules/Notifikasi/NotifikasiServiceProvider.php
public function boot(): void
{
Event::listen(IuranDilunasi::class, KirimTandaTerimaIuran::class);
}
Alternatifnya, aktifkan event discovery untuk folder modul di bootstrap/app.php:
->withEvents(discover: [
__DIR__.'/../app/Modules/*/Listeners',
])
Periksa hasilnya:
php artisan event:list --event=IuranDilunasi
Di production, php artisan optimize (atau event:cache) menyimpan hasil discovery agar tidak memindai folder di setiap request.
ShouldHandleEventsAfterCommit menyelesaikan satu sisi masalah: listener tidak berjalan untuk transaksi yang batal. Sisi lainnya tetap ada: transaksi sudah commit, lalu proses mati atau Redis tidak bisa dijangkau tepat sebelum job masuk antrean. Iuran sudah lunas, tetapi kas tidak pernah tercatat.
Untuk event yang benar-benar penting, simpan event di tabel dalam transaksi yang sama dengan perubahan data, lalu kirim dari tabel itu.
// migration
Schema::create('outbox', function (Blueprint $table) {
$table->id();
$table->uuid('event_id')->unique();
$table->string('jenis'); // nama kelas event
$table->json('payload');
$table->timestamp('dikirim_pada')->nullable()->index();
$table->unsignedSmallInteger('percobaan')->default(0);
$table->text('error_terakhir')->nullable();
$table->timestamps();
});
// app/Support/Outbox/Outbox.php
namespace App\Support\Outbox;
use Illuminate\Support\Facades\DB;
final class Outbox
{
public static function catat(object $event): void
{
DB::table('outbox')->insert([
'event_id' => $event->eventId,
'jenis' => $event::class,
'payload' => json_encode(get_object_vars($event), JSON_THROW_ON_ERROR),
'created_at' => now(),
'updated_at' => now(),
]);
}
}
Di LunasiIuran, ganti IuranDilunasi::dispatch(...) dengan:
Outbox::catat(new IuranDilunasi(/* ... */)); // dalam DB::transaction yang sama
Relay yang mengirim event dari outbox, dijalankan scheduler setiap menit:
// app/Console/Commands/KirimOutbox.php
public function handle(): int
{
DB::table('outbox')
->whereNull('dikirim_pada')
->where('percobaan', '<', 10)
->orderBy('id')
->limit(500)
->get()
->each(function ($baris) {
try {
$data = json_decode($baris->payload, true, flags: JSON_THROW_ON_ERROR);
$data['dilunasiPada'] = new \DateTimeImmutable($data['dilunasiPada']['date'] ?? $data['dilunasiPada']);
event(new ($baris->jenis)(...$data));
DB::table('outbox')->where('id', $baris->id)->update(['dikirim_pada' => now()]);
} catch (\Throwable $e) {
DB::table('outbox')->where('id', $baris->id)->update([
'percobaan' => $baris->percobaan + 1,
'error_terakhir' => mb_substr($e->getMessage(), 0, 1000),
]);
}
});
return self::SUCCESS;
}
// routes/console.php
Schedule::command('outbox:kirim')->everyMinute()->onOneServer()->withoutOverlapping(5);
Contoh di atas mengubah properti tanggal secara khusus untuk IuranDilunasi. Untuk banyak jenis event, beri setiap event metode statis fromArray() dan toArray() agar serialisasi tidak bergantung pada get_object_vars.
Outbox memberi jaminan setidaknya sekali: relay bisa mengirim event yang sama dua kali (misalnya proses mati setelah event() tetapi sebelum update). Itulah alasan listener tetap harus idempoten.
Gunakan outbox secukupnya. Untuk tanda terima WhatsApp, event biasa dengan queue sudah cukup. Untuk pencatatan keuangan dan integrasi ke sistem luar, outbox layak dipakai.
Bila modul Laporan dipindah ke aplikasi terpisah (misalnya karena berat dan dipakai beberapa RW), komunikasi tidak bisa lagi lewat event di memori. Dua pola:
1. Kontrak tetap, implementasi diganti dengan HTTP. Kode pemanggil tidak berubah.
// app/Modules/Laporan/Contracts/LayananLaporan.php
interface LayananLaporan
{
public function ringkasanKas(string $periode): array;
}
// app/Modules/Laporan/Services/LayananLaporanHttp.php
final class LayananLaporanHttp implements LayananLaporan
{
public function ringkasanKas(string $periode): array
{
return Http::baseUrl(config('services.laporan.url'))
->withToken(config('services.laporan.token'))
->acceptJson()
->timeout(5)
->retry(2, 200, throw: false)
->get('/api/v1/ringkasan-kas', ['periode' => $periode])
->throw()
->json('data');
}
}
2. Event diteruskan sebagai webhook. Relay outbox mengirim event ke layanan lain lewat HTTP dengan tanda tangan HMAC, dan layanan penerima memprosesnya seperti webhook (verifikasi tanda tangan, simpan, proses di queue, idempoten berdasarkan event_id).
// listener penerus di aplikasi utama
final class TeruskanKeLayananLaporan implements ShouldQueue, ShouldHandleEventsAfterCommit
{
public int $tries = 8;
public array $backoff = [10, 60, 300, 900];
public function handle(IuranDilunasi $event): void
{
$body = json_encode(['type' => 'iuran.dilunasi', 'id' => $event->eventId, 'data' => get_object_vars($event)]);
$ts = (string) time();
Http::withHeaders([
'X-Signature' => hash_hmac('sha256', "{$ts}.{$body}", config('services.laporan.webhook_secret')),
'X-Timestamp' => $ts,
])
->withBody($body, 'application/json')
->timeout(10)
->post(config('services.laporan.url').'/webhooks/rw-utama')
->throw();
}
}
Jangan terburu-buru memisahkan modul menjadi layanan. Panggilan jaringan menambah latensi, kegagalan parsial, dan pekerjaan operasional. Modul di dalam satu aplikasi dengan batas yang jelas (kontrak, event, test arsitektur) sudah menyelesaikan sebagian besar masalah keterikatan.
Satu pelunasan sekarang memicu beberapa job di antrean berbeda. Saat warga mengeluh "sudah bayar tapi tidak dapat tanda terima", Anda perlu menelusuri alurnya.
event_id di setiap log listener dan simpan di tabel turunan (transaksi_kas.event_id, pesan_whatsapp.event_id).Schedule::call(function () {
$macet = DB::table('outbox')->whereNull('dikirim_pada')->where('created_at', '<', now()->subMinutes(10))->count();
if ($macet > 0) {
Log::critical('outbox.macet', ['jumlah' => $macet]);
}
})->everyTenMinutes()->name('pantau-outbox')->onOneServer();
Pengirim: pastikan event diumumkan dengan data yang benar, tanpa menjalankan listener.
// tests/Feature/Iuran/LunasiIuranTest.php
use Illuminate\Support\Facades\Event;
it('mengumumkan IuranDilunasi saat iuran dilunasi', function () {
Event::fake([IuranDilunasi::class]);
$iuran = Iuran::factory()->create(['status' => 'belum_bayar', 'nominal' => 50_000]);
app(LunasiIuran::class)->handle($iuran, 'tunai');
Event::assertDispatched(IuranDilunasi::class, fn ($e) =>
$e->iuranId === $iuran->id && $e->nominal === 50_000 && $e->metode === 'tunai');
});
it('tidak mengumumkan event bila iuran sudah lunas', function () {
Event::fake([IuranDilunasi::class]);
$iuran = Iuran::factory()->create(['status' => 'lunas']);
app(LunasiIuran::class)->handle($iuran, 'tunai');
Event::assertNotDispatched(IuranDilunasi::class);
});
Wiring: pastikan listener terdaftar.
it('modul Kas dan Notifikasi mendengar IuranDilunasi', function () {
Event::fake();
Event::assertListening(IuranDilunasi::class, CatatPemasukanIuran::class);
Event::assertListening(IuranDilunasi::class, KirimTandaTerimaIuran::class);
});
Penerima: test listener secara langsung dengan event buatan, tanpa melibatkan modul Iuran.
// tests/Feature/Kas/CatatPemasukanIuranTest.php
function eventLunas(array $ubah = []): IuranDilunasi
{
return new IuranDilunasi(...array_merge([
'eventId' => (string) Str::uuid(),
'iuranId' => 10,
'keluargaId' => 3,
'periode' => '2026-10',
'nominal' => 50_000,
'metode' => 'transfer',
'pembayaranId' => null,
'dilunasiPada' => new DateTimeImmutable('2026-10-05 10:00'),
], $ubah));
}
it('mencatat pemasukan kas dari event', function () {
(new CatatPemasukanIuran)->handle(eventLunas());
expect(TransaksiKas::sole())
->jenis->toBe('masuk')
->nominal->toBe(50_000);
});
it('idempoten: event yang sama diproses dua kali tetap satu transaksi', function () {
$event = eventLunas();
(new CatatPemasukanIuran)->handle($event);
(new CatatPemasukanIuran)->handle($event);
expect(TransaksiKas::count())->toBe(1);
});
After commit: pastikan listener tidak berjalan bila transaksi batal.
it('tidak mengantrekan listener bila transaksi di-rollback', function () {
Queue::fake();
$iuran = Iuran::factory()->create(['status' => 'belum_bayar']);
try {
DB::transaction(function () use ($iuran) {
app(LunasiIuran::class)->handle($iuran, 'tunai');
throw new RuntimeException('batal');
});
} catch (RuntimeException) {}
Queue::assertNothingPushed();
});
Perhatikan bahwa test berbasis RefreshDatabase membungkus setiap test dalam transaksi. Laravel menangani ini sehingga callback after-commit tetap berjalan saat transaksi aplikasi (level paling luar di dalam test) commit, tetapi bila hasilnya tidak sesuai harapan, periksa apakah test memakai DatabaseTransactions atau koneksi yang berbeda.
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Listener dijalankan dua kali | Terdaftar manual sekaligus lewat discovery | Pilih satu cara; cek php artisan event:list |
| Listener tidak pernah dijalankan | Tidak terdaftar atau cache event lama | Daftarkan di provider modul; php artisan event:clear |
| Kas tercatat untuk pelunasan yang batal | Listener berjalan sebelum commit | ShouldHandleEventsAfterCommit |
| Iuran lunas, kas tidak tercatat | Job hilang setelah commit (Redis down, proses mati) | Pola outbox untuk event penting |
| Transaksi kas ganda | Listener tidak idempoten | Constraint unik event_id / (sumber, sumber_id) |
ModelNotFoundException di listener |
Event membawa model yang sudah dihapus | Event membawa data primitif, bukan model |
| Ketergantungan melingkar antar-modul | Modul hulu memanggil modul hilir | Arah ketergantungan satu arah; test arsitektur |
| Error deserialisasi di outbox relay | Struktur event berubah | Versi event; fromArray() yang toleran |
| Respons pelunasan lambat | Listener berat berjalan sinkron | ShouldQueue |
| Sulit menelusuri alur | Tidak ada korelasi antar-log | Sertakan event_id di semua log dan tabel turunan |
Keamanan
Performa
ShouldQueue, dengan antrean sesuai prioritas.dikirim_pada.Maintainability
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 |
| Redis | 7.x |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Laravel Scheduler: Otomatisasi Rekap Laporan, Pengingat Pembayaran, dan Pekerjaan Terjadwal
Berikutnya
Laravel Performance Optimization: 20 Pemeriksaan untuk Menemukan Bottleneck Aplikasi
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