PHPackages shanginn/telegram-bot-api-framework - 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. [Framework](/categories/framework) 4. / 5. shanginn/telegram-bot-api-framework ActiveLibrary[Framework](/categories/framework) shanginn/telegram-bot-api-framework =================================== Async, strictly typed Telegram bot framework for PHP 8.4 6.0.3(4w ago)2105MITPHPPHP ^8.4CI passing Since Sep 3Pushed 3mo ago1 watchersCompare [ Source](https://github.com/phenogram/framework)[ Packagist](https://packagist.org/packages/shanginn/telegram-bot-api-framework)[ Docs](https://github.com/phenogram/framework)[ RSS](/packages/shanginn-telegram-bot-api-framework/feed)WikiDiscussions master Synced 2w ago READMEChangelog (10)Dependencies (39)Versions (39)Used By (0) [English](README.en.md) | **Русский** Phenogram Framework =================== [](#phenogram-framework) [![CI](https://github.com/phenogram/framework/actions/workflows/ci.yaml/badge.svg)](https://github.com/phenogram/framework/actions/workflows/ci.yaml)[![PHP 8.4](https://camo.githubusercontent.com/57027d373b7f5a7948c357666d6dd77ce090b410c617c924030ced42e76ede6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342d3737374242342e737667)](https://www.php.net/releases/8.4/en.php)[![Лицензия: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](LICENSE) Типизированный прикладной фреймворк для Telegram-ботов на PHP 8.4. Phenogram Framework добавляет long polling, маршруты, middleware, параллельные обработчики, журналирование и загрузку файлов к пакету [Phenogram Bindings](https://github.com/phenogram/bindings). Warning Версия 6 находится в активной разработке. Оцените пакет перед использованием в production. Совместимость ------------- [](#совместимость) FrameworkPHPBindingsМодель Telegram Bot API6.0.x`^8.4``^7`9.6Framework 6 требует `phenogram/bindings:^7`. Bindings 7 содержит сгенерированную модель Telegram Bot API 9.6. Это утверждение не означает поддержку более новых основных версий Bindings или более новых версий Telegram Bot API. Не устанавливайте Bindings 8 или 9 вместе с Framework 6, пока новый выпуск Framework явно не объявит такую поддержку. Назначение пакета ----------------- [](#назначение-пакета) Используйте этот пакет, если вашему Telegram-боту нужен прикладной слой. Пакет предоставляет: - HTTP-клиент на Amp для запросов к Telegram Bot API; - long polling через `getUpdates`; - маршруты и условия маршрутов; - middleware и группы маршрутов; - параллельные обработчики обновлений на Amp futures; - журналирование через PSR-3; - загрузку локальных файлов, потоков и файлов из памяти. Используйте [Phenogram Bindings](https://github.com/phenogram/bindings) без этого пакета, если вам нужны только типизированные методы API, типы Telegram, сериализация и десериализация. Пакет не предоставляет webhook-сервер, хранилище данных, очередь или платформу развёртывания. Требования ---------- [](#требования) - PHP `^8.4` (PHP 8.4 или более новый выпуск PHP 8); - Composer 2; - токен Telegram-бота для работы с Telegram. Для офлайн-примеров и стандартного набора тестов токен не нужен. Установка --------- [](#установка) ``` composer require phenogram/framework ``` Примеры ------- [](#примеры) Репозиторий содержит полные файлы примеров. Офлайн-тесты загружают эти файлы напрямую. Тесты используют клиент Telegram в памяти и не обращаются к сети. Для команд ниже нужен клон репозитория. Подготовьте клон перед запуском: ``` git clone https://github.com/phenogram/framework.git cd framework composer install composer tools:install ``` Запустите все тесты примеров: ``` composer test:examples ``` ### Эхо-бот [](#эхо-бот) [`examples/echo-bot.php`](examples/echo-bot.php) создаёт бота, который повторяет каждое текстовое сообщение. Условие маршрута отклоняет обновления без текста. После этого обработчик может безопасно прочитать сообщение и идентификатор чата. Запустите бота: Токен ниже является намеренно недействительным примером для документации. ``` export TELEGRAM_BOT_TOKEN='7245389610:AAFHBDYMKpWxYu5JrSnTlQRD9bvPz0OgHkLf' php examples/echo-bot.php ``` Команда обращается к Telegram и требует доступ к сети. Остановите бота с помощью `Ctrl+C`. ### Группа маршрутов и middleware [](#группа-маршрутов-и-middleware) [`examples/route-group.php`](examples/route-group.php) добавляет маршрут `/ping` для одного пользователя Telegram. Условие маршрута выбирает текстовые сообщения `/ping`. `IsUserMiddleware` пропускает только настроенного пользователя. Обработчик отправляет `pong`. Вызовите `addPingRoute($bot, $allowedUserId)` до вызова `$bot->run()`. Оставляйте каждую цепочку `RouteConfigurator` в одном выражении. Не сохраняйте незавершённый конфигуратор. Фреймворк регистрирует маршрут, когда освобождает конфигуратор. ### Загрузка файлов [](#загрузка-файлов) [`examples/send-files.php`](examples/send-files.php) отправляет один файл в трёх формах. Входные данныеКлассНазначениеЛокальный путь`LocalFile`HTTP-клиент открывает файл по указанному пути.Читаемый поток`ReadableStreamFile`Клиент отправляет данные из читаемого потока Amp.Строка в памяти`BufferedFile`Клиент отправляет уже загруженные в память данные.Передайте строку напрямую в соответствующий метод Bindings API, если у вас есть Telegram file ID или публичный URL. Запустите пример с реальной отправкой: ``` export TELEGRAM_BOT_TOKEN='ваш-токен' export TELEGRAM_CHAT_ID='123456789' php examples/send-files.php ``` Команда отправляет три копии этого README в выбранный чат. Основной API ------------ [](#основной-api) ### Создание бота [](#создание-бота) `TelegramBot` принимает токен, необязательную реализацию `ApiInterface` и необязательный logger PSR-3. Публичное свойство `$bot->api` имеет тип `ApiInterface`. Для тестов или собственного транспорта можно передать совместимую реализацию API. Если реализация API не передана, фреймворк создаёт: - `TelegramBotApiClient` как HTTP-транспорт; - `Phenogram\Bindings\Serializer` как сериализатор; - `Phenogram\Bindings\Api` как типизированный API. ### Добавление обработчиков [](#добавление-обработчиков) Используйте `$bot->addHandler(...)` для одного маршрута. Добавьте `->supports(...)`, если обработчик должен принимать только определённые обновления. Используйте `$bot->defineHandlers(...)`, если нужен `Router`, группы маршрутов или общие middleware. Обработчик может принимать следующие параметры: 1. `UpdateInterface $update` 2. `TelegramBot $bot` Обработчик также может принимать меньше параметров. Фреймворк запускает все подходящие обработчики как Amp futures. ### Обработка одного обновления [](#обработка-одного-обновления) Используйте `$bot->handleUpdate($update)`, если обновление передаёт другой компонент. Метод возвращает futures обработчиков. Дождитесь их завершения, если вызывающему коду нужен результат обработки. Этот метод подходит для тестов и отдельного webhook-адаптера. ### Запуск long polling [](#запуск-long-polling) Вызовите `$bot->run()`, чтобы запустить long polling через `getUpdates`. Метод блокирует выполнение до остановки бота. Вызовите `$bot->stop()` из кода приложения, когда нужно остановить цикл. Аргумент `allowedUpdates` принимает значения `UpdateType`. Значение `limit` должно соответствовать ограничениям Telegram Bot API. ### Обработка ошибок [](#обработка-ошибок) Фреймворк отправляет записи в доступный logger PSR-3. Если механизм обнаружения не находит logger, фреймворк использует `EchoLogger`. Настройте `$bot->errorHandler`, если приложению нужна собственная обработка ошибок. Callback получает ошибку и экземпляр бота. Не записывайте токен бота в журнал. Считайте каждый токен секретом. Тесты и проверки качества ------------------------- [](#тесты-и-проверки-качества) Установите зависимости проекта и изолированный инструмент проверки стиля: ``` composer install composer tools:install ``` Запустите те же офлайн-проверки, которые выполняет CI: ``` composer check ``` Команда проверяет метаданные Composer, стиль кода и запускает офлайн-набор PHPUnit. Можно запустить одну проверку: ``` composer test composer test:examples composer style composer fix ``` Стандартная конфигурация PHPUnit: - не загружает `.env`; - не использует учётные данные Telegram; - не делает сетевые запросы; - исключает `tests/Integration`. Интеграционные тесты с Telegram ------------------------------- [](#интеграционные-тесты-с-telegram) Тесты с реальным Telegram отделены от стандартного набора. Они обращаются к Telegram и могут отправлять файлы в настоящий чат. Укажите явное разрешение и нужные учётные данные: ``` export RUN_TELEGRAM_INTEGRATION=1 export TELEGRAM_BOT_TOKEN='ваш-токен' export TEST_CHAT_ID='123456789' composer test:integration ``` Интеграционный bootstrap также может прочитать эти значения из локального файла `.env`. Репозиторий игнорирует `.env`. Значения из окружения процесса имеют приоритет над значениями из `.env`. Используйте отдельного тестового бота и отдельный тестовый чат. Не запускайте live-тесты в CI с production-учётными данными. Безопасность ------------ [](#безопасность) - Храните токен бота вне системы контроля версий. - Используйте переменные окружения или хранилище секретов. - Сразу замените токен, если он появился в журнале, коммите, issue или чате. - Проверяйте зависимости перед каждым выпуском. Стиль документации ------------------ [](#стиль-документации) Английская документация использует контролируемый английский в стиле ASD-STE100. - Используйте короткие предложения. - Давайте одну инструкцию в каждом предложении. - Используйте один термин для одного значения. - Расшифруйте сокращение перед первым использованием. - По возможности используйте активный залог. Участие в разработке -------------------- [](#участие-в-разработке) Откройте issue перед большим изменением. Делайте изменения небольшими. Добавляйте офлайн-тест для каждого изменения поведения. Обновляйте оба файла README при изменении публичного поведения. Не добавляйте новую основную версию Bindings без проверки совместимости. Лицензия -------- [](#лицензия) Phenogram Framework доступен по [лицензии MIT](LICENSE). ### Health Score 47 — FairBetter than 93% of packages Maintenance86 Actively maintained with recent releases Popularity13 Limited adoption so far Community7 Small or concentrated contributor base Maturity70 Established project with proven stability Bus Factor1 Top contributor holds 100% 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 Every ~19 days Recently: every ~42 days Total 36 Last Release 28d ago Major Versions 2.7.1 → 3.0.02024-10-20 3.1.1 → 4.0.02024-12-01 4.1.0 → 5.0.02024-12-22 5.2.0 → v6.x-dev2025-10-04 5.4.0 → 6.0.02026-04-29 PHP version history (2 changes)1.0.0PHP ^8.3 4.0.0PHP ^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/311e425711f60c09486c23252696fbe4dfa77e9b0dd5517bc89b288ac2f58655?d=identicon)[shanginn](/maintainers/shanginn) --- Top Contributors [![shanginn](https://avatars.githubusercontent.com/u/3357943?v=4)](https://github.com/shanginn "shanginn (91 commits)") --- Tags phpasyncframeworkbottelegramtelegram bottelegram bot apitype-safe ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/shanginn-telegram-bot-api-framework/health.svg) ``` [![Health](https://phpackages.com/badges/shanginn-telegram-bot-api-framework/health.svg)](https://phpackages.com/packages/shanginn-telegram-bot-api-framework) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.3k37.6k21](/packages/tempest-framework)[symfony/symfony The Symfony PHP framework 31.4k87.4M2.2k](/packages/symfony-symfony)[laravel/framework The Laravel Framework. 34.9k556.2M21.4k](/packages/laravel-framework)[cakephp/cakephp The CakePHP framework 8.9k20.0M1.9k](/packages/cakephp-cakephp)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6943.5M449](/packages/drupal-core-recommended)[danog/madelineproto Async PHP client API for the telegram MTProto protocol. 3.5k920.5k24](/packages/danog-madelineproto) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)