README

BotGate — это шлюз (прокси) для Telegram Bot API, позволяющий стабильно обращаться к Telegram из России без личных прокси и VPN. Ваше приложение отправляет запрос в BotGate, а он выполняет его к api.telegram.org с зарубежного сервера и возвращает ответ как есть — формат запросов привычный, меняется только адрес. Сервис даёт единый API-ключ для всех ботов, шифрование Telegram Bot Token, приём webhook с автоматическими повторными попытками и статистику в личном кабинете. Подробнее — на bot-gate.ru.

Этот пакет — официальный PHP SDK для BotGate: не зависит от фреймворка, предоставляет типизированный клиент для вызова методов Bot API, проверки подписи вебхуков и разбора входящих обновлений.

Требования

PHP ^8.2
PSR-18 HTTP-клиент (по умолчанию используется Guzzle)

Установка

composer require botgate/sdk

Быстрый старт

use BotGate\Client;

$client = Client::create('ВАШ_API_КЛЮЧ');

$response = $client->bot('public-bot-id')->call('sendMessage', [
    'chat_id' => 123456789,
    'text' => 'Привет из BotGate!',
]);

if ($response->ok) {
    // $response->result — содержимое поля "result" ответа Telegram
}

Client::create() собирает клиент с транспортом по умолчанию (Guzzle + повторные попытки с экспоненциальной задержкой).

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

Для тонкой настройки используйте Config:

use BotGate\Client;
use BotGate\Config;

$config = new Config(
    apiKey: 'ВАШ_API_КЛЮЧ',
    baseUrl: 'https://bot-gate.ru',
    timeout: 30.0,
    maxRetries: 3,
    retryBaseDelayMs: 500,
);

$client = Client::fromConfig($config);

Чтобы подставить собственный транспорт (например, для тестов или особой логики), реализуйте BotGate\Http\HttpClientInterface и передайте его напрямую:

$client = new Client($config, $customHttpClient);

Вызов методов Bot API

$bot = $client->bot('public-bot-id');

// JSON-запрос
$bot->call('sendMessage', ['chat_id' => 1, 'text' => 'hi']);

// Загрузка файлов (multipart/form-data)
use BotGate\Http\MultipartField;

$bot->callMultipart('sendPhoto', [
    new MultipartField('chat_id', '1'),
    MultipartField::file('photo', '/path/to/photo.jpg'),
]);

// Скачивание файла по его file_path
$stream = $bot->downloadFile('photos/file_0.jpg');

Метод getUpdates намеренно заблокирован (бросает BlockedMethodException) — обновления доставляются через вебхук.

Вебхуки

Проверка подписи

Входящие запросы подписываются заголовком X-BotGate-Signature (HMAC-SHA256 от тела запроса):

use BotGate\Webhook\SignatureValidator;

$validator = new SignatureValidator('webhook-секрет');

if (! $validator->isValid($rawBody, $signature)) {
    // 403
}

// либо строгий вариант с исключением
$validator->validate($rawBody, $signature); // InvalidSignatureException

Разбор обновления

use BotGate\DTO\Update;
use BotGate\DTO\UpdateType;

$update = Update::fromJson($rawBody);

$update->updateId;            // int
$update->type();              // UpdateType
$update->is(UpdateType::Message);

$message = $update->message();        // array|null
$callback = $update->callbackQuery(); // array|null

Ответ

При успехе call() и callMultipart() возвращают BotGate\DTO\Response. При ошибке SDK выбрасывает исключение:

$response->ok;          // bool
$response->result;      // mixed
$response->description; // ?string
$response->errorCode;   // ?int
$response->raw;         // array — исходный ответ целиком

Обработка ошибок

Все исключения SDK реализуют BotGate\Exception\BotGateExceptionInterface. Начиная с SDK 1.1.0 ошибки Telegram внутри HTTP 400 доступны как TelegramException; HTTP-статус и код Telegram можно прочитать отдельно.

Источник	Исключение	Время ожидания
Лимит BotGate, HTTP 429	`RateLimitException`	`retryAfter()` из числового заголовка `Retry-After`
Ошибка Telegram, HTTP 400	`TelegramException`	`retryAfter()` из `parameters.retry_after`, если передано корректное целое число

retryAfter() возвращает секунды или null, если время неизвестно. Для Telegram проверяйте telegramErrorCode() === 429 перед планированием повтора:

use BotGate\Exception\BotGateExceptionInterface;
use BotGate\Exception\RateLimitException;
use BotGate\Exception\TelegramException;
use BotGate\Exception\UnauthorizedException;

try {
    $client->bot('id')->call('sendMessage', $params);
} catch (RateLimitException $e) {
    $wait = $e->retryAfter();
    // Лимит BotGate. При известном $wait отложите задание в очереди.
} catch (TelegramException $e) {
    if ($e->telegramErrorCode() === 429) {
        $wait = $e->retryAfter();
        // Лимит Telegram. При известном $wait отложите задание в очереди.
    } else {
        // Исправьте запрос или права бота с учётом telegramErrorCode().
    }
} catch (UnauthorizedException $e) {
    // 401 — неверный API-ключ
} catch (BotGateExceptionInterface $e) {
    // любая другая ошибка SDK
}

TelegramException::parameters() сохраняет параметры Telegram, включая migrate_to_chat_id. httpStatusCode() и getCode() содержат HTTP-статус BotGate, а не error_code Telegram. Существующий catch (BotGateException $e) продолжает ловить TelegramException.

Telegram 429 внутри HTTP 400 автоматически не повторяется. Стандартный транспорт по-прежнему повторяет HTTP 429, 502, 503 и 504 до maxRetries раз; исключение возвращается после завершения этих попыток. Если повторами управляет ваша очередь, задайте maxRetries: 0. Не повторяйте отправку с неизвестным результатом без проверки: это может создать дубликат.

botgate / sdk

Package info

Security

Statistics