README

Русский | English

Phenogram Bindings

Строго типизированные PHP-привязки к Telegram Bot API без сторонних зависимостей.

Пакет предоставляет типизированные методы API, сериализацию запросов, десериализацию ответов и заменяемые фабрики объектов. Пакет не выбирает HTTP-клиент. Пакет не запускает цикл обработки бота.

Используйте Phenogram Framework, если нужны маршруты, middleware и обработка обновлений.

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

Компонент	Поддерживаемая версия
Пакет	`9.x`
Telegram Bot API	`10.2`
PHP	`^8.4`
Сторонние пакеты в рабочей среде	Нет

Код использует property hooks из PHP. Поэтому требуется PHP 8.4.

Установка

composer require phenogram/bindings

Быстрый старт

Используйте Serializer, чтобы создать данные для Telegram:

<?php

declare(strict_types=1);

use Phenogram\Bindings\Serializer;
use Phenogram\Bindings\Types\InlineKeyboardButton;
use Phenogram\Bindings\Types\InlineKeyboardMarkup;

require __DIR__ . '/vendor/autoload.php';

$payload = (new Serializer())->serialize([
    'chatId' => 42,
    'text' => 'Выберите действие.',
    'replyMarkup' => new InlineKeyboardMarkup(
        inlineKeyboard: [[
            new InlineKeyboardButton(
                text: 'Открыть документацию',
                url: 'https://core.telegram.org/bots/api',
            ),
        ]],
    ),
]);

Сериализатор заменяет chatId на chat_id. Он преобразует типизированные объекты во вложенные массивы. Он удаляет значения null.

Используйте Api, когда в приложении есть реализация ClientInterface. Клиент отправляет HTTP-запрос. Клиент возвращает полную оболочку ответа Telegram.

Для команд с примерами ниже нужен клон репозитория и команда composer install. Запустите проверенный пример API:

php examples/03-call-api.php

Запустите проверенные примеры без сети:

for file in examples/[0-9][0-9]-*.php; do php "$file"; done

Состав пакета

Часть	Назначение
`ApiInterface`	Определяет все поддерживаемые методы Telegram.
`Api`	Сериализует запросы и создаёт типизированные результаты.
`ClientInterface`	Подключает привязки к HTTP-транспорту.
`SerializerInterface`	Определяет сериализацию и десериализацию.
`Serializer`	Преобразует данные Telegram в PHP-типы.
`FactoryInterface`	Определяет конструкторы всех типов результата.
`Factory`	Создаёт стандартные объекты результата.
`Types`	Содержит конкретные типы и их интерфейсы.
`Factories`	Создаёт тестовые фикстуры через Faker.

Тестовым фабрикам нужен пакет fakerphp/faker. Приложение не получает этот пакет из зависимостей разработки библиотеки. Установите его в приложение, которое использует фабрики:

composer require --dev fakerphp/faker

Документация

Руководство	Содержание
Начало работы	Назначение, установка и первое использование
Архитектура	Поток запроса, точки расширения и структура пакета
Интеграция клиента	Контракт транспорта, файлы, ошибки и безопасность
Тестирование	Примеры без сети, фикстуры и рабочие тесты
Исполняемые примеры	Шесть скриптов, которые работают без токена бота

Официальная документация Telegram Bot API является главным источником информации о поведении Telegram. Используйте ApiInterface как локальный источник поддерживаемых сигнатур PHP-методов.

Обработка ошибок

Api выбрасывает ResponseException, когда ok равно false или result равно null. Исключение содержит полный объект ResponseInterface.

php examples/06-handle-api-error.php

Разработка

Установите зависимости пакета для разработки:

composer install
composer tools:install

Репозиторий не хранит корневой файл composer.lock. Composer разрешает корневые зависимости для разработки по ограничениям версий. Отдельные проекты инструментов хранят lock-файлы для PHPStan и PHP CS Fixer.

Запустите тесты без сети:

vendor/bin/phpunit

Запустите статический анализ:

composer phpstan

Запустите все проверки репозитория:

composer check

Прочитайте CONTRIBUTING.ru.md перед отправкой изменений. Сообщайте о проблемах безопасности по правилам из SECURITY.md. Используйте SUPPORT.md для запросов поддержки.

Лицензия

Phenogram Bindings доступен по лицензии MIT.

phenogram / bindings

Maintainers

Package info

Statistics

Security