Notifikasi Laravel: Menghubungkan Peristiwa Domain ke Satu Channel

Ketika status invoice berubah menjadi lunas, aplikasi biasanya perlu memberi tahu orang yang terkait. Di Laravel, kebutuhan itu tidak harus dimulai dari mail provider atau komponen toast di frontend. Mulailah dari pertanyaan yang lebih sempit: peristiwa domain apa yang terjadi, siapa penerimanya, lalu melalui channel apa pemberitahuan itu disimpan atau dikirim?

Artikel ini memakai contoh invoice yang sudah dibayar dan memilih database notification sebagai channel utama. Hasilnya dapat dibaca oleh antarmuka aplikasi pada kesempatan berikutnya. Ini berbeda dari UI toast yang hanya mengatur tampilan di sisi browser. Contoh mengikuti dokumentasi Laravel 13.x dan belum dijalankan pada project nyata.

Bentuk alur notifikasi Laravel

Untuk satu pemberitahuan, pisahkan empat bagian berikut:

1. Peristiwa domain: invoice berubah menjadi paid.
2. Penerima: model yang mewakili orang atau entitas yang harus mengetahui perubahan itu.
3. Notification class: kelas yang menyimpan isi dan aturan channel.
4. Channel: tujuan penyampaian, misalnya database atau mail.

Laravel merepresentasikan setiap notifikasi sebagai sebuah kelas. Kelas tersebut biasanya dibuat di app/Notifications dengan perintah Artisan berikut:

php artisan make:notification InvoicePaid

Perintah dan contoh di artikel ini adalah ilustrasi berbasis dokumentasi, bukan hasil eksekusi. Nama InvoicePaid juga merupakan contoh domain; sesuaikan dengan model dan peristiwa aplikasi Anda.

Siapa yang disebut notifiable?

Penerima tidak selalu harus model User. Laravel menyediakan trait Notifiable yang dapat dipakai pada model penerima. Pada aplikasi baru, model App\Models\User biasanya sudah memakainya, tetapi dokumentasi Laravel juga menjelaskan bahwa trait tersebut dapat digunakan pada model lain.

Contoh minimal model penerima:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;
}

Dengan trait itu, model memperoleh method notify. Pemanggilannya menerima sebuah instance Notification:

use App\Notifications\InvoicePaid;

$user->notify(new InvoicePaid($invoice));

Dalam contoh ini, $user adalah penerima yang sudah dipilih oleh alur aplikasi dan $invoice adalah data domain yang dibutuhkan untuk membentuk isi notifikasi. Pemilihan penerima bukan tanggung jawab otomatis Notification class. Aplikasi tetap perlu memastikan bahwa penerima memang terkait dengan invoice tersebut dan boleh menerima informasi itu. Artikel ini tidak mengajarkan authorization atau policy untuk keputusan tersebut.

Memilih satu channel dengan via

Setiap Notification class memiliki method via. Method inilah yang mengembalikan daftar channel untuk notifikasi tersebut. Laravel mendokumentasikan channel seperti mail, database, broadcast, vonage, dan slack; ketersediaan channel atau provider tidak berarti pengiriman di aplikasi tertentu sudah dikonfigurasi atau berhasil.

Untuk menjaga alur tetap sederhana, kita memilih database sebagai satu-satunya channel:

<?php

namespace App\Notifications;

use App\Models\Invoice;
use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification
{
    use Queueable;

    public function __construct(
        public Invoice $invoice,
    ) {
    }

    /**
     * Documentation-guided illustration; not executed in this article.
     */
    public function via(object $notifiable): array
    {
        return ['database'];
    }

    /**
     * Documentation-guided illustration; not executed in this article.
     */
    public function toDatabase(object $notifiable): array
    {
        return [
            'invoice_id' => $this->invoice->id,
            'status' => 'paid',
            'message' => 'Invoice telah dibayar.',
        ];
    }
}

via menentukan channel yang dipakai oleh notification. Ia bukan pemeriksaan hak akses dan bukan jaminan bahwa provider akan mengirimkan pesan. Pada contoh ini, toDatabase membentuk data yang akan disimpan oleh channel database. Data tersebut sengaja ringkas: identitas invoice, status, dan pesan yang dapat digunakan oleh antarmuka aplikasi.

Method toDatabase bukan tempat untuk menyalin seluruh objek invoice tanpa pertimbangan. Pilih data yang memang dibutuhkan oleh tampilan atau alur pembacaan notifikasi. Kebutuhan tersebut tetap bergantung pada struktur aplikasi Anda.

Mengirim notifikasi dari peristiwa domain

Setelah invoice dinyatakan lunas oleh alur bisnis yang relevan, aplikasi dapat memberitahu penerima:

use App\Notifications\InvoicePaid;

// Documentation-guided illustration; not executed.
$recipient->notify(new InvoicePaid($invoice));

Urutannya lebih penting daripada banyaknya kode: status domain sudah ditentukan, penerima sudah dipilih, Notification class membawa data yang diperlukan, lalu via memilih channel. Jika $recipient menggunakan Notifiable dan channel database dikonfigurasi sesuai kebutuhan project, Laravel dapat menyimpan representasi notifikasi untuk diakses melalui aplikasi.

Contoh ini tidak menyatakan bahwa invoice benar-benar telah lunas, bahwa penerima sudah diotorisasi, atau bahwa record berhasil disimpan. Semua itu memerlukan project, database, aturan domain, dan pengujian yang sesuai.

Apa arti channel database?

Channel database menyimpan informasi notifikasi di tabel database agar dapat ditampilkan pada antarmuka aplikasi. Laravel mendokumentasikan bahwa data tersebut mencakup tipe notifikasi dan struktur JSON yang menjelaskan isinya. Untuk memakainya, aplikasi perlu menyiapkan tabel notifications sesuai dokumentasi versi yang digunakan.

Secara konseptual, alurnya seperti ini:

• InvoicePaid menentukan ['database'] melalui via;
• toDatabase menyiapkan payload ringkas;
• Laravel menyimpan notifikasi untuk notifiable yang dituju;
• antarmuka aplikasi membaca notifikasi tersebut dan menentukan cara menampilkannya.

Langkah terakhir bukan otomatis menjadi UI toast. Toast, badge, daftar notifikasi, dan penandaan sebagai sudah dibaca adalah keputusan antarmuka aplikasi. Artikel ini hanya membahas batas Laravel Notification dan channel database, bukan implementasi komponen frontend.

Jika channel berubah, yang berubah apa?

Jika kebutuhan berubah dari penyimpanan internal menjadi email, Notification class dapat memakai channel mail dan method pembentuk pesan yang sesuai. Namun memilih mail hanya memilih permukaan channel Laravel; konfigurasi mailer, transport, provider, deliverability, dan hasil inbox berada di luar cakupan artikel ini.

Hal yang sama berlaku untuk channel lain. broadcast bukan sekadar database notification yang otomatis muncul di browser, dan slack atau SMS memerlukan konfigurasi serta pertimbangan provider tersendiri. Jangan memasukkan semua channel ke via hanya karena tersedia. Pilih channel berdasarkan cara penerima perlu menerima informasi tersebut.

Aturan praktisnya:

• pilih database bila aplikasi perlu menyimpan pemberitahuan untuk dibaca melalui antarmukanya;
• pilih mail bila kebutuhan memang pesan email dan konfigurasi mail sudah menjadi bagian project;
• gunakan channel lain hanya setelah kebutuhan, konfigurasi, dan batas operasionalnya jelas.

Ini adalah rekomendasi editorial, bukan persyaratan resmi Laravel atau jaminan hasil pengiriman.

Queue sebagai batas opsional

Laravel juga mendokumentasikan queued notifications. Notification class dapat mengimplementasikan ShouldQueue dan memakai trait Queueable; Laravel kemudian membuat pekerjaan untuk kombinasi penerima dan channel. Fitur ini relevan ketika pengiriman sebuah channel memerlukan pekerjaan lanjutan, tetapi queue worker, retry, failure handling, dan operasi infrastrukturnya adalah topik terpisah.

Karena itu, jangan menyimpulkan bahwa menambahkan ShouldQueue berarti notifikasi sudah terkirim atau pasti lebih andal. Konfigurasi queue dan worker harus diverifikasi pada project yang sebenarnya. Artikel ini tidak mengajarkan lifecycle queue.

Checklist sebelum memilih channel

Sebelum menulis Notification class, jawab pertanyaan berikut:

• Peristiwa domain apa yang ingin diberitahukan?
• Siapa notifiable yang tepat untuk peristiwa tersebut?
• Apakah penerima memang boleh menerima informasi itu menurut aturan aplikasi?
• Apakah notifikasi perlu disimpan untuk dibaca di dalam aplikasi, atau perlu channel lain?
• Data minimum apa yang diperlukan oleh channel dan antarmuka?
• Apakah channel membutuhkan konfigurasi provider atau queue yang belum diverifikasi?
• Apakah contoh sudah diuji pada versi Laravel dan project yang digunakan?

Jika kebutuhan utamanya adalah daftar pemberitahuan di dalam aplikasi, mulai dari satu penerima dan channel database. Pastikan batas antara fakta domain, pemilihan penerima, payload notification, dan tampilan UI tetap terlihat. Setelah alur lokal itu jelas, barulah pertimbangkan channel lain dengan bukti konfigurasi yang sesuai.