README

English | 中文

A Symfony bundle for managing Telegram bots, providing comprehensive bot management capabilities including:

Bot creation, editing, and management
Webhook message reception
Auto-reply rule management
Message processing and sending
Command handling system

Features
Installation
Quick Start
Auto-Reply Rules
Command Handling
Event System
API
Advanced Usage
License

Features

🤖 Bot Management

Create and manage multiple Telegram bots
Set up webhook URLs automatically
Bot validation and status tracking
Comprehensive bot configuration options

📨 Message Processing

Receive and process webhook messages
Support for all Telegram message types
Message persistence and tracking
Real-time message handling

🎯 Auto-Reply System

Rule-based automatic replies
Exact and fuzzy text matching
Priority-based rule processing
HTML-formatted response support

⚡ Command System

Extensible command handling framework
Custom command handlers
Argument parsing and validation
Built-in system commands

📊 Analytics & Logging

Command execution logging
Message tracking and statistics
User interaction analytics
System monitoring capabilities

Installation

Requirements

PHP 8.1 or higher
ext-json
Symfony 7.3 or higher
Doctrine ORM 3.0+
Doctrine DBAL 4.0+
EasyAdmin Bundle 4+

Install via Composer

composer require tourze/telegram-bot-bundle

Core Dependencies

doctrine/orm: ^3.0
doctrine/dbal: ^4.0
doctrine/doctrine-bundle: ^2.13
symfony/framework-bundle: ^7.3
symfony/http-client-contracts: ^3.6
easycorp/easyadmin-bundle: ^4
Plus additional Tourze bundles for enhanced functionality

Quick Start

1. Bundle Registration

return [
    // ... other bundles
    TelegramBotBundle\TelegramBotBundle::class => ['all' => true],
];

2. Basic Configuration

The bundle works out-of-the-box without additional configuration files. The webhook endpoint is automatically available at:

POST /telegram/webhook/{bot-id}

For advanced configuration, you can customize services in your config/services.yaml if needed.

3. Usage

Run database migrations to create required tables:

bin/console doctrine:migrations:migrate

Access the EasyAdmin interface to manage bots:
- Bots: /admin?crudAction=index&crudControllerFqcn=TelegramBotBundle\Controller\Admin\TelegramBotCrudController
- Auto-Reply Rules: /admin?crudAction=index&crudControllerFqcn=TelegramBotBundle\Controller\Admin\AutoReplyRuleCrudController
- Bot Commands: /admin?crudAction=index&crudControllerFqcn=TelegramBotBundle\Controller\Admin\BotCommandCrudController
Set up webhook URLs using the console command:

# Set webhook for a bot
bin/console telegram:set-webhook <bot-id> <base-url>

# Example:
bin/console telegram:set-webhook 123 https://your-domain.com
# This generates: https://your-domain.com/telegram/webhook/123

Auto-Reply Rules

Create intelligent auto-reply rules through the admin interface:

Exact Matching: Messages must match the keyword exactly
Fuzzy Matching: Messages containing the keyword will trigger replies
Priority System: Higher priority rules (larger numbers) are processed first
HTML Support: Reply content supports HTML formatting
Per-Bot Rules: Each bot can have its own set of rules

Command Handling

The bundle provides a command handling system that allows easy addition of new command handlers:

Create a command handler class:

use TelegramBotBundle\Handler\CommandHandlerInterface;
use TelegramBotBundle\Entity\TelegramBot;
use TelegramBotBundle\Entity\Embeddable\TelegramMessage;
use TelegramBotBundle\Service\TelegramBotService;

class YourCommandHandler implements CommandHandlerInterface
{
    public function __construct(
        private readonly TelegramBotService $botService,
    ) {
    }

    public function handle(TelegramBot $bot, string $command, array $args, TelegramMessage $message): void
    {
        // Handle your command logic here
        $response = "Your reply message";
        $this->botService->sendMessage($bot, (string) $message->getChat()?->getId(), $response);
    }
}

Command handlers will be automatically registered and handle corresponding commands

Event System

The bundle uses an event system to handle Webhook messages. You can create your own EventSubscriber to handle messages:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use TelegramBotBundle\Event\TelegramUpdateEvent;

class YourSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            TelegramUpdateEvent::class => ['onTelegramUpdate', -10], // lower priority than auto-reply
        ];
    }

    public function onTelegramUpdate(TelegramUpdateEvent $event): void
    {
        $update = $event->getUpdate();
        $bot = $event->getBot();

        // Handle message...
    }
}

API

Sending Messages

use TelegramBotBundle\Service\TelegramBotService;
use TelegramBotBundle\Repository\TelegramBotRepository;

class YourService
{
    public function __construct(
        private readonly TelegramBotService $botService,
        private readonly TelegramBotRepository $botRepository,
    ) {
    }

    public function sendMessage(string $botId, string $chatId, string $message): void
    {
        $bot = $this->botRepository->find($botId);
        if ($bot) {
            $this->botService->sendMessage($bot, $chatId, $message);
        }
    }
}

Advanced Usage

Database Schema

The bundle creates several tables for managing bots and tracking activity:

tg_bot: Bot configuration (name, token, webhook URL)
tg_auto_reply_rule: Auto-reply rules with priority and matching options
telegram_bot_command: Custom command definitions
telegram_update: All received Telegram updates (with Snowflake IDs)
command_log: Command execution audit trail

Event-Driven Architecture

Monitor bot activity by subscribing to events:

Custom Message Handlers

Create sophisticated message processing by implementing custom handlers:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use TelegramBotBundle\Event\TelegramUpdateEvent;
use TelegramBotBundle\Event\TelegramCommandEvent;

class CustomBotSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            TelegramUpdateEvent::class => ['onTelegramUpdate', -10],
            TelegramCommandEvent::class => ['onTelegramCommand', 0],
        ];
    }

    public function onTelegramUpdate(TelegramUpdateEvent $event): void
    {
        $update = $event->getUpdate();
        $bot = $event->getBot();
        
        // Handle all types of updates (messages, edits, etc.)
        if ($messageText = $event->getMessageText()) {
            // Process text messages
        }
    }
    
    public function onTelegramCommand(TelegramCommandEvent $event): void
    {
        $command = $event->getCommand();
        $args = $event->getArgs();
        
        // Handle specific command executions
    }
}

Custom Command Handlers

Implement the CommandHandlerInterface to create custom commands:

use TelegramBotBundle\Handler\CommandHandlerInterface;
use TelegramBotBundle\Entity\TelegramBot;
use TelegramBotBundle\Entity\Embeddable\TelegramMessage;
use TelegramBotBundle\Service\TelegramBotService;

class WeatherCommandHandler implements CommandHandlerInterface
{
    public function __construct(
        private readonly TelegramBotService $botService,
    ) {
    }

    public function handle(TelegramBot $bot, string $command, array $args, TelegramMessage $message): void
    {
        $location = $args[0] ?? 'Unknown';
        $chatId = (string) $message->getChat()?->getId();
        
        $weatherInfo = $this->fetchWeatherData($location);
        $this->botService->sendMessage($bot, $chatId, $weatherInfo);
    }
    
    private function fetchWeatherData(string $location): string
    {
        // Implement your weather API integration
        return "Weather in {$location}: Sunny, 24°C";
    }
}

Contributing

We welcome contributions to improve this bundle! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes and add tests
Ensure all tests pass (./vendor/bin/phpunit packages/telegram-bot-bundle/tests)
Run static analysis (php -d memory_limit=2G ./vendor/bin/phpstan analyse packages/telegram-bot-bundle)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Run tests
./vendor/bin/phpunit packages/telegram-bot-bundle/tests

# Run static analysis  
php -d memory_limit=2G ./vendor/bin/phpstan analyse packages/telegram-bot-bundle

# Check package integrity
bin/console app:check-packages telegram-bot-bundle -o -f

Changelog

Latest Changes

Enhanced test coverage with comprehensive integration tests
Improved PHPStan compliance and type safety
Added support for all Telegram message types
Implemented robust command parsing and logging
Enhanced EasyAdmin integration for better management

Version History

v0.1.x: Core bot management and webhook handling
v0.2.x: Auto-reply system and command framework
v0.3.x: Enhanced logging and event system
Current: Full-featured bot development platform

License

This bundle is licensed under the MIT License. See the LICENSE file for details.

tourze / telegram-bot-bundle

Maintainers

Details