adems / dapur-email
Modul email untuk Dapur AdeMS: mengirim email lewat SMTP, dengan template laminas-view
Requires
- php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
- composer-runtime-api: ^2.0
- mezzio/mezzio-template: ^3.0
- psr/container: ^1.1 || ^2.0
- symfony/mailer: ^7.4
Requires (Dev)
- phpunit/phpunit: ^11.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Modul email untuk Dapur AdeMS: mengirim email lewat server SMTP, dengan isi email yang disusun dari template seperti halaman biasa.
Paket ini tidak membuat halaman sendiri. Modul lain, misalnya adems/dapur-user untuk undangan dan lupa kata sandi, memakai layanan dari paket ini untuk mengirim email.
Pengiriman memakai symfony/mailer, pustaka pengirim email yang banyak dipakai di dunia PHP. Laminas juga punya laminas-mail, tetapi paket itu kini hanya menerima perbaikan keamanan, jadi untuk proyek baru dipilih symfony/mailer. Komponen Laminas dan Symfony bisa dipakai bersama tanpa masalah, karena keduanya mengikuti standar PHP yang sama.
Kebutuhan
- Dapur AdeMS 2.4 atau lebih baru
- Akun email untuk mengirim, misalnya
noreply@contoh.comdi hosting Anda, beserta alamat server SMTP-nya
Pemasangan
Paket ini biasanya ikut terpasang sebagai kebutuhan modul lain. Untuk memasangnya sendiri, tulis di
composer.local.json, lalu jalankan composer update:
{
"require": {
"adems/dapur-email": "^1.0"
}
}
Bila tidak ada modul lain yang memuatnya, cantumkan AdeMS\Dapur\Email\ConfigProvider di config/modul.local.php.
Pengaturan
Buat config/autoload/email.local.php di folder inti. Akhiran .local.php membuat file ini tidak masuk Git,
dan memang harus begitu, karena isinya memuat kata sandi email:
<?php return [ 'email' => [ // smtp: kirim sungguhan | file: tulis ke folder (untuk uji) | mati: tidak mengirim apa pun 'cara' => 'smtp', 'smtp' => [ 'host' => 'mail.contoh.com', 'port' => 587, 'user' => 'noreply@contoh.com', 'sandi' => 'kata-sandi-akun-email', 'enkripsi' => 'tls', // tls (port 587) | ssl (port 465) | tidak ], 'pengirim' => [ 'alamat' => 'noreply@contoh.com', 'nama' => 'Dapur AdeMS', ], ], ];
Batasi izin file ini seperti database.local.php: hanya pemilik dan grup web server yang boleh membacanya,
misalnya chmod 640 dengan grup web server. Ingat juga bahwa cache konfigurasi (data/cache/) ikut memuat kata
sandi ini, jadi izin folder cache harus tetap tertutup.
Tanpa pengaturan, cara bernilai mati: tidak ada email yang dikirim, dan modul yang memakai email memakai cara
lain bila ada (misalnya kata sandi sementara untuk user baru).
Memilih server SMTP
Kirim lewat server email yang memang berhak mengirim untuk domain Anda, biasanya server email hosting tempat kotak
surat itu dibuat. Banyak domain memasang aturan SPF, DKIM, dan DMARC: email yang dikirim dari server lain (misalnya
langsung dari server web atau NAS di rumah) akan ditolak atau masuk spam. Alamat host dan port biasanya tertera
di panel hosting, pada bagian pengaturan aplikasi email.
Cara file untuk uji
Dengan 'cara' => 'file', email tidak dikirim, tetapi ditulis sebagai berkas .eml ke data/email/ (bisa diubah
dengan 'folder' => '...'). Berkas .eml bisa dibuka di Thunderbird atau Outlook untuk melihat tampilannya. Cara
ini cocok di komputer sendiri; di server, folder itu harus bisa ditulis web server.
Per website
Dengan adems/dapur-multiwebsite, setiap website bisa memakai
pengirim atau server SMTP sendiri lewat config/autoload/email.local.php miliknya.
Perintah
vendor/bin/dapur-email info # menampilkan pengaturan email, tanpa kata sandi vendor/bin/dapur-email uji <alamat> # mengirim email uji ke alamat itu
Setelah mengubah pengaturan, hapus cache konfigurasi lebih dulu (php dapur clear-config-cache), lalu jalankan
uji untuk memastikan email benar-benar sampai. Dengan paket multi-website, tambahkan --website=<domain>.
Memakai email di modul lain
Ambil dua layanan dari container:
AdeMS\Dapur\Email\SuratTemplatmenyusun email dari template.AdeMS\Dapur\Email\PengirimEmailmengirimnya sesuai pengaturan.
$pesan = $container->get(SuratTemplat::class)->buat( 'toko::pesanan-baru', // template isi HTML ['nomor' => 'P-0012'], // data untuk template 'budi@contoh.com', // penerima 'Pesanan baru P-0012', // subjek 'Budi', // nama penerima (opsional) ); $pengirim = $container->get(PengirimEmail::class); if ($pengirim->aktif()) { $pengirim->kirim($pesan); // melempar GagalKirim bila gagal }
Setiap email butuh dua template:
toko::pesanan-baruuntuk isi HTML. Template ini otomatis dibungkus layoutemail::layout, berisi kepala "Dapur AdeMS" dan catatan kaki.toko::pesanan-baru-teksuntuk isi teks biasa, tanpa layout.
Email dengan dua versi isi lebih nyaman dibaca di semua aplikasi email dan lebih jarang dianggap spam. Di template
HTML, tulis gaya langsung di elemen (style="..."), karena banyak aplikasi email mengabaikan CSS terpisah.
Layout dan template paket ini bisa ditimpa seperti template lain:
'templates' => ['paths' => ['email' => [__DIR__ . '/../../templates/email']]],
Kenapa modul lain tidak memakai symfony/mailer langsung
Modul lain hanya mengenal kelas milik paket ini: PengirimEmail, Pesan, SuratTemplat, dan GagalKirim, ditambah
pengaturan 'email'. Hanya tiga berkas di paket ini yang menyentuh symfony/mailer: PengirimSmtp,
PengirimFile, dan SuratSymfony.
Pola ini disebut adapter atau dependency inversion: kode bergantung pada antarmuka buatan sendiri, bukan pada
pustaka pihak ketiga. Container Laminas membantu di sini, karena modul cukup meminta PengirimEmail::class, lalu
PabrikLayanan yang menentukan isinya sesuai pengaturan. Akibatnya:
- bila suatu saat ada pustaka yang lebih baik (atau layanan seperti Amazon SES), cukup tiga berkas itu yang ditulis ulang; modul lain, template, dan pengaturan di server tidak berubah;
- cara kirim baru, misalnya
'cara' => 'ses', bisa ditambahkan tanpa menyentuh modul lain; - di uji,
PengirimEmailbisa diganti tiruan yang hanya menyimpan email.
Karena itu, modul yang memakai paket ini sebaiknya tidak membuat objek symfony/mailer (misalnya
Symfony\Component\Mime\Email) sendiri.
Uji
composer install
composer test
Lisensi
BSD-3-Clause. Lihat LICENSE.md.