README

A Symfony bundle for integrating a framework-agnostic Telegram Bot library. Designed for Symfony 7.4 and 8.x, it enables robust, multi-bot support with flexible provider architecture.

Features

• Seamless integration of a framework-agnostic Telegram Bot library into Symfony
• Supports multiple bots and providers via CompositeBotProvider
• Built-in StaticBotProvider for configuration-based bot definition
• Custom provider support (e.g., database-backed)
• Symfony HttpClient (PSR-18) and nyholm/psr7 (PSR-17) integration
• Webhook controller for Telegram updates
• Automatic handler registration via Symfony service tags
• Symfony 7.4 and 8.x compatibility
• Requires PHP 8.4+

Installation

Install via Composer:

composer require aymericcucherousset/telegram-bot-bundle

Configuration Example

Create config/packages/telegram_bot.yaml:

telegram_bot:
    bots:
        main:
            token: '%env(TELEGRAM_BOT_TOKEN)%'

Create config/routes/telegram_bot_bundle.yaml:

telegram_bot_bundle:
    resource: '@TelegramBotBundle/config/routes.php'

Defining Static Bots

Static bots are defined directly in the configuration file:

# config/packages/telegram_bot.yaml

telegram_bot:
    bots:
        main:
            token: '%env(TELEGRAM_BOT_TOKEN)%'

Creating a Custom DatabaseBotProvider

Implement the BotProviderInterface to fetch bot credentials from a database:

<?php

declare(strict_types=1);

namespace App\Telegram;

use App\Repository\TelegramBotRepository;
use Aymericcucherousset\TelegramBotBundle\Bot\BotProviderInterface;

final class DatabaseBotProvider implements BotProviderInterface
{
    public function __construct(
        private TelegramBotRepository $repository,
    ) {}

    public function supports(string $name): bool
    {
        return null !== $this->repository->findOneBy([
            'name' => $name,
        ]);
    }

    public function getToken(string $name): string
    {
        $bot = $this->repository->findOneBy([
            'name' => $name,
        ]);

        if (!$bot) {
            throw new \RuntimeException(sprintf('Bot "%s" not found.', $name));
        }

        return $bot->getToken();
    }
}

Creating a Handler

Handlers are auto-registered via service tags. Example handler:

<?php

declare(strict_types=1);

namespace App\Telegram\Command;

use Aymericcucherousset\TelegramBot\Attribute\AsTelegramCommand;
use Aymericcucherousset\TelegramBot\Handler\HandlerInterface;
use Aymericcucherousset\TelegramBot\Method\Message\TextMessage;
use Aymericcucherousset\TelegramBot\Update\Update;

#[AsTelegramCommand(name: 'ping', description: 'Replies with pong')]
final class PingCommand implements HandlerInterface
{
    public function handle(Update $update): void
    {
        $message = $update->message;

        if ($message === null) {
            return;
        }

        $textMessage = new TextMessage(
            chatId: $message->chatId,
            text: 'pong 🏓',
        );

        $update->bot->getClient()->send($textMessage);
    }
}

Webhook Configuration Example

Define a route for the webhook controller:

Create config/routes/telegram_bot_bundle.yaml:

telegram_bot_bundle:
    resource: '@TelegramBotBundle/config/routes.php'

Use Telegram Bot in Services

    public function __construct(
        // Inject Bot Manager
        private readonly BotManager $botManager,
    ) {
    }

    public function yourMethod(): void
    {
        // Create your Telegram Method
        $method = new TextMessage(
            text: 'Hello world!',
            chatId: new ChatId(1111111111),
        );

        // Then send the Telegram Method from the bot
        $this->botManager->getClient('main')->send($method);
    }

Architecture Overview

• Bot Providers: Abstracted via BotProviderInterface. Use built-in StaticBotProvider or implement custom providers (e.g., database, API).
• CompositeBotProvider: Aggregates multiple providers for multi-bot support.
• Handlers: Auto-registered via service tags, process Telegram updates.
• Webhook Controller: Receives Telegram webhook updates and dispatches to handlers.
• PSR-18/PSR-17: Uses Symfony HttpClient and nyholm/psr7 for HTTP and message interoperability.

Advanced Usage: Multi-Provider Support

The bundle supports multiple bot providers. Register several providers (static, database, API, etc.) as services tagged with telegram_bot.provider. The CompositeBotProvider aggregates all bots, enabling scalable, multi-bot architectures.

Contributing

Contributions are welcome. Please submit pull requests or open issues for bug reports and feature requests. Follow Symfony and PSR coding standards.

License

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