Плагин PHPMailer для Cotonti Siena

Плагин PHPMailer улучшает функционал отправки email в Cotonti Siena, интегрируя библиотеку PHPMailer (версия 6.10.0). Он заменяет стандартную функцию cot_mail на мощное решение на основе SMTP, добавляя продвинутые возможности, такие как изоляция плагинов, защита от дублирования писем и детальное логирование. Плагин создан для разработчиков, которым нужен точный контроль над email-уведомлениями в Cotonti, особенно для плагинов comments и contact.

• Использует PHPMailer 6.10.0 для отправки писем через SMTP, поддерживая современные почтовые серверы с аутентификацией и шифрованием (SSL/TLS).
• Настраиваемые параметры SMTP (хост, порт, имя пользователя, пароль и т.д.) через админ-панель Cotonti.
• Не требует Composer; все зависимости включены в плагин.

• Позволяет выборочно отключать отправку писем для определённых плагинов (например, comments, contact).
• Управляется через настройку $enable_plugin_isolation и массив $isolated_plugins.
• Полезно для предотвращения нежелательных уведомлений (например, отключение уведомлений о комментариях для админов).
• Использует переменную Cotonti $env['ext'] для определения вызывающего плагина, с возвратом 'unknown', если плагин не определён.

• Поддерживает несколько форматов получателей:
  • Одиночный email (например, [email protected]).
  • Массив email’ов (например, ['[email protected]', '[email protected]']).
  • Сложные массивы от плагинов, таких как contact (например, ['to' => '[email protected]', 'from' => ['[email protected]', 'test_user']]).
• Проверяет email-адреса с помощью filter_var(FILTER_VALIDATE_EMAIL) для исключения ошибок.
• Игнорирует некорректные или не-email элементы, обеспечивая надёжную работу.

• Предотвращает отправку дублирующихся писем с помощью двух механизмов:
  • Ключ полного сообщения ($mail_key): Основан на получателе, теме и теле письма (хэш MD5). Блокирует одинаковые письма.
  • Ключ получатель-тема ($recipient_key): Блокирует письма одному получателю с той же темой в течение 60 секунд.
• Использует глобальный массив $cot_mail_processed для отслеживания отправленных писем в рамках запроса.

• Записывает все попытки отправки писем в plugins/phpmailer/logs/phpmailer.log (если включено):
  • Включает Request ID, получателя, тему, плагин, URI запроса, параметры GET/POST и укороченное тело письма.
  • Логирует пропуски из-за изоляции плагинов или дублирования.
• Отладочное логирование SMTP в plugins/phpmailer/logs/phpmailer_debug.log (если включено):
  • Фиксирует подробности SMTP-взаимодействия (например, подключение, аутентификация).
• Логирование настраивается через $enable_main_logging и $enable_debug_logging.

• Применяет шаблоны писем Cotonti ($cfg['subject_mail'], $cfg['body_mail']), если не указан кастомный шаблон.
• Подставляет переменные, такие как SITE_TITLE, SITE_URL, MAIL_SUBJECT, MAIL_BODY.
• Обеспечивает корректное кодирование тем в UTF-8 с помощью mb_encode_mimeheader.

• Корректно обрабатывает некорректных получателей, ошибки SMTP и проблемы с конфигурацией.
• Логирует ошибки в лог плагина и системный лог Cotonti (cot_log).
• Возвращает соответствующие булевы значения (true для успешной отправки или пропуска, false для ошибок), сохраняя совместимость с плагинами Cotonti.

• Протестирован с PHP 8.2 и Cotonti Siena v0.9.26.
• Избегает проблем со строгими типами и безопасно обрабатывает преобразование массивов в строки.

• Скачивание плагина

  • Клонируйте или скачайте репозиторий в директорию plugins/ вашей установки Cotonti.

• Структура директорий

  • Убедитесь, что структура следующая:

    plugins/phpmailer/
    ├── phpmailer.global.php
    ├── phpmailer.setup.php
    ├── src/
    │   ├── PHPMailer.php
    │   ├── SMTP.php
    │   ├── Exception.php
    ├── lang/
    │   ├── phpmailer.en.lang.php
    │   ├── phpmailer.ru.lang.php
    ├── logs/
    │   ├── phpmailer.log (создаётся автоматически)
    │   ├── phpmailer_debug.log (создаётся автоматически)
    

     

Установка прав доступа

• Убедитесь, что директория plugins/phpmailer/logs/ доступна для записи:

  chmod 0755 plugins/phpmailer/logs
  chmod 0644 plugins/phpmailer/logs/*.log

   

3. • Пользователь веб-сервера (например, www-data) должен иметь права на запись.

4. Активация плагина

   • Зайдите в админ-панель Cotonti (Администрирование > Расширения).
   • Найдите phpmailer и активируйте его.

• Настройки SMTP

  • В админ-панели Cotonti перейдите в Администрирование > Расширения > PHPMailer > Настроить.
  • Установите следующие параметры:
    • Host: SMTP-сервер (например, smtp.gmail.com).
    • Port: Порт SMTP (например, 587 для TLS).
    • SMTPAuth: Включить/отключить аутентификацию (true/false).
    • SMTPSecure: Тип шифрования (tls или ssl).
    • Username: Имя пользователя SMTP (например, [email protected]).
    • Password: Пароль SMTP.
    • from_author: Email отправителя (например, [email protected]).
    • from_name: Имя отправителя (например, Демо Сайт).
    • reply: Email для ответа (опционально, например, [email protected]).
    • reply_name: Имя для ответа (опционально).

• Настройки плагина

  • Отредактируйте plugins/phpmailer/phpmailer.global.php для настройки:
    • $enable_plugin_isolation: Установите true для включения изоляции указанных плагинов.
    • $isolated_plugins: Массив плагинов для изоляции (например, ['comments', 'contact']).
    • $enable_main_logging: Установите true для включения лога в phpmailer.log.
    • $enable_debug_logging: Установите true для включения отладочного лога SMTP.
    • $mail->SMTPDebug: Установите 1 или выше для подробного вывода отладки SMTP (требует $enable_debug_logging = true).

  Пример:

  $enable_plugin_isolation = true; // Включить изоляцию
  $isolated_plugins = ['comments', 'contact']; // Изолировать плагины comments и contact
  $enable_main_logging = true; // Включить основной лог
  $enable_debug_logging = true; // Включить отладочный лог
  $mail->SMTPDebug = 1; // Базовый вывод отладки SMTP

   

• Чтобы предотвратить отправку писем из определённых плагинов:
  • Установите $enable_plugin_isolation = true.
  • Добавьте имена плагинов в $isolated_plugins (например, ['comments', 'contact']).
• Письма из этих плагинов будут пропущены, с записью в лог:

  [2025-05-07 12:00:00] Request ID: 123abc, Email to [email protected] skipped due to plugin isolation (plugin: contact).
  

   

• Включите логирование для отладки:
  • Установите $enable_main_logging = true для записи попыток и результатов отправки.
  • Установите $enable_debug_logging = true и $mail->SMTPDebug = 1 для деталей SMTP.
• Логи сохраняются в plugins/phpmailer/logs/:
  • phpmailer.log: Общая активность email (попытки, успехи, пропуски).
  • phpmailer_debug.log: Детали отладки SMTP.
• Пример записи в логе:

  [2025-05-07 12:00:00] Request ID: 123abc, Attempt to send email to: {"to":"[email protected]","from":["[email protected]","test_user"]}, Subject: Dropped, HTML: false, Plugin: contact, Request URI: /contact, GET: {"rwr":"contact","e":"contact"}, POST: {...}, Body (short): Демо Сайт - https://demo.domain.ltd
  [2025-05-07 12:00:00] Request ID: 123abc, Successfully sent email to [email protected]
  

   

• Автоматически блокирует:
  • Одинаковые письма (тот же получатель, тема, тело).
  • Письма одному получателю с той же темой в течение 60 секунд.
• Логируется как:

  [2025-05-07 12:00:00] Request ID: 123abc, Email to [email protected] with recipient key 1f6e555fafe32cbfb7a311fbf9e83f3e blocked due to recent send.
  

   

• Плагин обрабатывает сложные массивы $fmail от плагинов, таких как contact:

  $fmail = ['to' => '[email protected]', 'from' => ['[email protected]', 'test_user']];

   

• Извлекает валидные email’ы из $fmail['to'], игнорируя $fmail['from'].

• Проверьте настройки SMTP: Убедитесь, что Host, Port, Username, Password корректны в админ-панели.
• Включите логирование: Установите $enable_main_logging = true, $enable_debug_logging = true, $mail->SMTPDebug = 1 и проверьте phpmailer.log и phpmailer_debug.log.
• Изоляция: Убедитесь, что $enable_plugin_isolation = false или плагин не в $isolated_plugins.

• Если админ получает несколько писем (например, для комментариев):
  • Проверьте, есть ли несколько админов в COT_GROUP_SUPERADMINS (нормальное поведение).
  • Включите $enable_main_logging = true и проверьте Request ID и Mail Key в phpmailer.log.
  • Уменьшите таймаут дублирования (например, с 60 до 10 секунд):

    if (time() - $last_sent < 10) { ... }

     

• Проверьте права доступа:

  ls -l plugins/phpmailer/logs

   
• Убедитесь, что файлы логов имеют права 0644, а директория — 0755.
• Проверьте, что $enable_main_logging и $enable_debug_logging установлены в true.
• Проверьте error_log на перенаправленные логи:

  tail -n 50 /var/log/apache2/error.log

   

• Если $env['ext'] возвращает 'unknown' для плагина, добавьте дополнительный фильтр по содержимому письма:

  if ($enable_plugin_isolation && (in_array($context['plugin'], $isolated_plugins) || strpos($body, 'оставил Комментарий к странице') !== false)) {
      log_phpmailer_file("Request ID: $request_id, Email to $fmail_log skipped due to plugin isolation or comment content.");
      return true;
  }

   

• Cotonti: Siena v0.9.26 (протестировано; может работать с другими версиями, но без гарантии).
• PHP: 8.2 (протестировано; совместимо с 7.x, но рекомендуется протестировать).
• PHPMailer: Версия 6.10.0 (включена, Composer не требуется).

• Форкните репозиторий, внесите изменения и отправьте pull request.
• Сообщайте о проблемах или предлагайте новые функции через GitHub Issues.

• Лицензия MIT (см. файл LICENSE).

• Создан для проекта CleanCot.
• Основан на PHPMailer 6.10.0 от PHPMailer.
• Разработан с любовью к движку Cotonti ❤️.