php email
v1.0.5
Предоставляет объектно-ориентированный способ отправки электронных писем и постановки их в очередь.
Практически во всех проектах существует необходимость отправлять электронные письма, например, для регистрации пользователей или функций сброса пароля. Большинство отправленных электронных писем очень просты. Сложные функции, такие как шифрование PGP и т. д., не требуются. Эта библиотека предлагает способ создавать такие электронные письма без настройки PHPMailer (базовой библиотеки), отправлять несколько электронных писем и даже откладывать отправку электронной почты с помощью очереди, поддерживаемой базой данных - и все это в одном файле. объектно-ориентированный способ.
Особенности:
EmailQueue .Этот проект распространяется под лицензией GNU LGPL 3.0.
composer install technicalguru/email
Вы можете скачать пакеты исходного кода со страницы выпуска GitHub.
Центральным классом для настройки является 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.
Все свойства могут быть установлены с помощью установщика:
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
Учетные данные для аутентификации также можно установить с помощью интерфейса TgUtilsAuthCredentialsProvider из пакетаtechnicguru technicalguru/utils :
// 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, на который вы можете ссылаться по
// 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 выдаст исключения при попытке поставить электронную почту в очередь. Пожалуйста, обратитесь к документации TgDatabaseDatabase о том, как создать объект Database . Настройте соответствующие 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);
Вы можете обработать очередь во время другого вызова или во время задания cron:
$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);
В функции send() queue() можно передать массив объектов Email . Однако, особенно при немедленной отправке электронных писем, вы должны знать, что это может занять некоторое время. Лучшая стратегия — поставить в очередь массовые рассылки.
Большинство тестов PHPUnit не будут выполняться, если SMTP-сервер или база данных недоступны. Модульные тесты проверят переменные среды EMAIL_TEST_SMTP и EMAIL_DATABASE . Существует скрипт bash set-test-env.sh , который создает для вас эти переменные. Скопируйте его, например, в set-local-test-env.sh и следуйте инструкциям в файле.
Сообщите об ошибке, запросите улучшение или запрос на включение в GitHub Issue Tracker.
