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

Blog / REST API, Integrasi & Automation / Membangun Integrasi Antar-Modu...
REST API, Integrasi & Automation

Membangun Integrasi Antar-Modul Laravel dengan Event, Listener, Queue, dan API

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
16 min read
15 views

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.

Overview

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:

  1. Iuran: tandai tagihan lunas.
  2. Kas: catat pemasukan di buku kas.
  3. Notifikasi: kirim tanda terima lewat WhatsApp dan email.
  4. Laporan: buang cache ringkasan dasbor.

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:

  • modul Iuran bergantung pada semua modul lain, dan perubahan di Kas bisa merusak Iuran,
  • satu kegagalan (misalnya WhatsApp down) menggagalkan seluruh proses pelunasan,
  • respons lambat karena semua dikerjakan di request,
  • menambah reaksi baru (misalnya poin warga) berarti mengubah modul Iuran lagi.

Artikel ini membahas pilihan cara integrasi dan kapan memakai masing-masing.

Hasil akhir:

  • aturan arah ketergantungan antar-modul,
  • kontrak (interface) untuk pemanggilan sinkron yang memang dibutuhkan,
  • event domain IuranDilunasi dengan listener di modul Kas, Notifikasi, dan Laporan,
  • listener ber-queue yang berjalan setelah commit dan idempoten,
  • pola outbox untuk event yang tidak boleh hilang,
  • integrasi lewat API internal bila satu modul dipisah,
  • test dengan Event::fake() dan test kontrak.

Prerequisites

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/

Step-by-step Tutorial

Langkah 1: Pilih Cara Integrasi

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:

  • Butuh jawaban sekarang? Gunakan kontrak.
  • Memberi tahu bahwa sesuatu sudah terjadi? Gunakan event.
  • Event tidak boleh hilang walau Redis mati? Gunakan outbox.
  • Beda proses atau beda aplikasi? Gunakan API.

Langkah 2: Aturan Ketergantungan

Tentukan arah sebelum menulis kode:

Warga  ←  Iuran  ←  Kas
  ↑         ↑        ↑
  └──── Notifikasi ──┘        (Notifikasi & Laporan mendengar event semua modul)
          Laporan
  • Modul hanya boleh memakai Contracts dan Events modul lain, tidak boleh model, service, atau tabel internalnya.
  • Tidak boleh ada ketergantungan melingkar (Iuran → Kas → Iuran).
  • Modul "hulu" (Iuran) tidak tahu modul "hilir" (Kas, Notifikasi). Hilir mendengar event hulu.

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();

Langkah 3: Kontrak untuk Pemanggilan Sinkron

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.

Langkah 4: Event Domain

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:

  • Membawa data primitif yang cukup, bukan model. Listener di modul lain tidak perlu (dan tidak boleh) memuat model Iuran. Bila listener butuh nominal, nominal ada di event.
  • Immutable (readonly).
  • Punya eventId agar listener bisa mendeteksi pemrosesan ganda.
  • Bagian dari kontrak publik modul. Mengubah atau menghapus properti adalah perubahan yang merusak, sama seperti mengubah API.

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.

Langkah 5: Listener Ber-queue yang Aman

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:

  1. ShouldQueue: dikerjakan worker. Bila pencatatan kas gagal, pelunasan iuran tetap berhasil, dan listener dicoba ulang sesuai tries dan backoff.
  2. ShouldHandleEventsAfterCommit: listener baru masuk antrean setelah transaksi di LunasiIuran commit. Tanpa ini, worker bisa mencatat kas untuk pelunasan yang akhirnya di-rollback.
  3. Idempoten lewat constraint unik: queue bisa menjalankan listener lebih dari sekali; constraint di database menjamin hanya satu transaksi kas per iuran.

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.

Langkah 6: Mendaftarkan Listener per Modul

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.

Langkah 7: Pola Outbox untuk Event yang Tidak Boleh Hilang

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.

Langkah 8: Saat Modul Menjadi Layanan Terpisah (API)

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.

Langkah 9: Pemantauan Alur Antar-Modul

Satu pelunasan sekarang memicu beberapa job di antrean berbeda. Saat warga mengeluh "sudah bayar tapi tidak dapat tanda terima", Anda perlu menelusuri alurnya.

  • Sertakan event_id di setiap log listener dan simpan di tabel turunan (transaksi_kas.event_id, pesan_whatsapp.event_id).
  • Pantau tabel outbox: baris yang belum terkirim lebih dari 10 menit adalah tanda bahaya.
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();
  • Gunakan Horizon untuk melihat listener mana yang gagal dan di antrean mana.

Langkah 10: Test

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.

Troubleshooting

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

Best Practices

Keamanan

  • Event tidak membawa data sensitif yang tidak perlu (nomor rekening, token).
  • Panggilan API antar-layanan memakai token atau HMAC dan HTTPS.
  • Payload outbox mengikuti kebijakan masa simpan data yang sama dengan tabel lain; bersihkan baris yang sudah terkirim.
  • Penerima event dari luar memperlakukannya seperti webhook: verifikasi, simpan, proses, idempoten.

Performa

  • Listener berat selalu ShouldQueue, dengan antrean sesuai prioritas.
  • Event membawa data yang cukup sehingga listener tidak perlu banyak query tambahan.
  • Relay outbox memproses dalam batch kecil dan memakai indeks dikirim_pada.
  • Cache event discovery di production.

Maintainability

  • Aturan: kontrak untuk bertanya, event untuk memberi tahu, outbox untuk yang tidak boleh hilang, API untuk antar-aplikasi.
  • Event adalah kontrak publik modul: immutable, dinamai bentuk lampau, perubahan diperlakukan seperti versi API.
  • Test arsitektur menjaga batas modul.
  • Test pengirim, wiring, dan penerima secara terpisah.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4
Redis 7.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya