xbot-my/telegram-sdk

Telegram Bot PHP SDK

1.0.1 2025-08-31 12:33 UTC

Requires

• php: ^8.3
• ext-json: *
• guzzlehttp/guzzle: ^7.10
• guzzlehttp/psr7: ^2.8
• psr/http-message: ^1.0 || ^2.0

Requires (Dev)

• larastan/larastan: ^3.0
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^9.0.0 || ^10.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• xbot

README

一个易于使用的 PHP Telegram Bot API SDK，提供高性能客户端、语义化端点和完善的异常处理机制，并支持 Laravel 集成。

特性

• 开箱即用
• 异常捕获
• 链式调用
• 响应转换

安装

composer require xbot-my/telegram-sdk

Laravel

php artisan vendor:publish --provider="XBot\\Telegram\\Providers\\TelegramServiceProvider"

快速开始

use XBot\\Telegram\\Bot;

$bot = Bot::token('YOUR_BOT_TOKEN');

$me  = $bot->getMe()->toArray();
$msg = $bot->sendMessage(123456789, 'Hello')->toArray();
$bot->setWebhook('https://example.com/telegram/webhook');

Webhook 与更新处理

• 在 .env 设置 TELEGRAM_WEBHOOK_SECRET，可选 TELEGRAM_WEBHOOK_ROUTE_PREFIX。
• ServiceProvider 注册默认路由与中间件，校验请求头 X-Telegram-Bot-Api-Secret-Token。
• 实现 UpdateHandler 或继承 BaseUpdateHandler：

class StartHandler extends BaseUpdateHandler {
    protected function onMessage(array $u): void {
        if ($this->text($u) === '/start') $this->replyText($u, 'Welcome!');
    }
}

• 命令路由可继承 CommandRouter，如 /start → onStart，/help foo → onHelp。

示例

// WebApp
$bot->answerWebAppQuery($queryId, [...]);
// Boosts
$bot->getUserChatBoosts($chatId, $userId);
// Stars
$bot->refundStarPayment($userId, $chargeId);
// Business
$bot->readBusinessMessage($chatId, $messageId);

Telegram Bot API 9.2 新参数

• direct_messages_topic_id：发送至频道话题
• suggested_post_parameters：建议帖子
• reply_parameters.checklist_task_id：回复清单任务

$bot->sendMessage($chatId, 'Hello', ['direct_messages_topic_id' => 1234]);

日志

• 环境变量控制：

  • TELEGRAM_LOG_ENABLED
  • TELEGRAM_LOG_SUPPRESS_INFO
  • TELEGRAM_LOG_CHANNEL

• 事件：telegram.request、telegram.response、telegram.retry 等