README

Простая, но мощная PHP библиотека для Telegram Bot API!

ZenithGram — это библиотека нового поколения для создания Telegram-ботов. Она избавляет вас от бесконечных массивов и if/else конструкций, предлагая чистый, декларативный синтаксис, мощный роутер и удобные конструкторы.

⚡ Ключевые особенности

• Fluent Interface: Цепочки методов для создания сообщений (msg()->img()->text()->send()).
• Мощный Роутер: Класс Bot для удобной обработки команд, текста, кнопок и регулярных выражений.
• FSM и Диалоги: Встроенная машина состояний для создания пошаговых сценариев и анкет с сохранением контекста (step, onState).
• AI-Native: Оптимизирована для работы с AI-ассистентами (Cursor, Windsurf).
• Универсальность: Поддержка Webhook и LongPoll из коробки.
• Обработка ошибок: Встроенный обработчик ошибок.
• Встроенная Пагинация: Автоматическая генерация постраничной навигации для списков.

📦 Установка

Установите библиотеку через Composer:

composer require zenithgram/zenithgram

🤖 AI-Native Development

Если вы используете Cursor, Windsurf или другие AI-IDE, добавьте ссылку на наш контекстный файл в документацию проекта. Нейросеть мгновенно изучит все методы библиотеки и будет писать идеальный код.

📄 Ссылки для AI:

• https://zenithgram.github.io/llms-full.txt
• https://zenithgram.github.io/llms.txt

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

Полное описание всех методов, классов и возможностей доступно на официальном сайте:

👉 Читать полную документацию

🛠 Основные возможности

Конструктор сообщений

Забудьте о ручном сборе массивов параметров. Используйте цепочки методов:

$tg->msg("Посмотрите на это *фото*!")
    ->img('https://cataas.com/cat') // URL, ID файла или путь
    ->reply() // Ответить на сообщение пользователя
    ->parseMode('MarkdownV2')
    ->send();

Роутинг и обработка событий

Класс Bot позволяет элегантно обрабатывать любые события:

// Команда с аргументами (!ban @user причина)
$bot->onCommand('ban', '!ban %w %s')
    ->func(function(ZG $tg, $username, $reason) {
        $tg->reply("Пользователь $username забанен. Причина: $reason");
    });

// Обработка кнопки "О нас" (текстовая клавиатура)
$bot->onText('about', 'ℹ️ О нас')
    ->text('Мы — лучшая компания!');

// Регулярные выражения (поиск email)
$bot->onTextPreg('email', '/[\w\.]+@[\w\.]+/')
    ->func(function(ZG $tg, $matches) {
        $tg->reply("Найден email: " . $matches[0]);
    });

Умные клавиатуры

Создавайте меню и обрабатывайте нажатия (Callback) в одном месте:

// 1. Создаем кнопки и их действия
$bot->btn('yes', '✅ Да')
    ->query('Вы согласились!') // Всплывающее уведомление
    ->editText('Отлично, вы нажали ДА.');

$bot->btn('no', '❌ Нет')
    ->editText('Вы отказались.');

// 2. Отправляем клавиатуру
$bot->onBotCommand('vote', '/vote')
    ->text('Вам нравится ZenithGram?')
    ->inlineKbd([
        ['yes', 'no'], // Используем ID кнопок
        [Button::url('Документация', 'https://zenithgram.github.io')]
    ]);

$bot->run();

Пагинация

Автоматическое создание навигации для больших списков:

// Создаем 50 кнопок
$items = [];
for ($i = 0; $i < 50; $i++) $items[] = Button::cb("Товар $i", "item_$i");

// Генерируем клавиатуру для 1-й страницы
$keyboard = $tg->pagination()
    ->setItems($items)
    ->setPerPage(5)
    ->setPage(1)
    ->create();

$tg->msg("Каталог товаров:")->inlineKbd($keyboard)->send();