Класс Email

Надежный класс Email из CodeIgniter поддерживает следующие функции:

• Несколько протоколов: Mail, Sendmail и SMTP
• Шифрование TLS и SSL для SMTP
• Несколько получателей
• CC и BCC
• Электронное письмо в формате HTML или Plaintext
• Вложения
• Обёртывание слов
• Приоритеты
• Режим BCC Batch Mode, позволяющий разбивать большие списки электронной почты на небольшие партии BCC.
• Инструменты отладки электронной почты

• Использование библиотеки Email
  • Отправка электронного письма
  • Настройка параметров электронной почты
  • SSL и TLS для протокола SMTP
  • Параметры электронной почты
  • Переопределение обёртывания слов
• Справочник по классу

Использование библиотеки Email

Отправка электронного письма

Отправка электронного письма проста; вы можете настроить её на лету или задать свои предпочтения в файле app/Config/Email.php.

Вот базовый пример демонстрации отправки электронного письма:

$email = \Config\Services::email();

$email->setFrom('your@example.com', 'Your Name');
$email->setTo('someone@example.com');
$email->setCC('another@another-example.com');
$email->setBCC('them@their-example.com');

$email->setSubject('Email Test');
$email->setMessage('Testing the email class.');

$email->send();

Настройка параметров электронной почты

Доступно 21 параметр, позволяющий настроить отправку ваших электронных сообщений. Вы можете настроить их вручную, как описано здесь, или автоматически через параметры, сохранённые в вашем файле конфигурации, описанные ниже:

Параметры устанавливаются путём передачи массива значений параметров в метод инициализации email. Вот пример того, как вы можете настроить некоторые параметры:

$config['protocol'] = 'sendmail';
$config['mailPath'] = '/usr/sbin/sendmail';
$config['charset']  = 'iso-8859-1';
$config['wordWrap'] = true;

$email->initialize($config);

Настройка параметров электронной почты в файле конфигурации

Если вы предпочитаете не устанавливать параметры с помощью указанного выше метода, вы можете поместить их в файл конфигурации. Просто откройте файл app/Config/Email.php и установите свои конфигурации в свойства Email. Затем сохраните файл, и он будет использоваться автоматически. Вам НЕ нужно использовать метод $email->initialize() , если вы настроили свои параметры в файле конфигурации.

Просмотр параметров

Настройки, использованные при последней успешной отправке, доступны из свойства экземпляра $archive. Это полезно для тестирования и отладки, чтобы определить фактические значения на момент вызова send().

SSL и TLS для протокола SMTP

Для защиты имени пользователя, пароля и содержимого электронного письма при общении с сервером SMTP следует использовать шифрование канала. Широко используются два разных стандарта, и важно понимать различия при попытке устранения неполадок при отправке электронных писем.

Большинство серверов SMTP позволяют подключения на портах 465 или 587 при отправке электронных писем. (Оригинальный порт 25 редко используется, так как многие провайдеры имеют правила блокировки, а общение происходит в текстовом формате).

Ключевое различие заключается в том, что порт 465 ожидает, что канал связи будет защищён с помощью TLS с самого начала согласно RFC 8314. Подключение к порту 587 позволяет подключение в текстовом формате, а затем обновит канал, используя шифрование с помощью команды STARTTLS SMTP.

Обновление соединения на порту 465 может быть или не быть поддерживаемым сервером, поэтому команда STARTTLS SMTP может завершиться ошибкой, если сервер не поддерживает её. Если вы установили порт на 465, вам следует оставить параметр SMTPCrypto пустым, так как связь защищена с помощью TLS с самого начала, а параметр STARTTLS не нужен.

Если ваша конфигурация требует подключения к порту 587, вы, скорее всего, должны установить SMTPCrypto на tls, так как это реализует команду STARTTLS при общении с сервером SMTP, чтобы переключиться с текстового формата на зашифрованный канал. Первичное общение будет происходить в текстовом формате, а канал будет обновлён до TLS с помощью команды STARTTLS.

Параметры электронной почты

Ниже приведен список всех параметров, которые можно задать при отправке электронного письма.

Переопределение обёртывания слов

Если обёртывание слов включено (рекомендуется для соответствия RFC 822), а у вас очень длинная ссылка в электронном письме, она может быть обёрнута, что сделает её не нажимаемой для получателя. CodeIgniter позволяет вручную переопределить обёртывание слов в части вашего сообщения следующим образом:

The text of your email that
gets wrapped normally.

{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}

More text that will be
wrapped normally.

Поместите элемент, который вы не хотите обёртывать, между: {unwrap} {/unwrap}

Справочник по классу

CodeIgniter\Email\Email

setFrom($from[, $name = ''[, $returnPath = null]])

Параметры:	$from (string) – Адрес электронной почты «От» $name (string) – Имя отправителя в поле «От» $returnPath (string) – Дополнительный адрес электронной почты для перенаправления не доставленных писем
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает адрес электронной почты и имя отправителя письма:

$email->setFrom('you@example.com', 'Your Name');

Вы также можете установить Return-Path, чтобы помочь перенаправить не доставленное письмо:

$email->setFrom('you@example.com', 'Your Name', 'returned_emails@example.com');

Примечание

Return-Path нельзя использовать, если вы настроили протокол ‘smtp’.

setReplyTo($replyto[, $name = ''])

Параметры:	$replyto (string) – Адрес электронной почты для ответов $name (string) – Имя для адреса электронной почты reply-to
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает адрес ответа. Если информация не предоставлена, используется информация из метода setFrom. Пример:

$email->setReplyTo('you@example.com', 'Your Name');

setTo($to)

Параметры:	$to (mixed) – Строка, разделенная запятыми, или массив адресов электронной почты
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает адрес(ы) электронной почты получателя(ей). Может быть один адрес, список, разделенный запятыми, или массив:

$email->setTo('someone@example.com');

$email->setTo('one@example.com, two@example.com, three@example.com');

$email->setTo(['one@example.com', 'two@example.com', 'three@example.com']);

setCC($cc)

Параметры:	$cc (mixed) – Строка, разделенная запятыми, или массив адресов электронной почты
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает адрес(ы) электронной почты CC. Также, как и для «to», может быть один адрес, список, разделенный запятыми, или массив.

setBCC($bcc[, $limit = ''])

Параметры:	$bcc (mixed) – Строка, разделенная запятыми, или массив адресов электронной почты $limit (int) – Максимальное количество электронных писем для отправки в группе
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает адрес(ы) электронной почты BCC. Также, как и в методе setTo(), может быть один адрес, список, разделенный запятыми, или массив.

Если $limit установлен, режим «пакетов» будет включен, который отправит письма группами, каждая группа не будет превышать указанного $limit.

setSubject($subject)

Параметры:	$subject (string) – Тема письма
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает тему письма:

$email->setSubject('This is my subject');

setMessage($body)

Параметры:	$body (string) – Тело письма
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает тело письма:

$email->setMessage('This is my message');

setAltMessage($str)

Параметры:	$str (string) – Тело альтернативного письма
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Устанавливает тело альтернативного письма:

$email->setAltMessage('This is the alternative message');

Это необязательная строка сообщения, которую можно использовать при отправке писем в формате HTML. Она позволяет указать альтернативное сообщение без форматирования HTML, которое добавляется в заголовок для пользователей, не принимающих HTML-письма. Если вы не установите собственное сообщение, CodeIgniter извлечет сообщение из вашего HTML-письма и удалит теги.

setHeader($header, $value)

Параметры:	$header (string) – Имя заголовка $value (string) – Значение заголовка
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Добавляет дополнительные заголовки к письму:

$email->setHeader('Header1', 'Value1');
$email->setHeader('Header2', 'Value2');

clear($clearAttachments = false)

Параметры:	$clearAttachments (bool) – Удалять ли вложения
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепочка методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Инициализирует все переменные письма в пустое состояние. Этот метод предназначен для использования, если вы выполняете метод отправки письма в цикле, разрешая сброс данных между циклами.

foreach ($list as $name => $address)
{
    $email->clear();

    $email->setTo($address);
    $email->setFrom('your@example.com');
    $email->setSubject('Here is your info '.$name);
    $email->setMessage('Hi ' . $name . ' Here is the info you requested.');
    $email->send();
}

Если вы установите параметр в true, вложения также будут удалены:

$email->clear(true);

send($autoClear = true)

Параметры:	$autoClear (bool) – Автоматически очищать данные сообщения
Возвращает:	true при успехе, false при неудаче
Тип возвращаемого значения:	bool

Метод отправки письма. Возвращает true или false в зависимости от успеха или неудачи, что позволяет использовать его условно:

if (! $email->send())
{
    // Generate error
}

Этот метод автоматически очистит все параметры, если запрос был успешным. Чтобы остановить это поведение, передайте false:

if ($email->send(false))
{
    // Parameters won't be cleared
}

Примечание

Для использования метода printDebugger(), необходимо избегать очистки параметров письма.

Примечание

Если BCCBatchMode включен, а получателей более BCCBatchSize, этот метод всегда вернет булево значение true.

attach($filename[, $disposition = ''[, $newname = null[, $mime = '']]])

Параметры:	$filename (string) – Имя файла $disposition (string) – «расположение» вложения. Большинство почтовых клиентов принимают собственное решение независимо от используемого здесь MIME-спецификации. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml $newname (string) – Пользовательское имя файла для использования в электронном письме $mime (string) – Тип MIME для использования (полезно для буферизованных данных)
Возвращает:	Экземпляр CodeIgniter\Email\Email (цепление методов)
Тип возвращаемого значения:	CodeIgniter\Email\Email

Позволяет отправлять вложение. В первом параметре укажите путь/имя файла. Для нескольких вложений используйте метод несколько раз. Например:

$email->attach('/path/to/photo1.jpg');
$email->attach('/path/to/photo2.jpg');
$email->attach('/path/to/photo3.jpg');

Чтобы использовать значение по умолчанию для расположения (вложение), оставьте второй параметр пустым, в противном случае используйте пользовательское расположение:

$email->attach('image.jpg', 'inline');

Вы также можете использовать URL:

$email->attach('http://example.com/filename.pdf');

Если вы хотите использовать пользовательское имя файла, вы можете использовать третий параметр:

$email->attach('filename.pdf', 'attachment', 'report.pdf');

Если вам нужно использовать строку буфера вместо реального - физического - файла, вы можете использовать первый параметр в качестве буфера, третий параметр в качестве имени файла и четвертый параметр в качестве типа MIME:

$email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');

setAttachmentCID($filename)

Параметры:	$filename (string) – Существующее имя файла вложения
Возвращает:	Идентификатор содержимого вложения или false, если не найден
Тип возвращаемого значения:	string

Устанавливает и возвращает Content-ID вложения, что позволяет встраивать встраиваемое (изображение) вложение в HTML. Первый параметр должен быть именем уже прикрепленного файла.

$filename = '/img/photo1.jpg';
$email->attach($filename);

foreach ($list as $address) {
    $email->setTo($address);
    $cid = $email->setAttachmentCID($filename);
    $email->setMessage('<img src="cid:'. $cid .'" alt="photo1" />');
    $email->send();
}

Примечание

Идентификатор содержимого для каждого электронного письма должен быть повторно создан, чтобы он был уникальным.

printDebugger($include = ['headers', 'subject', 'body'])

Параметры:	$include (array) – Какие части сообщения распечатать
Возвращает:	Отформатированные данные отладки
Тип возвращаемого значения:	string

Возвращает строку, содержащую любые сообщения сервера, заголовки электронной почты и сообщение электронной почты. Полезно для отладки.

Вы можете указать, какие части сообщения должны быть напечатаны. Допустимые параметры: headers, subject, body.

Пример:

// You need to pass false while sending in order for the email data
// to not be cleared - if that happens, printDebugger() would have
// nothing to output.
$email->send(false);

// Will only print the email headers, excluding the message subject and body
$email->printDebugger(['headers']);

Примечание

По умолчанию будут напечатаны все исходные данные.