php email
v1.0.5
提供物件導向的方式來發送和排隊電子郵件。
幾乎所有項目都需要發送電子郵件，例如用於用戶註冊或密碼重設功能。大多數電子郵件發送都非常簡單。不需要 PGP 加密等複雜功能。該庫提供了一種無需設置 PHPMailer（底層庫）即可創建此類電子郵件的方法，可以發送多封電子郵件，甚至可以通過使用數據庫支持的隊列來推遲發送電子郵件 - 所有這些都在一個面向對象的方式。
特點是：
EmailQueue物件中。該專案已獲得 GNU LGPL 3.0 許可。
composer install technicalguru/email
您可以從GitHub Release Page下載源碼包
配置的中心類別是EmailConfig 。它包含所有必要的資訊。讓我們從基本框架開始：
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
上面的行創建配置並告訴它在需要創建時間戳時使用Europe/Berlin時區。這主要是在電子郵件排隊並且需要記錄時間戳時需要的。該值是可選的，預設為UTC 。
接下來，設定預設寄件者地址。當要傳送的特定電子郵件未定義寄件者地址時，將使用預設寄件者。下面進一步解釋建立電子郵件地址。
主題前綴用於稍後發送的每封電子郵件。主題將以此字串作為前綴。預設為NULL ，不會修改主題。
僅當您需要發送測試郵件時才需要調試地址。
我們仍然需要知道 SMTP 伺服器所在的位置。這就是設定這些值的方法：
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);
大多數選項都是不言自明的。 $auth告訴底層 PHPMailer 是否使用給定的使用者憑證進行身份驗證。 $secureOption由PHPMailer定義，應具有值smtps或starttls 。請參閱 PHPMailer 文件以取得更多資訊。
所有屬性都可以使用 setter 來設定：
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
也可以使用technicalguru/utils套件中的TgUtilsAuthCredentialsProvider介面來設定身份驗證憑證：
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
現在是時候創建我們的中央MailQueue物件了：
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
您已準備好發送您的第一封電子郵件。
有一種快速簡便的方法可以檢查您的設定是否正常運作：
$email = $mailer->createTestMail();
$rc = $mailer->send($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);
就是這樣。上面的程式碼片段是您在應用程式程式碼中發送電子郵件所需的全部程式碼。配置和設定應隱藏在基礎設施設定中的某個位置。
附加文件或嵌入圖像很簡單。您需要使該文件在檔案系統上可用且可讀：
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);
注意嵌入影像的第三個參數。它在您的 HTML 電子郵件中定義了一個唯一的 ID，您可以透過以下方式引用
// Using the embedded image
$myHTML = '<img src="cid:img1">';
MailQueue將使您的檔案系統上的所有附件保持不變。但是，有時您可能希望在發送電子郵件後刪除該檔案。建構函式需要兩個附加參數：
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
第一個布林值將在電子郵件發送成功後觸發文件被刪除。第二個布林值告訴發送失敗時是否可以刪除檔案。使用這些參數，您無需再關心臨時檔案。尤其是在排隊和延遲發送方面。
MailQueue支援所謂的郵件模式。它們告訴郵件發送者物件一般如何處理電子郵件。當您測試設定、處於具有真實電子郵件地址的環境（例如使用者驗收測試環境）或實際發送電子郵件沒有多大意義時，這會很方便。
這些模式可用：
EmailQueue::DEFAULT - 這是正常操作。所有電子郵件均按定義發送。EmailQueue::BLOCK - 這將阻止任何郵件發送或排隊。回傳碼始終為 TRUE。EmailQueue::REROUTE - 所有電子郵件都會傳送到另一個地址，通常是管理員或開發人員地址，並且定義的電子郵件收件者將被忽略。EmailQueue::BCC - 電子郵件將發送給其預期收件人，但在 BCC 上設定其他地址。阻止所有要發送或排隊的電子郵件非常簡單：
$mailer->setMailMode(EmailQueue::BLOCK);
可以在中央EmailConfig物件上使用相同的方法。
您需要在主配置中設定RerouteConfig配置。您可以在建立配置物件時預先設定它，或在設定郵件模式時一起設定：
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);
您需要在主配置中設定BccConfig配置。您可以在建立配置物件時預先設定它，或在設定郵件模式時一起設定：
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
直接從應用程式程式碼發送電子郵件的缺點之一是非常耗時。您的用戶需要等待發送完成，然後才能看到您的應用程式的任何回應。對電子郵件進行排隊是一種解決方案，因為發送會被推遲（優於 cron 作業），並且用戶可以快速收到她/他的應用程式回應。
您將需要一個TgDatabaseDatabase物件來對電子郵件進行排隊。否則，當您嘗試對電子郵件進行排隊時， EmailQueue將引發異常。有關如何建立Database的信息，請參閱TgDatabaseDatabase文件。設定對應的EmailsDAO和EmailQueue如下：
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
如果隊列表不存在，郵件程式將自動建立隊列表。
一旦EmailsDAO可用，您就可以輕鬆地對電子郵件進行排隊：
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
您可以在另一個呼叫中或在 cronjob 期間處理佇列：
$mailer->processQueue($maxSeconds);
參數$maxSeconds將確保在達到時間限制時停止處理。此參數是可選的，預設為 60 秒。
建立電子郵件地址的方法有多種。所有郵件元件都使用EmailAddress物件。無論何時需要電子郵件地址，您都可以使用此物件作為參數。存在多種創建此類物件的方法。
// 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);
這意味著您在建立電子郵件時可以使用這些風格：
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
上面介紹的配置物件也可以使用 JSON 字串、物件或關聯數組來建立。以下片段以簡短表示法描述了 JSON 物件。
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] "
}
每個配置類別都提供一個靜態from()方法，該方法將這些類型作為參數並傳回配置物件本身：
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
可以將Email物件陣列傳遞給send()和queue()函數。但是，特別是對於立即發送電子郵件，您應該意識到這可能需要一些時間。更好的策略是對群發郵件進行排隊。
當沒有可用的 SMTP 伺服器或資料庫時，大多數 PHPUnit 測試將不會執行。單元測試將檢查環境變數EMAIL_TEST_SMTP和EMAIL_DATABASE 。有一個可用的 bash 腳本set-test-env.sh可以為您建立這些變數。將其複製到例如set-local-test-env.sh並按照文件中的說明進行操作。
在 GitHub 問題追蹤器上報告錯誤、請求增強或拉取請求。
