TGram PHP

Telegram Bot API SDK for PHP.

A lightweight PHP SDK for building Telegram bots with a simple, expressive API and minimal dependencies. Covers the Telegram Bot API (v10.3) with first-class entities and developer-friendly tooling:

• Entity system — every API response is mapped to an object with dynamic properties: $message->from->first_name.
• Attribute-driven commands & callbacks — #[Command('/start')], #[Callback('action')] with argument parsing.
• All update types — commands, callbacks, handlers, conversations and a middleware pipeline.
• Rich messages (Bot API 10.3 format) — Text, RichMessage and Block builders for beautiful messages.
• Keyboard factory — fluent inline & reply keyboards (Keyboard::inline(), Keyboard::reply()).
• Webhook security — X-Telegram-Bot-Api-Secret-Token validation.
• Built-in CLI — install, scaffold and manage your bot from the terminal.

Note

Before you start creating code, you must have created your bot in Telegram. Here's how to do it.

Requirements

• PHP >= 8.5

Installation

composer require mk4u/tgram

Quick start

1. Create config.php with your bot token:

return [
    'token'      => '110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw',
    'secret'     => 'your_secret_token_here',
    'admins'     => [123456789, 985632147],
    'parse_mode' => 'HTML',
    'abs_path'   => __DIR__,
];

2. Create your entry point (index.php):

require_once 'vendor/autoload.php';

use Mk4U\TGram\Bot;

$bot = new Bot();
$bot->run();

3. Define a command in bot/Commands/Start.php:

namespace Bot\Commands;

use Mk4U\TGram\Core\Actions\Commands;
use Mk4U\TGram\Attributes\Command;

#[Command('/start')]
class Start extends Commands
{
    public function execute(): void
    {
        $this->reply('Hey there! Welcome to our bot!');
    }

    public static function description(): string
    {
        return 'Start Command to get you started';
    }
}

4. Register your commands:

php vendor/bin/tgram register

5. Choose how your bot receives updates:

   • Webhook (recommended for production — requires a public HTTPS URL):

     php vendor/bin/tgram hook:set https://your-domain.com/index.php

   • Long polling (no public URL needed — runs forever in the terminal):

     php vendor/bin/tgram poll

Documentation

• Installation and configuration
• Command line interface
• Available methods
• Command system
• Callbacks
• Handler system
• Conversation flow
• Keyboards
• Message format
• Events logger
• Middlewares
• Rich messages

License

MIT