php email
v1.0.5
Menyediakan cara berorientasi objek untuk mengirim dan mengantri email.
Ada kebutuhan untuk mengirim email di hampir semua proyek, misalnya untuk fungsi registrasi pengguna atau pengaturan ulang kata sandi. Kebanyakan email yang dikirim sangat mudah. Fitur canggih seperti enkripsi PGP dll tidak diperlukan. Pustaka ini menawarkan cara untuk membuat email seperti itu tanpa menyiapkan PHPMailer (perpustakaan yang mendasarinya), mengirim banyak email, dan bahkan menunda pengiriman email dengan menggunakan antrian yang didukung oleh database - dan semuanya dalam satu cara berorientasi objek.
Fitur-fiturnya adalah:
EmailQueue .Proyek ini dilisensikan di bawah GNU LGPL 3.0.
composer install technicalguru/email
Anda dapat mengunduh paket kode sumber dari Halaman Rilis GitHub
Kelas pusat untuk konfigurasi adalah EmailConfig . Ini menyimpan semua informasi yang diperlukan. Mari kita mulai dengan kerangka dasar:
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
Baris di atas membuat konfigurasi dan memerintahkannya untuk menggunakan zona waktu Europe/Berlin ketika perlu membuat stempel waktu. Hal ini diperlukan terutama ketika email dimasukkan dalam antrean dan stempel waktu perlu dicatat. Nilai ini opsional dan defaultnya adalah UTC .
Selanjutnya, alamat pengirim default dikonfigurasi. Pengirim default akan digunakan ketika email tertentu yang akan dikirim tidak menentukan alamat pengirim. Membuat alamat email dijelaskan lebih lanjut di bawah.
Awalan subjek digunakan pada setiap email yang akan dikirim nanti. Subjek akan diawali dengan string ini. Standarnya adalah NULL dan tidak akan mengubah subjek.
Alamat debug diperlukan hanya ketika Anda perlu mengirim email percobaan.
Kami masih perlu mengetahui di mana server SMTP kami berada. Jadi, inilah cara Anda menetapkan nilai-nilai ini:
use TgEmailConfigSmtpConfig;
$host = 'smtp.example.com;
$port = 587;
$auth = TRUE;
$username = 'mySmtpUser';
$password = 'mySmtpPassword';
$secureOption = 'starttls';
$smtpConfig = new SmtpConfig($host, $port, $auth, $username, $password, $secureOption);
$config->setSmtpConfig($smtpConfig);
Sebagian besar pilihan dapat menjelaskan dirinya sendiri. $auth memberi tahu PHPMailer yang mendasari apakah akan mengautentikasi dengan kredensial pengguna yang diberikan. $secureOption ditentukan oleh PHPMailer dan harus memiliki nilai smtps atau starttls . Lihat dokumentasi PHPMailer untuk informasi lebih lanjut.
Semua properti dapat diatur dengan menggunakan setter:
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
Kredensial autentikasi juga dapat diatur dengan menggunakan antarmuka TgUtilsAuthCredentialsProvider dari paket technicalguru/utils :
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
Sekarang saatnya membuat objek MailQueue pusat kita:
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
Anda siap mengirim email pertama Anda.
Ada cara cepat dan mudah untuk memeriksa apakah pengaturan Anda berfungsi dengan benar:
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
Kami telah menyiapkan persyaratan minimum untuk mengirim email:
use TgEmailEmail;
$email = new Email();
$email
->setSubject('Hello World')
->addTo('[email protected]', 'John Doe')
->addBcc('[email protected]')
->setReplyTo('[email protected]')
->setBody(Email::TEXT, 'The text e-mail body')
->setBody(Email::HTML, '<p>The HTML e-mail body</p>');
// Will return FALSE when sending fails
$rc = $mailer->send($email);
Itu saja. Cuplikan kode di atas adalah semua yang Anda perlukan dalam kode aplikasi Anda untuk mengirim email. Konfigurasi dan penyiapan harus terkubur di suatu tempat di penyiapan infrastruktur Anda.
Melampirkan file atau menyematkan gambar itu sederhana. Anda harus memiliki file yang tersedia dan dapat dibaca di sistem file:
use TgEmailAttachment;
$myFile = new Attachment(Attachment::ATTACHED, 'file.pdf', NULL, '/local/path/to/file.pdf', 'application/pdf');
$myImage = new Attachment(Attachment::EMBEDDED, 'img.png', 'img1', '/local/path/to/img.png', 'image/png');
$email
->addAttachment($myFile)
->addAttachment($myImage);
Perhatikan parameter ketiga dari gambar yang disematkan. Ini mendefinisikan ID unik dalam email HTML Anda yang dapat Anda referensikan
// Using the embedded image
$myHTML = '<img src="cid:img1">';
MailQueue akan membiarkan semua lampiran Anda tidak tersentuh di sistem file Anda. Namun, terkadang Anda mungkin ingin membuang file tersebut setelah Anda mengirim email. Konstruktor mengambil dua argumen tambahan:
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
Boolean pertama akan memicu file terhapus setelah email berhasil terkirim. Boolean kedua memberitahukan apakah file dapat dihapus ketika pengiriman gagal. Dengan menggunakan parameter ini Anda tidak perlu lagi mengurus file-file sementara. Terutama dalam hal antrian dan pengiriman tertunda.
MailQueue mendukung apa yang disebut Mode Mail. Mereka memberi tahu objek pengirim surat bagaimana memperlakukan email secara umum. Hal ini akan terasa nyaman saat Anda menguji pengaturan, saat Anda berada di lingkungan yang memiliki alamat email asli (seperti lingkungan Uji Penerimaan Pengguna) atau saat pengiriman email sebenarnya tidak masuk akal.
Mode berikut tersedia:
EmailQueue::DEFAULT - Ini adalah operasi normal. Semua email dikirim sebagaimana ditentukan.EmailQueue::BLOCK - Ini akan mencegah email apa pun dikirim atau diantrekan. Kode pengembalian selalu BENAR.EmailQueue::REROUTE - Semua email akan dikirim ke alamat lain, biasanya alamat admin atau pengembang dan penerima email yang ditentukan akan diabaikan.EmailQueue::BCC - Email akan dikirim ke penerima yang dituju tetapi alamat tambahan ditetapkan di BCC.Memblokir semua email yang akan dikirim atau diantrekan cukup mudah:
$mailer->setMailMode(EmailQueue::BLOCK);
Metode yang sama dapat digunakan pada objek EmailConfig pusat.
Anda memerlukan konfigurasi RerouteConfig untuk disetel di konfigurasi utama. Anda dapat mengatur ini terlebih dahulu saat membuat objek konfigurasi, atau semuanya saat mengatur mode email:
use TgEmailConfigRerouteConfig;
// Create the config
$subjectPrefix = '[Rerouted]';
$recipients = array('[email protected]');
$rerouteConfig = new RerouteConfig($subjectPrefix, $recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::REROUTE, $rerouteConfig);
Anda memerlukan konfigurasi BccConfig untuk disetel di konfigurasi utama. Anda dapat mengatur ini terlebih dahulu saat membuat objek konfigurasi, atau semuanya saat mengatur mode email:
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
Salah satu kelemahan mengirimkan email langsung dari kode aplikasi adalah memakan waktu. Pengguna Anda harus menunggu hingga pengiriman selesai sebelum dia dapat melihat respons apa pun dari aplikasi Anda. Mengantri email adalah solusinya karena pengirimannya ditunda (lebih disukai daripada tugas cron) dan pengguna menerima respons aplikasinya dengan cepat.
Anda memerlukan objek TgDatabaseDatabase untuk mengantri email. Jika tidak, EmailQueue akan memberikan pengecualian saat Anda mencoba mengantri email. Silakan merujuk ke dokumentasi TgDatabaseDatabase tentang cara membuat objek Database . Siapkan EmailsDAO dan EmailQueue yang sesuai sebagai berikut:
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
Mailer akan secara otomatis membuat tabel antrian jika tidak ada.
Setelah EmailsDAO tersedia, Anda dapat dengan mudah mengantri email:
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
Anda dapat memproses antrian di panggilan lain atau selama cronjob:
$mailer->processQueue($maxSeconds);
Argumen $maxSeconds akan memastikan bahwa pemrosesan berhenti ketika batas waktu telah tercapai. Argumennya opsional dan defaultnya adalah 60 detik.
Ada beberapa cara untuk membuat alamat email. Semua komponen surat menggunakan objek EmailAddress . Anda dapat menggunakan objek ini sebagai argumen di mana pun alamat email diharapkan. Ada beberapa cara untuk membuat objek seperti itu.
// From a string
$address = EmailAddress::from('[email protected]');
$address = EmailAddress::from('<[email protected]>');
$address = EmailAddress::from('John Doe <[email protected]>');
// From email string and name
$address = EmailAddress::from('[email protected]', 'John Doe');
// From another object
$obj = new stdClass;
$obj->name = 'John Doe';
$obj->email = '[email protected]';
$address = EmailAddress::from($obj);
// From another EmailAddress
$address = EmailAddress::from($anotherEmailAddressObject);
Ini berarti Anda dapat menggunakan ragam berikut saat membuat email:
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
Objek konfigurasi yang diperkenalkan di atas juga dapat dibuat menggunakan string, objek, atau array asosiatif JSON. Cuplikan berikut menjelaskan objek JSON dalam notasi singkat.
SmtpConfig:
-----------
{
"host": "www.example.com",
"port": 587,
"debugLevel": 0,
"auth": true,
"secureOption": "starttls",
"charset": "utf8",
"credentials": {
"user": "username",
"pass": "password"
}
},
RerouteConfig:
--------------
{
"recipients": "[email protected]",
"subjectPrefix": "[Rerouted]"
},
BccConfig:
----------
{
"recipients": "[email protected]"
},
EmailConfig:
------------
{
"timezone": "Europe/Berlin",
"mailMode": "default",
"smtpConfig": {... see above ...},
"rerouteConfig": {... see above ...},
"bccConfig": {... see above ...},
"debugAddress": "[email protected]",
"defaultSender": "[email protected]",
"subjectPrefix": "[PHPUnitTest] "
}
Masing-masing kelas konfigurasi menyediakan metode statis from() yang menggunakan tipe ini sebagai argumen dan mengembalikan objek konfigurasi itu sendiri:
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
Dimungkinkan untuk meneruskan array objek Email ke fungsi send() dan queue() . Namun, khusus untuk mengirim email dengan segera, Anda harus menyadari bahwa ini mungkin memerlukan waktu. Strategi yang lebih baik adalah dengan mengantri surat massal.
Sebagian besar pengujian PHPUnit tidak akan dijalankan jika tidak ada server SMTP atau database yang tersedia. Pengujian unit akan memeriksa variabel lingkungan EMAIL_TEST_SMTP dan EMAIL_DATABASE . Ada skrip bash yang tersedia, set-test-env.sh yang membuat variabel tersebut untuk Anda. Salin ke misalnya set-local-test-env.sh dan ikuti instruksi dalam file.
Laporkan bug, minta peningkatan, atau tarik permintaan di GitHub Issue Tracker.
