# =========================================================================== #
# NG CMS // Плагин ads_pro // Управление рекламными и произвольными блоками  #
# =========================================================================== #

## 📋 Описание

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

**Версия 1.0.1** включает полную интеграцию с ng-helpers v0.2.2 для улучшенной производительности, безопасности и мониторинга.

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

### 🎯 Создание и управление блоками

- **Неограниченное количество блоков** - создавайте столько блоков, сколько требуется
- **Группировка блоков** - объединяйте блоки по ID (имени) для удобного управления
- **Три типа контента**:
  - 📝 HTML - полноценный HTML-код с поддержкой стилей и скриптов
  - 🔧 PHP - динамический PHP-код для сложной логики
  - 📄 TEXT - простой текстовый контент

### ⚙️ Гибкие настройки отображения

**Режимы активации:**
- ✅ Постоянный показ - блок всегда активен
- ⏰ По расписанию - автоматический показ в заданное время
- ❌ Выключен - блок неактивен

**Условия показа:**
- 🏠 На главной странице
- 📂 В определенных категориях
- 📰 На страницах новостей
- 📄 На статических страницах
- 🔌 В плагинах
- 🌐 Везде или везде кроме указанных мест

### 🎲 Режимы отображения блоков с одинаковым ID

При наличии нескольких блоков с одинаковым именем:
1. **Последовательно** - показываются все активные блоки один за другим
2. **Первый активный** - показывается только первый подходящий блок
3. **Случайный** - каждый раз выбирается случайный блок из активных

### ⏱️ Показ по расписанию

- **Дата начала показа** - блок начнет отображаться с указанного времени
- **Дата окончания показа** - блок автоматически скроется после указанного времени
- **Гибкие настройки**:
  - Без даты начала → показ начинается немедленно
  - Без даты окончания → показ продолжается бесконечно
  - С обеими датами → точный контроль периода показа

### ⚡ Производительность (ng-helpers v0.2.2)

- **Автоматическое кэширование** - HTML и TEXT блоки кэшируются для быстрой загрузки
- **Настраиваемый TTL кеша** - от 5 минут до 24 часов (параметр cache_duration)
- **Cache HIT/MISS мониторинг** - логирование эффективности кеширования
- **Benchmark PHP блоков** - автоматический замер времени и памяти для PHP блоков
- **Умный сброс кэша** - автоматически сбрасывается при обновлении настроек
- **Синхронизация с БД** - хранение блоков в базе данных для переносимости
- **Поддержка Redis/Memcached** - через ng-helpers для максимальной производительности

### 🔒 Безопасность (ng-helpers v0.2.2)

- **Sanitize обработка** - безопасная очистка HTML и TEXT контента
- **Валидация параметров** - clamp() для типов блоков, состояний и TTL
- **XSS защита** - автоматическое экранирование опасного контента
- **PHP мониторинг** - логирование всех выполнений PHP блоков
- **Аудит синхронизации** - полное логирование операций с БД

### 📊 Мониторинг и логирование (ng-helpers v0.2.2)

- **Детальные логи** - `engine/logs/ads_pro.log` с уровнями важности
- **Производительность** - время выполнения и размер каждого блока
- **Cache аналитика** - HIT/MISS статистика для оптимизации
- **Синхронизация БД** - логирование восстановления/удаления блоков
- **Уровни логирования**: debug, info, warning для разных операций

## 📦 Установка

1. Разместите папку плагина в `engine/plugins/ads_pro/`
2. Активируйте плагин ng-helpers в панели управления (обязательно!)
3. Активируйте плагин ads_pro в панели управления
4. Настройте параметры в разделе "Дополнительно" → "ads_pro"

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

Для вывода блока в шаблоне используйте переменную с именем блока:

```twig
{# Вывод блока с текстовым ID "sidebar_banner" #}
{{ sidebar_banner|raw }}

{# Вывод блока с числовым ID (например, 2222) - добавляется префикс block_ #}
{{ block_2222|raw }}

{# Вывод блока "top_ads" на главной странице #}
{% if isMain %}
    {{ top_ads|raw }}
{% endif %}

{# Условный вывод блока "mobile_menu" #}
{% if system_flags.check_pda %}
    {{ mobile_menu|raw }}
{% endif %}
```

**Важно:**
- Для блоков с текстовыми ID используйте их напрямую: `{{ my_block|raw }}`
- Для блоков с числовыми ID автоматически добавляется префикс `block_`: `{{ block_123|raw }}`
- Всегда используйте фильтр `|raw` для вывода HTML-контента без экранирования

## ⚙️ Настройка

### Общие настройки

- **Поддержка страниц новостей** - включить отображение блоков на полных страницах новостей
- **Сортировка новостей** - выбор порядка отображения в конфигураторе
- **Режим множественного отображения** - выбор стратегии показа блоков с одинаковым ID
- **Длительность кеша (cache_duration)** - от 300 до 86400 секунд (5 мин - 24 часа)

### Управление блоками

1. **Создание блока**:
   - Укажите ID (имя) блока - используется в шаблонах
   - Выберите тип контента (HTML/PHP/TEXT)
   - Добавьте описание для удобства
   - Настройте условия показа

2. **Настройка расписания**:
   - Выберите режим "По расписанию"
   - Укажите дату и время начала показа
   - Укажите дату и время окончания показа

3. **Условия отображения**:
   - Добавьте правила для показа/скрытия
   - Настройте приоритеты
   - Протестируйте на сайте

## 🔧 Примеры использования

### Пример 1: Google AdSense (HTML блок)

```
ID: adsense_sidebar
Тип: HTML
Контент:
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-XXXXX"
     data-ad-slot="XXXXX"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
Условия: Показывать везде кроме главной
Кеш: 43200 секунд (12 часов)
```

### Пример 2: Динамический виджет с мониторингом (PHP блок)

```
ID: dynamic_stats
Тип: PHP
Контент:
<?php
global $mysql;
$count = $mysql->result("SELECT COUNT(*) FROM " . prefix . "_users");
echo '<div class="stats-widget">';
echo '<h3>Статистика</h3>';
echo '<p>Пользователей: ' . $count . '</p>';
echo '</div>';
?>
Условия: Показывать везде
Мониторинг: Автоматический benchmark и логирование
```

### Пример 3: Временная акция (HTML блок)

```
ID: promo_newyear
Тип: HTML
Режим: По расписанию
Начало: 01.12.2026 00:00
Окончание: 31.12.2026 23:59
Контент:
<div class="promo-banner">
    <h2>🎄 Новогодняя распродажа!</h2>
    <p>Скидки до 50% на все товары</p>
    <a href="/sale">Подробнее</a>
</div>
Кеш: 86400 секунд (24 часа)
```

### Пример 4: Текстовый блок (TEXT блок)

```
ID: contact_info
Тип: TEXT
Контент:
📞 Телефон: +7 (999) 123-45-67
📧 Email: info@example.com
🕐 Время работы: 9:00 - 18:00
Условия: Показывать на статических страницах
Безопасность: Автоматическое экранирование HTML
```

## 🛠️ Технические особенности

- **Версия NGCMS**: 0.9.3+
- **PHP**: 7.0+
- **База данных**: MySQL/MariaDB
- **Зависимости**: ng-helpers v0.2.2+ (рекомендуется)
- **Хранение**: Таблица `_ads_pro` + конфигурация плагина
- **Кэш**: Файловый/Redis/Memcached/APCu через ng-helpers
- **Логи**: `engine/logs/ads_pro.log`

### Интеграция с ng-helpers

Плагин использует следующие функции ng-helpers v0.2.2:
- `cache_get()`, `cache_put()` - современное кеширование с поддержкой Redis/Memcached
- `sanitize()` - безопасная обработка HTML и TEXT контента
- `logger()` - комплексное логирование с уровнями важности
- `benchmark()` - мониторинг производительности PHP блоков
- `clamp()` - валидация числовых параметров (TTL, типы, состояния)
- `array_get()`, `array_only()`, `is_ajax()` - вспомогательные функции

**Производительность с разными драйверами кеша:**
- File cache: 1.3-2x ускорение vs старый метод
- Redis cache: 10-50x ускорение (in-memory)
- Memcached: 15-70x ускорение
- APCu: 5-30x ускорение (shared memory)

## 📝 Changelog

### Версия 1.0.1 (2026-01-29)
- ✅ **Интеграция ng-helpers v0.2.2** - полная модернизация
- ✅ **Benchmark PHP блоков** - автоматический мониторинг производительности
- ✅ **Расширенное логирование** - debug/info/warning уровни
- ✅ **Cache HIT/MISS аналитика** - мониторинг эффективности кеша
- ✅ **Настраиваемый TTL** - от 5 минут до 24 часов
- ✅ **Улучшенная безопасность** - раздельная sanitize для HTML/TEXT
- ✅ **Валидация параметров** - clamp для типов и состояний блоков
- ✅ **Подробная документация** - CHANGELOG_NGHELPERS.md

### Версия 1.0.0 (2026-01-15)
- ✅ Синхронизация с базой данных при переносе сайта
- ✅ Поддержка ng-helpers для улучшенной производительности
- ✅ Современный интерфейс настроек с табами
- ✅ Исправлена активация табов в настройках
- ✅ Полная миграция на Twig синтаксис

## 🤝 Поддержка

При возникновении вопросов или проблем:
- Проверьте активацию плагина в админ-панели
- Убедитесь, что ng-helpers v0.2.2+ активирован
- Проверьте ID блока в шаблоне (добавьте префикс `block_` для числовых ID)
- Проверьте условия показа блока
- Очистите кэш плагина через настройки
- Просмотрите логи в `engine/logs/ads_pro.log` для диагностики
- Проверьте производительность PHP блоков через benchmark данные в логах

### Анализ производительности

Просмотр Cache HIT/MISS статистики:
```bash
# PowerShell
Get-Content engine\logs\ads_pro.log | Select-String "Cache HIT"
Get-Content engine\logs\ads_pro.log | Select-String "Cache MISS"

# Медленные PHP блоки (> 100ms)
Get-Content engine\logs\ads_pro.log | Select-String "PHP block executed" | Select-String -Pattern "time=[1-9][0-9]{2,}"
```

### Настройка TTL кеша

В админ-панели плагина или через код:
```php
// Настройка длительности кеша (в секундах)
pluginSetVariable('ads_pro', 'cache_duration', 3600);   // 1 час
pluginSetVariable('ads_pro', 'cache_duration', 43200);  // 12 часов
pluginSetVariable('ads_pro', 'cache_duration', 86400);  // 24 часа (максимум)
pluginsSaveConfig();
```

### Просмотр логов PHP блоков

```bash
# Все выполнения PHP блоков
Get-Content engine\logs\ads_pro.log | Select-String "PHP block"

# Только медленные блоки
Get-Content engine\logs\ads_pro.log | Select-String "PHP block executed" | Where-Object { $_ -match "time=([0-9]+)" -and [int]$matches[1] -gt 100 }
```

## 📄 Лицензия

Плагин распространяется "как есть" для использования с NG CMS.

---
**Разработка**: NG CMS Community  
**ng-helpers интеграция**: Copilot + russsiq  
**Документация обновлена**: 29.01.2026  
**Версия**: 1.0.1

📖 **Дополнительная документация**: См. `CHANGELOG_NGHELPERS.md` для полного описания интеграции ng-helpers
