Класс Email
Надежный Email класс CodeIgniter, поддерживает следующие функции:
- Несколько протколов: Mail, Sendmail и SMTP
- TLS и SSL шифрование для SMTP
- Несколько получателей
- CC и BCC
- HTML или Plaintext письма
- Вложения
- Перенос слов
- Приоритеты
- Пакетный режим BCC,обеспечивающий разбитие больших списков контактов на небольшие BCC пакеты
- Средства отладки Email
Использование Email библиотеки
Отправка Email
Отправлять электронную почту не только просто, но и можно настроить отправку на лету или задать настройки в конфигурационном файле.
Вот основной пример, демонстрирующий как можно отправить письмо. Примечание: в этом примере предполагается, что вы отправляете сообщение из одного из ваших контроллеров.
$this->load->library('email');
$this->email->from('your@example.com', 'Your Name');
$this->email->to('someone@example.com');
$this->email->cc('another@another-example.com');
$this->email->bcc('them@their-example.com');
$this->email->subject('Email Test');
$this->email->message('Testing the email class.');
$this->email->send();
Параметры настройки Email
Существует 21 предпочтение, предоставляемое для тонкой настройки отправляемых сообщений. Вы можете либо установить их вручную, как описано здесь, либо же автоматически через настройки хранящиеся в файле конфигурации, описанные ниже:
Предпочтения устанавливаются путем передачи массива значений приоритета на инициализацию метода электронной почты. Вот пример, как можно установить некоторые настройки:
$config['protocol'] = 'sendmail';
$config['mailpath'] = '/usr/sbin/sendmail';
$config['charset'] = 'iso-8859-1';
$config['wordwrap'] = TRUE;
$this->email->initialize($config);
Примечание
Большая часть настроек имеют значения по умолчанию, которые будут использоваться, если вы не установите их.
Параметры настройки Email в файле конфигурации
Если вы предпочитаете не устанавливать параметры с помощью описанного выше метода, вы можете вместо этого записать их в конфигурационный файл. Просто создайте новый файл с названием email.php и добавьте массив $config в файл. Затем сохраните файл в config/email.php и он будет использоваться автоматически. Вам НЕ нужно будет использовать $this->email->initialize() метод, если сохраните настройки в конфигурационный файл.
Email предпочтения
Ниже приведен список всех настроtr, которые можно установить при отправке Email.
Предпочтение | Значение по умолчанию | Варианты | Описание |
---|---|---|---|
useragent | CodeIgniter | Нет | “Пользовательский агент”. |
Протокол | mail, sendmail или smtp | Протокол отправки почты. | |
mailpath | /usr/sbin/sendmail | Нет | Путь сервера к Sendmail. |
smtp_host | Нет умолчаний | Нет | SMTP адрес сервера. |
smtp_user | Нет умолчаний | Нет | SMTP имя пользователя. |
smtp_pass | Нет умолчаний | Нет | SMTP пароль. |
smtp_port | 25 | Нет | SMTP порт. |
smtp_timeout | 5 | Нет | SMTP таймаут (в секундах). |
smtp_keepalive | FALSE | TRUE или FALSE (булево) | Включить постоянное SMTP соединение. |
smtp_crypto | Нет умолчаний | tls или ssl | SMTP шифрование |
wordwrap | TRUE | TRUE или FALSE (булево) | Включить перенос слов. |
wrapchars | 76 | Количество символов для переноса слова. | |
mailtype | text | text или html | Тип почты. Если вы отправляете HTML письмо, то вы должны отправить его как полноценную веб-страницу. Убедитесь, что вы не имеете каких-либо относительных ссылок или относительных путей к изображениям иначе они работать не будут. |
charset | $config['charset'] | Набор символов (utf-8, iso-8859-1 и т.д.). | |
validate | FALSE | TRUE или FALSE (булево) | Нужно ли проверять адрес электронной почты. |
priority | 3 | 1, 2, 3, 4, 5 | Приоритет Email. 1 = высший. 5 = низший. 3 = средний. |
crlf | \n | “\r\n” or “\n” or “\r” | Символ новой строки. (Используйте “\r\n” для соблюдения RFC 822). |
newline | \n | “\r\n” or “\n” or “\r” | Символ новой строки. (Используйте “\r\n” для соблюдения RFC 822). |
bcc_batch_mode | FALSE | TRUE или FALSE (булево) | Включить BCC пакетный режим. |
bcc_batch_size | 200 | Нет | Количество сообщений в каждом BCC пакете. |
dsn | FALSE | TRUE или FALSE (булево) | Включить сообщение от сервера. |
Переопределение переноса слов
Если включен перенос слов (рекомендуется соблюдение RFC 822) и имеется очень длинная ссылк в вашем письме, она может стать некликабельна для конечного пользователя из-за переноса слов. CodeIgniter позволяет переопределить вручную перенос слов в пределах сообщения следующим образом:
Текст вашего письма
с нормальным переносом слов.
{unwrap}http://example.com/а_вот_ссылка_которую_не_следует_переносиить_по_словам.html{/unwrap}
Еще текст вашего письма
с нормальным переносом слов.
Поместите фрагмент, который Вы не хотите переносить на новую строку между: {unwrap} {/unwrap}
Настройки класса
- class CI_Email
- from($from[, $name = ''[, $return_path = NULL]])
Параметры: - $from (строка) – “Адрес” от кого e-mail
- $name (строка) – “Имя”отправителя
- $return_path (строка) – Необязательный адрес электронной почты для перенаправления недопоставленной электронной почты
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Установить адрес электронной почты и имя лица, отправившего письмо:
$this->email->from('you@example.com', 'Your Name');
Вы можете также установить обратный путь, чтобы помочь перенаправить недоставленные письма:
$this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');
Примечание
Возвращаемый путь не может быть использован, если установлен ‘SMTP’ протокол.
- reply_to($replyto[, $name = ''])
Параметры: - $replyto (строка) – E-mail адрес для ответов
- $name (строка) – Отображаемое имя в reply-to e-mail адреса
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает адрес для ответов. Если информация не предоставлена информация используется из метода. Пример:
$this->email->reply_to('you@example.com', 'Your Name');
- to($to)
Параметры: - $to (смешанный) – Строка с разделителем в виде запятой или массив адресов электронной почты
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает адрес электронной почты получателя. Может быть одиночной электронной почтой, списком указанным через запятую или массивом:
$this->email->to('someone@example.com');
$this->email->to('one@example.com, two@example.com, three@example.com');
$this->email->to( array('one@example.com', 'two@example.com', 'three@example.com') );
- cc($cc)
Параметры: - $cc (смешанный) – Строка с разделителем в виде запятой или массив адресов электронной почты
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает email адрес(а) CC. Так же как и “to”, может быть одиночной электронной почтой, списком указанным через запятую или массивом.
- bcc($bcc[, $limit = ''])
Параметры: - $bcc (смешанный) – Строка с разделителем в виде запятой или массив адресов электронной почты
- $limit (число) – Максимальное количество сообщений электронной почты, для отправки в пакете
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает email адрес(а) BCC. Так же как и методto(), может быть одиночной электронной почтой, списком указанным через запятую или массивом.
Если $limit установлен, то будет активирован “пакетный режим”, который будет отправлять письма пачками, с размером каждой партии, не превышающей указанного $limit.
- subject($subject)
Параметры: - $subject (строка) – Строка темы сообщения электронной почты
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает тему сообщения электронной почты:
$this->email->subject('This is my subject');
- message($body)
Параметры: - $body (строка) – Текст сообщения электронной почты
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает текст сообщения электронной почты:
$this->email->message('This is my message');
- set_alt_message($str)
Параметры: - $str (строка) – Альтернативный текст сообщения электронной почты
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Устанавливает альтернативный текст сообщения электронной почты:
$this->email->set_alt_message('This is the alternative message');
Это дополнительная строка текстового сообщения, которая может быть использована, при отправке электронной почты отформатированной в HTML. Она позволяет указать альтернативный текст сообщения без HTML форматирования, который добавляется к заголовку строки для людей, которые не принимают электронную почту в HTML. Если не установите свой собственный текст сообщения CodeIgniter будет извлекать сообщения из HTML формата электронной почты обрезая теги.
- set_header($header, $value)
Параметры: - $header (строка) – Имя заголовка
- $value (строка) – Значение заголовка
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Добавляет дополнительные заголовки к электронной почте:
$this->email->set_header('Header1', 'Value1'); $this->email->set_header('Header2', 'Value2');
- clear([$clear_attachments = FALSE])
Параметры: - $clear_attachments (булево) – Следует ли очищать вложения
Возвращает: CI_Email экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Инициализирует все переменные email класса в пустое значение. Этот метод предназначается для использования при запуске отправки почты в цикле, позволяя сбросить значения данных между циклами.
foreach ($list as $name => $address) { $this->email->clear(); $this->email->to($address); $this->email->from('your@example.com'); $this->email->subject('Here is your info '.$name); $this->email->message('Hi '.$name.' Here is the info you requested.'); $this->email->send(); }
Если установите папаметр в TRUE любые вложения будут очищены:
$this->email->clear(TRUE);
- send([$auto_clear = TRUE])
Параметры: - $auto_clear (булево) – Whether to clear message data automatically
Возвращает: TRUE при успехе или FALSE при неудаче
Возвращаемый тип: Булево
Метод отправки электронной почты. Возвращает булево TRUE или FALSE основываясь на успехе или неудаче, что позволяет ему быть использованным условно:
if ( ! $this->email->send()) { // Генерирует ошибку }
Этот метод будет автоматически очищать все параметры при успешном запросе. Чтобы остановить такое поведение, установите FALSE:
if ($this->email->send(FALSE)) { // Параметры не будут очищены }
Примечание
Для того, чтобы использовать print_debugger() метод, необходимо избегать параметра очистки электронной почты.
- attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])
Параметры: - $filename (строка) – Имя файла
- $disposition (строка) – ‘расположение’ вложения. Большинство почтовых клиентов делают свои собственные решения независимо от спецификации MIME, используемого здесь. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml
- $newname (строка) – Пользовательское имя файла для использования в электронной почте
- $mime (строка) – MIME тип (полезно для буферизованных данных)
Возвращает: CI_Email instance экземпляр (метод цепочки)
Возвращаемый тип: CI_Email
Позволяет отправлять вложения. Установите путь к файлу папка/имя в первом параметре. Для нескольких вложений используйте этот метод несколько раз. Пример:
$this->email->attach('/path/to/photo1.jpg'); $this->email->attach('/path/to/photo2.jpg'); $this->email->attach('/path/to/photo3.jpg');
Чтобы использовать по умолчанию расположение (вложений), оставьте второй параметр пустым, в противном случае будет использовано пользовательское расположение:
$this->email->attach('image.jpg', 'inline');
Можно также использовать URL:
$this->email->attach('http://example.com/filename.pdf');
Если вы хотите использовать собственное имя файла, то можете использовать третий параметр:
$this->email->attach('filename.pdf', 'attachment', 'report.pdf');
Если нужно использовать буфер строку вместо реальных - физических - файлов, то можете использовать первый параметр в качестве буфера, третий параметр как имя файла и четвертый параметр в виде MIME типа:
$this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');
- attachment_cid($filename)
Параметры: - $filename (строка) – Существует ли указанное вложение
Возвращает: ID содержимого вложения или false, если не найдено
Возвращаемый тип: Строка
Устанавливает и возвращает ID содержимого вложения, что позволяет встроить свое изображение вложения в формат HTML. Первый параметр должен быть уже прикрепленным файлом.
$filename = '/img/photo1.jpg'; $this->email->attach($filename); foreach ($list as $address) { $this->email->to($address); $cid = $this->email->attachment_cid($filename); $this->email->message(''); $this->email->send(); }
Примечание
ID содержимого для каждого адреса электронной почты должен быть создан заново, чтобы он был уникальным.
- print_debugger([$include = array('headers', 'subject', 'body')])
Параметры: - $include (массив) – Указать части сообщения для отображения
Возвращает: Отформатированные данные отладки
Возвращаемый тип: Строка
Возвращает строку, содержащую любые сообщения сервера, заголовки сообщений и написанное сообщение. Полезно при отладке.
При необходимости можно указать, какие части сообщения должны быть напечатаны. Допустимые варианты: headers, subject, body.
Пример:
// Вам нужно передать FALSE при отправке данных // чтобы не были очищены - если что случится, print_debugger() // ничего не выведет. $this->email->send(FALSE); // Будет отображать только заголовки сообщений, за исключением темы сообщения и Body $this->email->print_debugger(array('headers'));
Примечание
По умолчанию все исходные данные будут отображены.