Руководство по использованию класса Mail

Введение

Класс Mail — это модуль для отправки электронных писем на платформе Wepps с поддержкой HTML/Plain текста, вложений и режима отладки. Класс автоматически обрабатывает кодирование заголовков, MIME-границы и форматирование контента.

Основные возможности

• ✉️ Отправка писем в формате HTML и Plain Text
• 📎 Прикрепление файлов из файловой системы
• 📄 Прикрепление файлов из памяти (input)
• 🐛 Режим отладки для тестирования
• 🎨 Интеграция с шаблонизатором Smarty
• 🔤 Автоматическое кодирование UTF-8
• 📧 Настройка отправителя

Установка и подключение

use WeppsExtensions\Addons\Messages\Mail\Mail;

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

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

$mail = new Mail('plain');
$result = $mail->mail(
    'user@example.com',
    'Тема письма',
    'Текст вашего сообщения'
);

if ($result) {
    echo "Письмо отправлено успешно!";
} else {
    echo "Ошибка отправки письма";
}

Отправка HTML письма

$mail = new Mail('html');
$htmlContent = '<h1>Привет!</h1><p>Это <strong>HTML</strong> письмо.</p>';

$result = $mail->mail(
    'user@example.com',
    'HTML письмо',
    $htmlContent
);

Конструктор

public function __construct($type = 'plain')

Параметры:

• $type (string) — тип письма: 'plain' (по умолчанию) или 'html'

Автоматическая инициализация:

• Устанавливает отправителя из Connect::$projectInfo
• Создает уникальную MIME-границу
• Включает режим отладки, если Connect::$projectDev['debug'] == 1

⚠️ Важно: Если на сервере разработки установлен параметр debug = 1, все письма будут автоматически перенаправлены на Connect::$projectDev['email'] независимо от указанного получателя.

Основные методы

mail()

Формирует и отправляет письмо.

public function mail(string $to, string $subject, string $text): bool

Параметры:

• $to — email получателя
• $subject — тема письма
• $text — содержимое письма (HTML или plain text)

Возвращает: true при успешной отправке, false при ошибке

Пример:

$mail = new Mail('html');
$mail->mail(
    'customer@example.com',
    'Подтверждение заказа',
    '<h2>Ваш заказ #12345 принят</h2>'
);

setSender()

Изменяет отправителя письма.

public function setSender($name, $email): void

Параметры:

• $name — имя отправителя
• $email — email отправителя

Пример:

$mail = new Mail('plain');
$mail->setSender('Служба поддержки', 'support@company.com');
$mail->mail('user@example.com', 'Ответ на запрос', 'Ваша проблема решена.');

setAttach()

Прикрепляет файлы из файловой системы.

public function setAttach(array $attachment = []): void

Параметры:

• $attachment — массив путей к файлам

Пример:

$mail = new Mail('html');
$mail->setAttach([
    '/path/to/document.pdf',
    '/path/to/image.jpg'
]);
$mail->mail(
    'user@example.com',
    'Документы',
    '<p>Прикрепленные документы во вложении.</p>'
);

setAttachInput()

Прикрепляет файлы из памяти (без сохранения на диск).

public function setAttachInput(array $attachment = []): void

Параметры:

• $attachment — массив с ключами 'title' (имя файла) и 'content' (содержимое)

Пример:

$csvData = "Name,Email\nJohn,john@example.com\nJane,jane@example.com";

$mail = new Mail('plain');
$mail->setAttachInput([
    [
        'title' => 'users.csv',
        'content' => $csvData
    ]
]);
$mail->mail(
    'admin@example.com',
    'Отчет пользователей',
    'CSV отчет во вложении'
);

setDebug() / unsetDebug()

Управление режимом отладки.

public function setDebug(): int
public function unsetDebug(): int

Режим отладки:

• Доступен только когда Connect::$projectDev['debug'] == 1
• В режиме отладки все письма автоматически перенаправляются на Connect::$projectDev['email'] вместо реального получателя
• Это защищает от случайной отправки тестовых писем реальным пользователям

Пример:

$mail = new Mail('html');
$mail->setDebug(); // Принудительно включить отладку
$mail->mail(
    'user@example.com', // Будет заменен на dev email
    'Тестовое письмо',
    '<p>Это тест</p>'
);

getContent()

Получает сформированное содержимое письма.

public function getContent(bool $contentAll = false): string

Параметры:

• $contentAll — если true, возвращает полное содержимое с заголовками, если false — только тело

Пример:

$mail = new Mail('html');
$mail->mail('user@example.com', 'Тест', '<p>Контент</p>');

// Получить только тело письма
$body = $mail->getContent(false);

// Получить полное содержимое с MIME заголовками
$fullContent = $mail->getContent(true);

save()

Сохраняет содержимое письма в файл (для отладки).

public function save($filename = ''): void

Параметры:

• $filename — путь к файлу (по умолчанию сохраняет в files/mail.html)

Пример:

$mail = new Mail('html');
$mail->mail('user@example.com', 'Тест', '<h1>Тестовое письмо</h1>');
$mail->save('/tmp/debug_email.html'); // Сохранить для проверки

Практические примеры

Пример 1: Письмо с подтверждением регистрации

use WeppsExtensions\Addons\Messages\Mail\Mail;

function sendRegistrationEmail($userEmail, $userName, $activationLink) {
    $mail = new Mail('html');

    $htmlContent = "
        <h2>Добро пожаловать, {$userName}!</h2>
        <p>Спасибо за регистрацию на нашем сайте.</p>
        <p>Для активации аккаунта перейдите по ссылке:</p>
        <p><a href='{$activationLink}'>Активировать аккаунт</a></p>
        <p>Если вы не регистрировались, проигнорируйте это письмо.</p>
    ";

    return $mail->mail(
        $userEmail,
        'Подтверждение регистрации',
        $htmlContent
    );
}

// Использование
sendRegistrationEmail(
    'newuser@example.com',
    'Иван Петров',
    'https://example.com/activate?token=abc123'
);

Пример 2: Отправка счета с PDF-вложением

function sendInvoiceEmail($customerEmail, $invoiceNumber, $pdfPath) {
    $mail = new Mail('html');

    // Устанавливаем отправителя
    $mail->setSender('Бухгалтерия', 'billing@company.com');

    // Прикрепляем PDF
    $mail->setAttach([$pdfPath]);

    $htmlContent = "
        <h2>Счет #{$invoiceNumber}</h2>
        <p>Уважаемый клиент,</p>
        <p>Ваш счет №{$invoiceNumber} во вложении.</p>
        <p>Пожалуйста, оплатите в течение 7 дней.</p>
        <p>С уважением,<br>Бухгалтерия</p>
    ";

    return $mail->mail(
        $customerEmail,
        "Счет #{$invoiceNumber}",
        $htmlContent
    );
}

// Использование
sendInvoiceEmail(
    'client@example.com',
    '2026-001',
    '/var/invoices/2026-001.pdf'
);

Пример 3: Массовая рассылка с динамическим контентом

function sendNewsletterToUsers($users) {
    $mail = new Mail('html');
    $mail->setSender('Новости компании', 'news@company.com');

    $results = [];
    foreach ($users as $user) {
        $htmlContent = "
            <h2>Привет, {$user['name']}!</h2>
            <p>У нас есть специальное предложение для вас:</p>
            <ul>
                <li>Скидка 20% на все товары</li>
                <li>Бесплатная доставка</li>
            </ul>
            <p><a href='https://shop.com/promo/{$user['id']}'>Перейти в магазин</a></p>
        ";

        $result = $mail->mail(
            $user['email'],
            'Специальное предложение!',
            $htmlContent
        );

        $results[$user['email']] = $result;
    }

    return $results;
}

// Использование
$users = [
    ['id' => 1, 'name' => 'Алексей', 'email' => 'alex@example.com'],
    ['id' => 2, 'name' => 'Мария', 'email' => 'maria@example.com']
];
sendNewsletterToUsers($users);

Пример 4: Отправка отчета из базы данных

function sendDatabaseReport($adminEmail) {
    // Формируем CSV из данных БД
    $csvContent = "ID,Name,Email,Status\n";
    $users = getUsersFromDatabase(); // ваша функция

    foreach ($users as $user) {
        $csvContent .= "{$user['id']},{$user['name']},{$user['email']},{$user['status']}\n";
    }

    $mail = new Mail('plain');
    $mail->setSender('Система отчетов', 'reports@company.com');

    // Прикрепляем CSV из памяти
    $mail->setAttachInput([
        [
            'title' => 'users_report_' . date('Y-m-d') . '.csv',
            'content' => $csvContent
        ]
    ]);

    return $mail->mail(
        $adminEmail,
        'Ежедневный отчет пользователей',
        'Отчет по пользователям за ' . date('d.m.Y') . ' во вложении.'
    );
}

Пример 5: Уведомление с несколькими вложениями

function sendProjectDocuments($clientEmail, $projectName, $files) {
    $mail = new Mail('html');
    $mail->setSender('Менеджер проектов', 'pm@company.com');

    // Прикрепляем все файлы проекта
    $mail->setAttach($files);

    $fileList = '';
    foreach ($files as $file) {
        $fileList .= '<li>' . basename($file) . '</li>';
    }

    $htmlContent = "
        <h2>Документация проекта: {$projectName}</h2>
        <p>Здравствуйте!</p>
        <p>Направляем вам документы по проекту:</p>
        <ul>{$fileList}</ul>
        <p>Если есть вопросы — свяжитесь с нами.</p>
    ";

    return $mail->mail(
        $clientEmail,
        "Документы проекта: {$projectName}",
        $htmlContent
    );
}

// Использование
sendProjectDocuments(
    'client@example.com',
    'Website Redesign',
    [
        '/projects/redesign/specification.pdf',
        '/projects/redesign/mockups.pdf',
        '/projects/redesign/timeline.xlsx'
    ]
);

Особенности работы класса

Автоматическое кодирование

Класс автоматически обрабатывает:

• UTF-8 кодирование для всего контента
• Base64 для заголовков (тема, имя отправителя)
• Quoted-Printable для тела письма
• Base64 для вложений

Интеграция с Smarty

Класс использует шаблоны Smarty для форматирования писем:

• MailHtml.tpl — для HTML писем
• MailPlain.tpl — для текстовых писем

Доступные переменные в шаблоне:

• $settings — информация о проекте и хосте
• $subject — тема письма (только для HTML)
• $text — содержимое письма

MIME и структура

Класс формирует письма по стандарту MIME:

• Использует multipart/related для поддержки вложений
• Каждая часть письма разделена уникальной границей
• Автоматически добавляет корректные заголовки Content-Type

Отладка и тестирование

Включение режима отладки

Автоматическое включение:

Если на сервере установлен параметр Connect::$projectDev['debug'] = 1, режим отладки включается автоматически при создании объекта. Все письма будут отправляться на адрес из Connect::$projectDev['email'], а не на указанного получателя.

// Если Connect::$projectDev['debug'] == 1, режим отладки уже активен
$mail = new Mail('html');

// Письмо будет отправлено на Connect::$projectDev['email'],
// а НЕ на user@example.com
$mail->mail(
    'user@example.com', // Адрес будет автоматически заменен
    'Тест',
    '<p>Тестовое письмо</p>'
);

Ручное управление:

// Явно включить режим отладки
$mail = new Mail('html');
$mail->setDebug();

// Или отключить, если нужно отправить на реальный адрес
$mail->unsetDebug();

Сохранение для проверки

$mail = new Mail('html');
$mail->mail('user@example.com', 'Тест', '<h1>Контент</h1>');

// Сохранить HTML для проверки в браузере
$mail->save('/tmp/test_email.html');

// Получить контент программно
$htmlBody = $mail->getContent(false);
$fullMime = $mail->getContent(true);

Рекомендации и лучшие практики

✅ Делайте так:

1. Проверяйте результат отправки:

   $result = $mail->mail($to, $subject, $text);
   if (!$result) {
   logError("Failed to send email to {$to}");
   }

2. Используйте осмысленные темы:

   // Хорошо
   $mail->mail($email, 'Заказ #12345 оформлен', $content);

// Плохо $mail->mail($email, 'Письмо', $content);

3. **Валидируйте email перед отправкой:**
```php
if (filter_var($email, FILTER_VALIDATE_EMAIL)) {
    $mail->mail($email, $subject, $text);
}

4. Проверяйте существование файлов для вложений:

   $attachments = [];
   foreach ($files as $file) {
   if (file_exists($file)) {
       $attachments[] = $file;
   }
   }
   $mail->setAttach($attachments);

❌ Избегайте:

1. Не отправляйте письма в цикле без контроля:

   // Плохо - может вызвать блокировку
   foreach ($users as $user) {
   $mail = new Mail('html');
   $mail->mail($user['email'], 'Spam', 'Content');
   }

// Лучше - добавьте паузы и обработку ошибок foreach ($users as $user) { $mail = new Mail('html'); if ($mail->mail($user['email'], 'Newsletter', $content)) { usleep(100000); // 0.1 сек задержка } }

2. **Не забывайте про тестирование:**
```php
// Включайте отладку при разработке
if (ENVIRONMENT === 'development') {
    $mail->setDebug();
}

Устранение неполадок

Письма не отправляются

Проблема: mail() возвращает false

Решения:

• Проверьте настройки SMTP на сервере
• Убедитесь, что PHP функция mail() доступна
• Проверьте логи сервера /var/log/mail.log
• Проверьте, что email отправителя корректный

Письма попадают в спам

Решения:

• Настройте SPF и DKIM записи для домена
• Используйте реальный email отправителя
• Избегайте спам-триггеров в тексте (БЕСПЛАТНО, !!!!, ВЫИГРАЛ)
• Добавьте ссылку отписки

Кириллица отображается некорректно

Решения:

• Класс автоматически обрабатывает UTF-8
• Убедитесь, что исходный PHP файл в UTF-8
• Проверьте, что база данных использует UTF-8

Вложения не открываются

Решения:

• Проверьте права доступа к файлам
• Убедитесь, что путь к файлу абсолютный
• Проверьте размер вложений (обычно лимит 25MB)

Заключение

Класс Mail предоставляет удобный API для отправки писем в приложениях на платформе Wepps. Используйте методы класса последовательно, проверяйте результаты отправки и тестируйте письма перед production-запуском.

Для более сложных сценариев (массовые рассылки, очереди) рассмотрите использование специализированных решений вроде SMTP-библиотек или сервисов email-рассылок.