PHPackages                             aymericcucherousset/telegram-bot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. aymericcucherousset/telegram-bot

ActiveLibrary

aymericcucherousset/telegram-bot
================================

v0.0.1(2mo ago)03[2 PRs](https://github.com/aymericcucherousset/telegram-bot/pulls)1PHPPHP ^8.4CI passing

Since Feb 15Pushed 1mo agoCompare

[ Source](https://github.com/aymericcucherousset/telegram-bot)[ Packagist](https://packagist.org/packages/aymericcucherousset/telegram-bot)[ RSS](/packages/aymericcucherousset-telegram-bot/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (7)Versions (5)Used By (1)

aymericcucherousset/telegram-bot
================================

[](#aymericcucheroussettelegram-bot)

[![PHP Version](https://camo.githubusercontent.com/6e44ad49e5307c87d1393389feb52ab61c99956e2e5f8c77177b2501f1d3d47f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e342d3838393242462e737667)](https://camo.githubusercontent.com/6e44ad49e5307c87d1393389feb52ab61c99956e2e5f8c77177b2501f1d3d47f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e342d3838393242462e737667)[![License](https://camo.githubusercontent.com/1b15d4499c9d6a0dcd635b4feea73e624b56cd8b3cc039d8f19867b87dda4862/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f61796d657269636375636865726f75737365742f74656c656772616d2d626f74)](https://camo.githubusercontent.com/1b15d4499c9d6a0dcd635b4feea73e624b56cd8b3cc039d8f19867b87dda4862/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f61796d657269636375636865726f75737365742f74656c656772616d2d626f74)[![CI](https://github.com/aymericcucherousset/telegram-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/aymericcucherousset/telegram-bot/actions/workflows/ci.yml/badge.svg)

---

Description
-----------

[](#description)

**Telegram Bot** is a modern, Clean Architecture-oriented PHP package for building robust Telegram bots. Designed for PHP 8.4+, it leverages DDD principles, strict typing, and PSR-18 HTTP clients. The package provides a clear Domain/Infrastructure separation, value objects, and extensible message patterns for maintainable, testable, and scalable bot development.

Goals
-----

[](#goals)

- Promote Clean Architecture and DDD for Telegram bots
- Provide a strict, type-safe, and extensible API
- Encapsulate [Telegram API](https://core.telegram.org/bots/api) calls via OutboundMessageInterface
- Support for value objects and inline keyboards
- Easy integration with any PSR-18 HTTP client

Installation
------------

[](#installation)

```
composer require aymericcucherousset/telegram-bot
```

Basic Usage
-----------

[](#basic-usage)

```
use Aymericcucherousset\TelegramBot\Api\HttpTelegramClient;
use Aymericcucherousset\TelegramBot\Handler\HandlerInterface;
use Aymericcucherousset\TelegramBot\Attribute\AsTelegramCommand;
use Aymericcucherousset\TelegramBot\Method\Message\TextMessage;
use Aymericcucherousset\TelegramBot\Keyboard\InlineKeyboardMarkup;
use Aymericcucherousset\TelegramBot\Keyboard\InlineKeyboardButton;
use Aymericcucherousset\TelegramBot\Bot\Bot;
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);
    }
}

// Bot instantiation:
$client = new HttpTelegramClient('TOKEN', $psr18Client); // $psr18Client is your PSR-18 HTTP client
$bot = new Bot($client); // Optionally pass a custom HandlerRegistry as the 2nd argument

// UpdateFactory usage:
use Aymericcucherousset\TelegramBot\Update\UpdateFactory;
$update = UpdateFactory::fromJson($json, $bot); // $json is the incoming update JSON string
```

Example: Inline Keyboard
------------------------

[](#example-inline-keyboard)

```
use Aymericcucherousset\TelegramBot\Method\Message\TextMessage;
use Aymericcucherousset\TelegramBot\Keyboard\InlineKeyboardMarkup;
use Aymericcucherousset\TelegramBot\Keyboard\InlineKeyboardButton;
use Aymericcucherousset\TelegramBot\Value\ChatId;

$keyboard = new InlineKeyboardMarkup([
    [new InlineKeyboardButton('Button 1', callbackData: 'action_1')],
    [new InlineKeyboardButton('Button 2', callbackData: 'action_2')],
]);

$message = new TextMessage(
    new ChatId(123456789),
    'Choose an option:',
    replyMarkup: $keyboard
);
```

Example: CallbackQuery Handling
-------------------------------

[](#example-callbackquery-handling)

```
use Aymericcucherousset\TelegramBot\Handler\HandlerInterface;
use Aymericcucherousset\TelegramBot\Attribute\AsTelegramCallbackQuery;
use Aymericcucherousset\TelegramBot\Method\Message\EditMessageText;
use Aymericcucherousset\TelegramBot\Update\Update;
use Aymericcucherousset\TelegramBot\Value\ParseMode;

#[AsTelegramCallbackQuery(name: 'products', description: 'Replies with the list of products')]
final class ProductsCallbackQuery implements HandlerInterface
{
    public function handle(Update $update): void
    {
        $callbackQuery = $update->callbackQuery;
        if ($callbackQuery === null) {
            return;
        }
        $editMessage = new EditMessageText(
            chatId: $callbackQuery->chatId,
            messageId: $update->message->id,
            text: 'List of products : ...',
            mode: ParseMode::Markdown,
        );
        $update->bot->getClient()->send($editMessage);
    }
}
```

UpdateFactory
-------------

[](#updatefactory)

The `UpdateFactory` is responsible for creating `Update` objects from incoming Telegram JSON updates. It now requires a `Bot` instance as the second argument:

```
use Aymericcucherousset\TelegramBot\Update\UpdateFactory;
use Aymericcucherousset\TelegramBot\Bot\Bot;

$bot = new Bot($client); // $client is your TelegramClientInterface implementation
$update = UpdateFactory::fromJson($json, $bot);
```

Architecture
------------

[](#architecture)

```
src/
├── Api/         # PSR-18 HTTP client, API interfaces
├── Attribute/   # Command/callback attributes
├── Method/     # TelegramMethod interface
│   ├── TelegramMethod.php   # TelegramMethod interface
│   └── Message/             # Message-related methods (SendMessage, EditMessageText, etc.)
├── Bot/         # Bot orchestration
├── Exception/   # Domain & API exceptions
├── Handler/     # Handler interfaces/loaders
├── Keyboard/    # Inline keyboard markup/buttons
├── Loader/      # Attribute handler loader
├── Message/     # OutboundMessageInterface & implementations
├── Registry/    # Handler registries
├── Update/      # Update, Message, CallbackQuery, factories
├── Value/       # Value Objects (ChatId, ParseMode, UserId)

```

```
ASCII Architecture:

   +-------------------+
   |   Domain Layer    |
   |-------------------|
   |  Value Objects    |
   |  OutboundMessage  |
   |  Handlers         |
   +-------------------+
            |
            v
   +------------------------+
   |  Infrastructure Layer  |
   |------------------------|
   |  PSR-18 HTTP Client    |
   |  API Integration       |
   +------------------------+

```

Philosophy
----------

[](#philosophy)

- **Domain-Driven Design**: Core logic and value objects are decoupled from infrastructure.
- **Value Objects**: (ChatId, ParseMode, UserId) ensure type safety and immutability.
- **TelegramMethod**: Encapsulates all outbound API calls for extensibility.
- **Extensible**: Add new message types or handlers without modifying core logic.
- **Strict Types**: All code uses `declare(strict_types=1)`.

Roadmap
-------

[](#roadmap)

- Core message types (SendMessage, EditMessageText, AnswerCallbackQuery, DeleteMessage)
- Inline keyboard support
- Exception handling (ApiException)
- File upload (photo, document, etc.)
- Symfony Bundle
- More update types and handlers

Contributing
------------

[](#contributing)

Contributions are welcome! Please submit pull requests with clear descriptions and tests. Follow PSR-12 and Clean Architecture principles.

License
-------

[](#license)

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

###  Health Score

40

—

FairBetter than 87% of packages

Maintenance95

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

82d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1e5233371c649b785f2b726ec2ec837d143dc7f5c3e801ae2dd0838faaa2fd5d?d=identicon)[aymericcucherousset](/maintainers/aymericcucherousset)

---

Top Contributors

[![aymericcucherousset](https://avatars.githubusercontent.com/u/62072504?v=4)](https://github.com/aymericcucherousset "aymericcucherousset (53 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/aymericcucherousset-telegram-bot/health.svg)

```
[![Health](https://phpackages.com/badges/aymericcucherousset-telegram-bot/health.svg)](https://phpackages.com/packages/aymericcucherousset-telegram-bot)
```

###  Alternatives

[cakephp/cakephp

The CakePHP framework

8.8k18.5M1.6k](/packages/cakephp-cakephp)[aporat/store-receipt-validator

PHP receipt validator for Apple App Store and Amazon Appstore

6503.9M9](/packages/aporat-store-receipt-validator)[opensearch-project/opensearch-php

PHP Client for OpenSearch

15024.3M64](/packages/opensearch-project-opensearch-php)[tempest/framework

The PHP framework that gets out of your way.

2.1k23.1k9](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

81733.7k](/packages/flow-php-flow)[neos/flow

Flow Application Framework

862.0M449](/packages/neos-flow)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)