# Плагин Email-рассылки для NGCMS (версия 2.0)

## Описание

Современный плагин для массовых email-рассылок с поддержкой:

- ✅ Сегментация пользователей по группам
- ✅ Вложения (изображения, PDF, DOC, XLS и т.д.)
- ✅ Отложенная отправка
- ✅ Очередь отправки с повторными попытками
- ✅ Ссылка отписки в каждом письме
- ✅ Авто-рассылка новых новостей
- ✅ Поддержка SMTP
- ✅ Интеграция с Twig-шаблонами
- ✅ PHP 8.1+ с современным синтаксисом

## Требования

- NGCMS с поддержкой Twig
- PHP 8.1 или выше
- MySQL/MariaDB

## Установка

1. Скопируйте папку `mailing` в `/engine/plugins/`
2. Активируйте плагин через админ-панель NGCMS
3. При установке будут созданы 4 таблицы:
   - `mailing_campaigns` - кампании рассылок
   - `mailing_queue` - очередь отправки писем
   - `mailing_attachments` - вложения к письмам
   - `mailing_unsub` - отписки пользователей
4. Настройте параметры: `admin.php?mod=extra-config&plugin=mailing`

**Важно:** При деинсталляции все данные и загруженные файлы будут удалены!

## Настройка

### Базовые настройки

**Отправитель:**

- `from_email` - Email отправителя (по умолчанию: no-reply@ваш-сайт)
- `from_name` - Имя отправителя
- `reply_to` - Email для ответов
  **SMTP (опционально):**
- `smtp_enable` - Включить SMTP (рекомендуется для надежности)
- `smtp_host` - Хост SMTP-сервера (например: smtp.gmail.com)
- `smtp_port` - Порт (587 для TLS, 465 для SSL)
- `smtp_auth` - Включить авторизацию
- `smtp_user` - Логин SMTP
- `smtp_pass` - Пароль SMTP
- `smtp_secure` - Тип шифрования (tls/ssl)
  **Отправка:**
- `send_batch` - Количество писем за один проход (по умолчанию: 50)
- `max_tries` - Максимум попыток отправки (по умолчанию: 3)
- `allow_iframe` - Разрешить `<iframe>` в HTML (не рекомендуется)

### Обработка очереди

Есть 2 способа:

#### Способ A: CRON (рекомендуется)

1. Задайте секретный ключ в настройках плагина (`cron_secret`)
2. Добавьте в crontab:

```bash
*/5 * * * * curl -s "https://ваш-сайт.ru/?mailing_cron=1&secret=ВАШ_СЕКРЕТ" >/dev/null
```

#### Способ B: По посещениям

1. Включите `enable_tick` в настройках
2. Установите `tick_chance` (шанс запуска в %, например 10)
   Плагин будет обрабатывать очередь при посещениях сайта.

### Авто-рассылка новых новостей

1. Включите `auto_news_enable`
2. Укажите ID категории (0 = все категории)
3. Укажите группы пользователей в JSON: `[1,2,3]`
4. Установите лимит новостей за проход
   Плагин автоматически найдет новые опубликованные новости и создаст рассылку.

## Использование

### Создание рассылки через админку

1. Перейдите: `admin.php?mod=extra-config&plugin=mailing&sub=compose`
2. Заполните:
   - Название кампании
   - Тема письма
   - HTML-содержимое
   - Текстовую версию (опционально)
3. Выберите сегмент пользователей
4. Загрузите вложения (опционально)
5. Нажмите "Создать и поставить в очередь"

### Специальные теги в HTML

- `{UNSUB_URL}` - Ссылка отписки (добавляется автоматически)
- `{YOUTUBE:https://youtu.be/ID}` - Превью YouTube-видео

### Использование в Twig-шаблонах

**Вывод статистики рассылок:**

```twig
{{ callPlugin("mailing.stats") }}
```

**Форма подписки/отписки:**

```twig
{{ callPlugin("mailing.form") }}
```

## Структура базы данных

Плагин создает 4 таблицы:

1. **mailing_campaigns** - Кампании рассылок
2. **mailing_queue** - Очередь отправки
3. **mailing_attachments** - Вложения
4. **mailing_unsub** - Отписки пользователей

## Отписка

В каждое письмо автоматически добавляется:

- Ссылка отписки: `/?mailing_unsub=1&token=...`
- Заголовок `List-Unsubscribe` для почтовых клиентов
  Отписавшиеся пользователи больше не будут получать письма.

## Безопасность

- ✅ Валидация всех входных данных
- ✅ Защита от SQL-инъекций через db_squote()
- ✅ Санитизация HTML (удаление опасных тегов/атрибутов)
- ✅ Защита CRON-URL секретным ключом
- ✅ Токены отписки (64 символа hex)

## Разработка

### Файловая структура

```
mailing/
├── mailing.php          # Основной файл плагина
├── config.php           # Админ-панель настроек
├── install.php          # Скрипт установки
├── uninstall.php        # Скрипт удаления
├── install.sql          # SQL-схема
├── version              # Метаданные плагина
├── README.md            # Документация
├── lib/
│   ├── common.php       # Вспомогательные функции
│   ├── mailer.php       # Отправка email
│   └── queue.php        # Обработка очереди
└── tpl/
    ├── stats.tpl        # Шаблон статистики
    └── subscription_form.tpl  # Форма подписки
```

### API функции

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

- `mailing_cfg($key, $default)` - Получить значение
- `mailing_cfg_bool($key, $default)` - Получить boolean
- `mailing_set_cfg($key, $value)` - Установить значение
  **База данных:**
- `mailing_db()` - Получить инстанс БД
- `mailing_tbl($name)` - Имя таблицы с префиксом
  **Отправка:**
- `mailing_send_email($to, $name, $subject, $html, $text, $attachments, $headers)` - Отправить письмо
- `mailing_create_campaign_and_queue($title, $subject, $html, $text, $segment)` - Создать кампанию
  **Утилиты:**
- `mailing_h($string)` - HTML-экранирование
- `mailing_token($length)` - Генерация токена
- `mailing_sanitize_html($html, $allowIframe)` - Санитизация HTML

## Устранение проблем

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

1. Проверьте настройки SMTP
2. Убедитесь, что cron работает
3. Проверьте логи сервера
   **Ошибки БД:**

- Адаптируйте `lib/queue.php` под вашу версию NGCMS
- Проверьте имена полей в таблицах `users` и `news`
  **Письма в SPAM:**

1. Настройте SMTP с авторизацией
2. Добавьте SPF/DKIM записи для домена
3. Используйте реальный email отправителя

## Лицензия

GNU GPL v2 или выше

## Поддержка

- Форум NGCMS: https://ngcms.ru/forum/
- GitHub Issues: (если применимо)

## Changelog

### Версия 2.0.0

- ✨ Полная переработка под PHP 8.1+
- ✨ Добавлена интеграция с Twig
- ✨ Современный синтаксис (типизация, match, named arguments)
- ✨ Улучшенная безопасность
- ✨ Обновленная документация
- ✨ Новые Twig-функции для шаблонов
