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

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

Способ 1: Long Polling

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

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

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

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

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

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

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

<?php
require_once __DIR__ . '/vendor/autoload.php'; // Убедитесь, что подключили автозагрузчик Composer
use ZenithGram\ZenithGram\LongPoll;
use ZenithGram\ZenithGram\Bot;
use ZenithGram\ZenithGram\ZG;

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

// Создаём простые команды
$bot->onStart()->text('Привет! Я бот, работающий на ZG через Long Polling.');
$bot->onBotCommand('/time')->text('Точное время: ' . date('H:i:s'));

// Добавляем вывод в консоль, чтобы знать, что всё запушено
echo "Long Poll запущен... Нажмите Ctrl+C для остановки.";
// Запускаем прослушивание. Вся магия происходит внутри анонимной функции.
$lp->listen(function (ZG $tg) use ($bot) {
    // Для каждого обновления библиотека автоматически создает и передает вам 
    // полностью готовый к работе объект ZG.

    // Прокидываем основной класс в конструктор и запускаем
    $bot->zg($tg)->run();

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

Запуск

1. Сохраните код.
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_once __DIR__ . '/vendor/autoload.php'; // Подключаем автозагрузчик
use ZenithGram\ZenithGram\ZG;
use ZenithGram\ZenithGram\Bot;

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

// Дальнейшая логика обработки точно такая же, как и в Long Poll
$bot->onStart()->text('Привет! Я бот, работающий на ZenithGram через Webhook.');
$bot->onBotCommand('/time')->text('Точное время: ' . date('H:i:s'));

// Запускаем бота
$bot->run();
// Вам не нужно ничего выводить или отправлять "ok" вручную. 
// ZG::create() уже сделал это в самом начале.

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

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

Замените ТОКЕН_БОТА на токен вашего бота, а <URL> на полный HTTPS-адрес вашего скрипта.

https://api.telegram.org/bot<ТОКЕН_БОТА>/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<ТОКЕН_БОТА>/getWebhookInfo
• Удалить Webhook (чтобы вернуться к режиму Long Poll):https://api.telegram.org/bot<ТОКЕН_БОТА>/deleteWebhook

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

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

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