WSMailer

Быстрый старт

$mailer = new WSMailer([
    'smtp-host' => 'smtp.example.com',
    'smtp-login' => 'robot@example.com',
    'smtp-pass' => 'secret',
    'from-email' => 'robot@example.com',
    'from-name' => 'WebSource',
    'smtp-secure' => 'tls',
    'smtp-port' => 587
]);

$mailer->sendHtml(
    'user@example.com',
    'Добро пожаловать',
    '<h1>Здравствуйте!</h1><p>Ваш аккаунт создан.</p>'
);

Конфигурация

Конфигурация формируется из двух источников:

• настроек из базы данных options с типом email
• массива $config, переданного в __construct()

Переданные параметры объединяются с настройками из базы данных. Для предсказуемого переопределения используйте те же имена ключей, которые сохранены в настройках.

Параметры конфигурации

Если smtp-secure не задан, порт 465 автоматически включает ssl, а порт 587 включает tls. Для другого порта пустое значение оставляет соединение без шифрования.

Инициализация

__construct(array $config = [])

Создаёт экземпляр класса и подготавливает итоговую конфигурацию.

$mailer = new WSMailer();

$mailer = new WSMailer([
    'from-email' => 'robot@example.com',
    'from-name' => 'WebSource'
]);

Отправка писем

sendText(string $to, string $subject, string $text, array $attachments = []) : void

Отправляет текстовое письмо.

Параметры:

Пример:

$mailer->sendText(
    'user@example.com',
    'Проверка почты',
    'Это тестовое письмо.'
);

sendHtml(string $to, string $subject, string $html, array $attachments = [], ?string $text = null) : void

Отправляет HTML-письмо.

Параметры:

Пример:

$html = $mailer->mailHtmlTemplate(
    '<h1>Восстановление доступа</h1><p>Перейдите по ссылке для продолжения.</p>',
    'Если вы не запрашивали это письмо, просто проигнорируйте его.'
);

$mailer->sendHtml(
    'user@example.com',
    'Восстановление доступа',
    $html
);

Проверка соединения

ping() : void

Проверяет доступность SMTP-сервера.

Если SMTP не настроен, метод просто завершится без ошибки.

Пример:

$mailer->ping();

Получение состояния

getLastTransport() : string

Возвращает транспорт, через который было отправлено последнее письмо.

Возможные значения:

• smtp
• mail

Пример:

$mailer->sendText('user@example.com', 'Test', 'Hello');
$transport = $mailer->getLastTransport();

getLastSmtpError() : ?string

Возвращает текст последней SMTP-ошибки, если во время отправки через SMTP произошёл сбой.

Если SMTP-ошибки не было, возвращает null.

Пример:

try {
    $mailer->sendText('user@example.com', 'Test', 'Hello');
} catch (Throwable $e) {
    $smtpError = $mailer->getLastSmtpError();
}

HTML-шаблон письма

mailHtmlTemplate(string $html, ?string $footerText = null) : string

Формирует HTML-обёртку письма в стиле WebSource.

Параметры:

Возвращает:

Пример:

$html = $mailer->mailHtmlTemplate(
    '<h1>Добро пожаловать</h1><p>Спасибо за регистрацию.</p>',
    'Команда WebSource'
);

Вложения

Каждое вложение передаётся как элемент массива.

Формат:

[
    'path' => '/absolute/path/to/file.pdf',
    'name' => 'manual.pdf',
    'mime' => 'application/pdf'
]

Поддерживаемые ключи:

Пример:

$mailer->sendText(
    'user@example.com',
    'Документы',
    'Во вложении находится файл.',
    [
        [
            'path' => '/var/www/files/report.pdf',
            'name' => 'report.pdf',
            'mime' => 'application/pdf'
        ]
    ]
);

Исключения

Класс может выбрасывать стандартные исключения PHP:

Ограничения и замечания

• класс работает только с одним получателем за один вызов
• в публичном API нет отдельных методов для CC и BCC
• SMTP-аутентификация реализована через AUTH LOGIN
• ping() проверяет соединение и запуск TLS, но не проверяет SMTP-авторизацию и отправку письма
• при HTML-отправке текстовая версия письма создаётся автоматически, если text не передан
• вложения должны существовать на диске и быть доступны для чтения
• если from-email не задан явно, класс пытается определить его из smtp-login или sendmail_from

Что использовать

Используйте sendText(), если:

• письмо должно содержать только обычный текст
• не нужна HTML-вёрстка

Используйте sendHtml(), если:

• письмо должно содержать HTML-разметку
• нужна шаблонная обёртка письма
• нужна автоматическая текстовая версия