Плагин tgm4market: интеграция магазина Cotonti с Telegram

Полное руководство по установке, настройке и использованию

Автор: webitproff
Репозиторий: https://github.com/webitproff/telegram-market-cotonti

Оглавление

1. Введение
2. Основные возможности
3. Архитектура и структура файлов
4. Установка плагина
5. Настройка Telegram
6. Настройка плагина через админ-панель Cotonti
7. Размещение тегов в шаблонах
8. Работа плагина: добавление, редактирование и удаление товаров
9. Виджет обсуждения на странице товара
10. Хранение настроек и данных
11. Пошаговый сценарий использования
12. Репозиторий и поддержка
13. Заключение

Введение

tgm4market — плагин для системы управления контентом Cotonti CMF, предназначенный для полной интеграции интернет-магазина (модуль Market) с мессенджером Telegram. Он автоматически публикует информацию о новых и изменённых товарах в ваш Telegram-канал и встраивает на страницу каждого товара официальный виджет обсуждения Telegram. Это позволяет вашим подписчикам оперативно узнавать о новинках, а посетителям сайта — видеть и оставлять комментарии (через Telegram) прямо из карточки товара.

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

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

• Автоматическая публикация при создании нового товара: в Telegram-канал отправляется сообщение с названием товара и ссылкой на страницу сайта.
• Гибкое управление при редактировании товара: можно выбрать, следует ли создать новый пост, обновить существующий или ничего не делать.
• Официальный виджет обсуждения Telegram встраивается в страницу товара через специальный тег. Комментарии к посту канала отображаются непосредственно на сайте.
• Удаление связи при удалении товара: запись о соответствии товара и Telegram-сообщения удаляется из базы данных (само сообщение в канале остаётся).
• Независимая конфигурация через удобную админ-панель: токен бота и данные канала хранятся в отдельной таблице базы данных, а не прописываются в коде.
• Поддержка русского и английского языков в интерфейсе плагина.
• Безопасность: встроенная обработка входных данных, использование htmlspecialchars для предотвращения XSS-атак.

Архитектура и структура файлов

Плагин состоит из нескольких хуковых файлов, которые подключаются к событиям модуля Market и расширяют его функционал. Настройки вынесены в отдельную таблицу базы данных, а административный интерфейс реализован как инструмент в разделе «Инструменты» (Tools).

Структура папки плагина (plugins/tgm4market/):

tgm4market/
├── tgm4market.setup.php          // Заголовок плагина и регистрация
├── tgm4market.admin.php          // Контроллер страницы настроек
├── tgm4market.admin.tpl          // Шаблон формы настроек
├── tgm4market.global.php         // Файл глобального хука (подключает язык)
├── tgm4market.market.add.add.done.php   // Обработчик завершения добавления товара
├── tgm4market.market.add.tags.php       // Хук тегов: добавляет радиокнопки в форму добавления
├── tgm4market.market.edit.update.done.php // Обработчик завершения обновления товара
├── tgm4market.market.edit.delete.done.php // Обработчик удаления товара
├── tgm4market.market.edit.tags.php      // Хук тегов: добавляет радиокнопки в форму редактирования
├── tgm4market.market.tags.php           // Хук тегов: генерирует виджет обсуждения на странице товара
├── inc/
│   └── tgm4market.functions.php         // Основные функции: отправка/редактирование сообщений, получение конфигурации
├── lang/
│   ├── tgm4market.ru.lang.php           // Русский языковой файл
│   └── tgm4market.en.lang.php           // Английский языковой файл
└── setup/
    ├── tgm4market.install.sql           // SQL-запросы при установке
    └── tgm4market.uninstall.sql         // SQL-запросы при удалении

Каждый файл строго отвечает за свою часть логики, что упрощает поддержку и модификацию.

Установка плагина

1. Скопируйте папку tgm4market в директорию plugins/ вашего сайта Cotonti.
2. Зайдите в административную панель, перейдите в раздел «Расширения» → «Плагины».
3. Найдите в списке tgm4market и нажмите кнопку «Установить».
   • При установке автоматически создадутся таблицы в базе данных:
     • cot_tgm4market — хранит связку «ID товара — ID сообщения в Telegram».
     • cot_tgm4market_cfg — хранит настройки: токен бота и юзернеймы канала.
4. После успешной установки плагин станет активным, и вы сможете перейти к его настройке.

Настройка Telegram

Для работы плагина потребуются три сущности в Telegram:

• Бот — будет публиковать сообщения в канал.
• Публичный канал — в него бот будет отправлять посты.
• Группа для комментариев — обсуждения будут проходить в отдельной группе, привязанной к каналу.

Краткая инструкция:

1. Создайте бота через @BotFather. Выполните команду /newbot, задайте имя и юзернейм, заканчивающийся на bot (например, myshop_bot). Полученный токен сохраните — он понадобится для настройки плагина.
2. Создайте публичный канал. При создании обязательно выберите тип «Публичный канал» и задайте юзернейм (например, myshop). Адрес канала будет t.me/myshop. Этот юзернейм понадобится в двух форматах:
   • с символом @ (@myshop) — для отправки сообщений ботом,
   • без символа @ (myshop) — для виджета обсуждения.
3. Создайте группу для комментариев (любую, можно приватную). Откройте созданный канал, перейдите в настройки → «Обсуждение» → «Добавить группу» и выберите созданную группу.
4. Добавьте бота в канал и в группу как администратора. В канале обязательно выдайте право «Публикация сообщений». В группе достаточно права чтения сообщений.

Подробная пошаговая инструкция с картинками (при необходимости) доступна в документации к плагину в репозитории.

Настройка плагина через админ-панель Cotonti

После установки плагина перейдите в «Инструменты» (административная панель Cotonti) и выберите tgm4market. Откроется страница с формой настройки, доступной по адресу:
admin.php?m=other&p=tgm4market

Форма содержит три поля:

• Username канала (без @, для виджета)
  Сюда вводится юзернейм вашего публичного канала без символа @. Например: myshop.
  Это значение используется для формирования HTML-виджета обсуждения на странице товара.
• @Username канала (для отправки сообщений)
  Сюда вводится тот же юзернейм, но уже с символом @. Например: @myshop.
  Это значение используется при отправке сообщений через API Telegram (бот будет публиковать посты именно в этот канал).
• Токен бота
  Вставьте сюда токен, полученный от @BotFather. Строка вида 123456789:ABCdef....

Нажмите «Сохранить». Все данные запишутся в таблицу cot_tgm4market_cfg с идентификатором cfg_id = 1. При повторном открытии страницы настройки автоматически загрузятся из базы данных.

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

Размещение тегов в шаблонах

Для работы плагина в шаблонах вашей темы (скина) Cotonti необходимо разместить специальные теги. Все теги генерируются плагином автоматически при наличии необходимых настроек.

1. Тег для формы добавления товара

Файл: skins/ваш_скин/market.add.tpl
Тег: {TGM4MARKET_ADD_ACTION}

Вставьте его в удобное место (например, перед кнопкой «Сохранить»). Он добавит блок с радиокнопками:

• «Ничего не делать»
• «Опубликовать как новый»

По умолчанию при создании нового товара выбран вариант «Опубликовать как новый» — это означает, что сообщение будет сразу отправлено в канал. При необходимости вы можете переключиться на «Ничего не делать», чтобы пропустить публикацию.

2. Тег для формы редактирования товара

Файл: skins/ваш_скин/market.edit.tpl
Тег: {TGM4MARKET_EDIT_ACTION}

Он добавляет три радиокнопки:

• «Ничего не делать»
• «Опубликовать как новый»
• «Обновить существующий»

По умолчанию выбрано «Ничего не делать», чтобы случайно не изменять Telegram-пост. Выбор действия влияет на поведение при сохранении изменений товара (см. далее).

3. Тег для виджета обсуждения

Файл: skins/ваш_скин/market.tpl (основной шаблон страницы товара)
Тег: {TGM4MARKET_DISCUSSION}

Вставьте его там, где хотите видеть блок обсуждения. Обычно это после описания товара или в отдельной вкладке. Плагин сам подгрузит официальный скрипт виджета Telegram, указав нужный ID поста.

Важно: Все теги будут обработаны только при активном плагине и корректных настройках. Если настройки не заполнены или плагин отключён, теги ничего не выведут.

Работа плагина: добавление, редактирование и удаление товаров

Добавление товара

1. При создании товара администратор может выбрать действие в форме (радиокнопки). Если выбрано «Ничего не делать», плагин завершает работу.
2. Если выбрано «Опубликовать как новый» (по умолчанию), после успешного сохранения товара вызывается функция tgm4market_send_message(). Она формирует текст сообщения:
   • Префикс (например, «🆕 Новый товар:») берётся из языкового файла.
   • Название товара экранируется для безопасности (htmlspecialchars), но в текущей версии используется простая интерполяция строки, так как перенос строки не срабатывал в режиме HTML; предпочтительнее использовать версию с \n и http_build_query.
   • Ссылка на страницу товара формируется абсолютной.
3. Функция отправляет запрос к Telegram Bot API методом sendMessage, используя @username канала и токен бота из настроек. Telegram возвращает уникальный message_id.
4. Плагин сохраняет в таблицу cot_tgm4market запись с item_id (ID товара) и message_id.

Редактирование товара

При редактировании администратор выбирает одно из трёх действий:

• Ничего не делать — плагин не выполняет никаких операций с Telegram.
• Опубликовать как новый — отправляется новое сообщение в канал (аналогично добавлению), а старая связь обновляется: если запись уже была, message_id заменяется, иначе создаётся новая.
• Обновить существующий — если в таблице есть запись для этого товара, вызывается editMessageText в Telegram API, который изменяет текст ранее опубликованного сообщения. Это удобно, когда нужно поправить описание товара без создания нового поста.

Удаление товара

При удалении товара (в корзину или окончательно) плагин просто удаляет запись из таблицы cot_tgm4market, разрывая связь. Сам пост в Telegram остаётся — таким образом, история публикаций сохраняется.

Виджет обсуждения на странице товара

Плагин использует официальный виджет обсуждения Telegram. Он встраивается через тег {TGM4MARKET_DISCUSSION} и отображает ветку комментариев к конкретному посту в канале.

Механизм:

• В момент открытия страницы товара плагин находит в таблице cot_tgm4market запись с item_id товара.
• Извлекает message_id.
• Из настроек берёт chat_id_market (юзернейм канала без @).

• Генерирует HTML-код:

  <script async src="https://telegram.org/js/telegram-widget.js?22"
          data-telegram-discussion="myshop/12345"
          data-comments-limit="5">
  </script>
  

• Этот скрипт автоматически загружает и отображает комментарии из привязанной к каналу группы.

Таким образом, посетители могут видеть обсуждение и оставлять комментарии, если откроют обсуждение в Telegram (нажав на кнопку «Комментировать» на сайте или в самом мессенджере).

Хранение настроек и данных

Плагин использует две таблицы в базе данных Cotonti:

1. cot_tgm4market_cfg — конфигурация

Структура:

• cfg_id — первичный ключ (всегда 1, единственная запись).
• chat_id_market — юзернейм канала без @ (для виджета).
• chat_id_edit — юзернейм канала с @ (для API).
• bot_token — токен бота Telegram.

Доступ к данным конфигурации осуществляется через функцию tgm4market_get_cfg(), которая выполняет запрос:
SELECT * FROM {$db_x}tgm4market_cfg WHERE cfg_id = 1

Во всех файлах плагина, где нужны настройки, вызывается эта функция, и нужное поле извлекается из массива. Это означает, что в коде нет жёстко прописанных токенов или имён каналов — всё загружается динамически из базы.

2. cot_tgm4market — связи товаров и сообщений

Структура:

• item_id (int, уникальный) — идентификатор товара в модуле Market.
• message_id (int) — идентификатор сообщения в Telegram.

Используется для хранения соответствия «какому товару какой пост в канале принадлежит». При формировании виджета и при обновлении поста плагин обращается именно к этой таблице.

Пошаговый сценарий использования

Предположим, вы уже установили плагин и настроили Telegram по инструкции.

1. Заполните настройки плагина
   Перейдите в admin.php?m=other&p=tgm4market, введите myshop в первое поле, @myshop во второе, и токен бота. Нажмите «Сохранить».
2. Добавьте теги в шаблоны
   • В market.add.tpl вставьте {TGM4MARKET_ADD_ACTION}.
   • В market.edit.tpl вставьте {TGM4MARKET_EDIT_ACTION}.
   • В market.tpl вставьте {TGM4MARKET_DISCUSSION} в то место, где хотите видеть обсуждение.
3. Создайте новый товар
   Перейдите на страницу добавления товара. Появится панель с выбором действия. По умолчанию выбрано «Опубликовать как новый». Заполните поля, сохраните.
   Проверьте свой Telegram-канал: там должно появиться сообщение с названием товара и ссылкой.
4. Откройте страницу товара на сайте
   Вы увидите виджет обсуждения. Если в группе комментариев ещё ничего нет, он отобразит «No messages yet». Теперь ваши подписчики могут комментировать, и комментарии будут отображаться на сайте.
5. Отредактируйте товар
   При редактировании появится блок с тремя опциями. Вы можете обновить существующий пост или опубликовать новый. Выберите нужное действие и сохраните изменения.
6. Удалите товар
   При удалении товара связь с постом пропадёт из базы, но сам пост в канале останется (вы можете удалить его вручную, если нужно).

Репозиторий и поддержка

Плагин полностью открыт и доступен для скачивания в репозитории на GitHub:
https://github.com/webitproff/telegram-market-cotonti

Там же находится архив с последней версией и возможностью сообщить об ошибке или предложить улучшение через Issues. Плагин распространяется под лицензией BSD.

Заключение

tgm4market — мощный и гибкий инструмент для автоматизации взаимодействия вашего интернет-магазина на Cotonti с Telegram. Он экономит время администратора, повышает вовлечённость аудитории и делает обсуждение товаров живым и доступным прямо на сайте. Благодаря продуманной архитектуре и простой настройке плагин подходит как небольшим, так и крупным проектам.

Если у вас остались вопросы или вы хотите предложить доработку — обращайтесь в Issues на GitHub. Успешных продаж и активных обсуждений!