Получение обновлений

Библиотека TGZ поддерживает два официальных способа получения обновлений (событий) от Telegram: Long Polling и Webhook. Выбор зависит от ваших задач и инфраструктуры.

Способ 1: Long Polling

Long Polling — это простой метод, при котором ваш скрипт постоянно опрашивает серверы Telegram в ожидании новых обновлений.

Когда использовать:

• Для разработки и отладки: Очень легко запустить на локальной машине без веб-сервера.
• Для простых ботов: Если у бота низкая нагрузка, и нет желания настраивать веб-сервер с SSL.
• В средах, где нельзя открыть порты: Например, за корпоративным файрволом.

Как это работает

Вы запускаете PHP-скрипт из командной строки. Этот скрипт входит в бесконечный цикл и "слушает" новые события. Как только событие приходит, выполняется ваша логика.

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

Создайте файл bot.php и поместите в него следующий код:

<?php

require 'vendor/autoload.php'; // Убедитесь, что подключили автозагрузчик Composer

use ZhenyaGR\TGZ\LongPoll;
use ZhenyaGR\TGZ\TGZ;

$token = 'ВАШ_ТОКЕН_ЗДЕСЬ';

// Создаем экземпляр LongPoll с помощью удобного статического метода
$longPoll = LongPoll::create($token);

// Запускаем прослушивание. Вся магия происходит внутри анонимной функции.
$longPoll->listen(function (TGZ $tg) {
    // Для каждого обновления библиотека автоматически создает и передает вам 
    // полностью готовый к работе объект TGZ.

    // Получаем текст сообщения
    $text = $tg->getText();
    $chat_id = $tg->getChatID();
    
    // Выводим в консоль
    echo "Новое сообщение в чате $chat_id: $text\n";

    // Пример простой команды
    if ($text === '/start') {
        $tg->reply('Привет! Я бот, работающий на TGZ через Long Polling.');
    }

    if ($text === '/time') {
        $time = date('H:i:s');
        $tg->reply("Точное время: {$time}");
    }
});

Запуск

1. Сохраните код в файл (например, bot.php).
2. Откройте терминал или командную строку в этой же директории.
3. Выполните команду:

   php bot.php

4. Вы увидите сообщение Long Poll запущен... Нажмите Ctrl+C для остановки.. Теперь ваш бот активен. Чтобы остановить его, нажмите Ctrl+C.

Важно:

Скрипт с Long Polling не должен размещаться на веб-сервере и запускаться через браузер. Он предназначен исключительно для запуска из командной строки (CLI).

Способ 2: Webhook

Webhook — это более продвинутый и эффективный метод, рекомендуемый для ботов в продакшене. При этом подходе Telegram сам отправляет обновления на ваш сервер по указанному URL в виде POST-запроса, как только они появляются.

Когда использовать:

• Для ботов в продакшене: Это наиболее производительный и масштабируемый способ.
• Для ботов с высокой нагрузкой: Не создает лишних запросов к API Telegram.

Требования

1. Веб-сервер (например, Nginx или Apache).
2. HTTPS: Ваш сервер должен быть доступен по HTTPS с валидным SSL-сертификатом (самоподписанные не принимаются). Сервисы вроде Let's Encrypt предоставляют бесплатные сертификаты.

Шаг 1: Создание скрипта-обработчика

Создайте файл webhook.php на вашем сервере. Этот скрипт будет "точкой входа" для всех обновлений от Telegram.

<?php

require 'vendor/autoload.php'; // Подключаем автозагрузчик

use ZhenyaGR\TGZ\TGZ;

$token = 'ВАШ_ТОКЕН_ЗДЕСЬ';

// Эта одна строка делает всё:
// 1. Принимает входящий запрос от Telegram.
// 2. Декодирует JSON-данные.
// 3. Создает и настраивает объект TGZ, готовый к работе.
// 4. Автоматически отправляет ответ "ok" и HTTP-код 200, чтобы Telegram знал, что обновление получено.
$tg = TGZ::create($token);

// Дальнейшая логика обработки точно такая же, как и в Long Poll
$text = $tg->getText();

if ($text === '/start') {
    $tg->reply('Привет! Я бот, работающий на TGZ через Webhook.');
}

if ($text === '/info') {
    // Получим больше данных с помощью метода initVars
    $tg->initVars($chat_id, $user_id, $text, $type);
    
    $tg->reply("Тип обновления: {$type}\nID чата: {$chat_id}\nID пользователя: {$user_id}");
}

// Вам не нужно ничего выводить или отправлять "ok" вручную. 
// TGZ::create() уже сделал это в самом начале.

Шаг 2: Установка Webhook

Вам нужно один раз сообщить Telegram, на какой URL отправлять обновления. Самый простой способ — открыть специально сформированную ссылку в браузере.

Замените <TOKEN> на токен вашего бота, а <URL> на полный HTTPS-адрес вашего скрипта.

https://api.telegram.org/bot<TOKEN>/setWebhook?url=<URL>

Пример:

https://api.telegram.org/bot12345:ABC-DEF/setWebhook?url=https://mydomain.com/bots/webhook.php

Если все прошло успешно, вы увидите ответ:

{
    "ok": true,
    "result": true,
    "description": "Webhook was set"
}

Полезные команды для управления Webhook:

• Проверить информацию о Webhook:https://api.telegram.org/bot<TOKEN>/getWebhookInfo
• Удалить Webhook (чтобы вернуться к режиму Long Poll):https://api.telegram.org/bot<TOKEN>/deleteWebhook

Какой способ выбрать?

Критерий	Long Polling	Webhook
Настройка	✅ Просто (нужен только PHP)	❌ Сложно (требуется веб-сервер, домен, SSL)
Режим запуска	Командная строка (CLI)	Веб-сервер (Nginx, Apache)
Рекомендуется для	Разработка, отладка, боты с низкой нагрузкой	Продакшн, боты с высокой нагрузкой
Эффективность	Менее эффективен (постоянные запросы)	✅ Более эффективен (получает данные по факту)
Отклик	Задержка до timeout секунд	✅ Мгновенный

Итог: Начните разработку с Long Polling на вашем локальном компьютере. Когда бот будет готов к запуску для всех, перенесите его на сервер и настройте Webhook для максимальной производительности. Логика обработки обновлений в обоих случаях останется практически идентичной.