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:

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

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

Все исключения SDK реализуют BotGate\Exception\BotGateExceptionInterface, поэтому их можно ловить одним блоком:

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

try {
    $client->bot('id')->call('sendMessage', $params);
} catch (RateLimitException $e) {
    // 429 — превышен лимит
} catch (UnauthorizedException $e) {
    // 401 — неверный API-ключ
} catch (BotGateExceptionInterface $e) {
    // любая другая ошибка SDK
}

Лицензия

MIT © BotGate