README

English | Русский

Phenogram Framework

Типизированный прикладной фреймворк для Telegram-ботов на PHP 8.4.

Phenogram Framework добавляет long polling, маршруты, middleware, параллельные обработчики, журналирование и загрузку файлов к пакету Phenogram Bindings.

Warning

Версия 6 находится в активной разработке. Оцените пакет перед использованием в production.

Совместимость

Framework	PHP	Bindings	Модель Telegram Bot API
6.0.x	`^8.4`	`^7`	9.6

Framework 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 без этого пакета, если вам нужны только типизированные методы 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 создаёт бота, который повторяет каждое текстовое сообщение.

Условие маршрута отклоняет обновления без текста. После этого обработчик может безопасно прочитать сообщение и идентификатор чата.

Запустите бота:

Токен ниже является намеренно недействительным примером для документации.

export TELEGRAM_BOT_TOKEN='7245389610:AAFHBDYMKpWxYu5JrSnTlQRD9bvPz0OgHkLf'
php examples/echo-bot.php

Команда обращается к Telegram и требует доступ к сети. Остановите бота с помощью Ctrl+C.

Группа маршрутов и middleware

examples/route-group.php добавляет маршрут /ping для одного пользователя Telegram.

Условие маршрута выбирает текстовые сообщения /ping. IsUserMiddleware пропускает только настроенного пользователя. Обработчик отправляет pong.

Вызовите addPingRoute($bot, $allowedUserId) до вызова $bot->run().

Оставляйте каждую цепочку RouteConfigurator в одном выражении. Не сохраняйте незавершённый конфигуратор. Фреймворк регистрирует маршрут, когда освобождает конфигуратор.

Загрузка файлов

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

Создание бота

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.

Обработчик может принимать следующие параметры:

UpdateInterface $update
TelegramBot $bot

Обработчик также может принимать меньше параметров. Фреймворк запускает все подходящие обработчики как Amp futures.

Обработка одного обновления

Используйте $bot->handleUpdate($update), если обновление передаёт другой компонент. Метод возвращает futures обработчиков. Дождитесь их завершения, если вызывающему коду нужен результат обработки.

Этот метод подходит для тестов и отдельного webhook-адаптера.

Запуск 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 и могут отправлять файлы в настоящий чат.

Укажите явное разрешение и нужные учётные данные:

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.

phenogram / framework

Maintainers

Package info

Statistics

Security