Обработчики событий (Маршрутизация)

Класс Bot предоставляет гибкую систему маршрутизации для обработки различных типов обновлений от Telegram. Вы можете определить, как бот должен реагировать на команды, текстовые сообщения, нажатия кнопок, медиафайлы и другие события.

Каждый метод-обработчик создает уникальный "маршрут" (route) с заданным ID и возвращает объект класса Action, который позволяет настроить ответ или действие для этого маршрута.

Основные обработчики

Эти обработчики покрывают наиболее частые сценарии взаимодействия с ботом.

onBotCommand()

Срабатывает, когда пользователь отправляет команду, начинающуюся со слеша (/). Например, /start или /help.

Описание: Этот обработчик предназначен специально для стандартных команд Telegram. Он автоматически отделяет саму команду (например, /start) от следующих за ней аргументов. Аргументы передаются в ваш обработчик в виде отдельных параметров.

Сигнатура:

php

public function onBotCommand(string $id, array|string $command = null): Action

Параметры:

Параметр	Тип	Описание
`$id`	`string`	Уникальный идентификатор маршрута.
`$command`	`string`\|`array`	Команда или массив команд для отслеживания (например, `'/start'`). Если не указан, используется `$id`.

Пример использования:

php

// Обработка команды /start
$bot->onBotCommand('start', '/start')->func(function (TGZ $tg) {
    $tg->reply('Привет! Я бот');
});

// Обработка команды с аргументом (реферальная ссылка)
// Пользователь пишет: /start 12345
$bot->onBotCommand('start_ref', '/start')->func(function (TGZ $tg, $ref) {
    if (!empty($ref)) {
        $tg->reply("Вы пришли по реферальной ссылке: {$ref}");
    } else {
        $tg->reply('Привет! Я бот');
    }
});

onCommand()

Срабатывает, когда пользователь отправляет команду, начинающуюся с любого заданного префикса. Например, !ban или .info. Поддерживает шаблоны для парсинга аргументов.

Описание: Более гибкий аналог onBotCommand. Полезен для создания команд-администрирования в чатах. Вы можете использовать специальные плейсхолдеры в шаблоне команды для автоматического извлечения аргументов:

%s - строка (захватывает весь текст до конца сообщения).
%w - слово (одно слово без пробелов).
%n - число (только цифры).

Сигнатура:

php

public function onCommand(string $id, array|string $command = null): Action

Параметры:

Параметр	Тип	Описание
`$id`	`string`	Уникальный идентификатор маршрута.
`$command`	`string`\|`array`	Шаблон команды или массив шаблонов (например, `'!ban %n %s'`).

Пример использования:

php

// Простая команда !ping
$bot->onCommand('ping', '!ping')->func(function(TGZ $tg) {
    $tg->reply('pong!');
});

// Команда бана с числовым ID и текстовой причиной
// Пользователь пишет: !ban 12345678 флуд в чате
$bot->onCommand('ban', '!ban %n %s')->func(function(TGZ $tg, $userId, $reason) {
    // $userId будет '12345678'
    // $reason будет 'флуд в чате'
    $tg->reply("Пользователь {$userId} забанен по причине: {$reason}");
});

onText()

Срабатывает, когда текст сообщения в точности совпадает с указанной строкой. Чувствителен к регистру.

Описание: Идеально подходит для обработки нажатий на текстовые (не inline) кнопки клавиатуры.

Сигнатура:

php

public function onText(string $id, array|string $text = null): Action

Параметры:

Параметр	Тип	Описание
`$id`	`string`	Уникальный идентификатор маршрута.
`$text`	`string`\|`array`	Текст или массив текстов для точного совпадения.

Пример использования:

php

// Создаем кнопку
$bot->btn('about_btn', 'О нас');

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

onTextPreg()

Срабатывает, когда текст сообщения совпадает с заданным регулярным выражением.

Описание: Мощный инструмент для обработки сообщений, которые должны соответствовать определенному формату (например, email, номер телефона, артикул товара). Найденные группы из регулярного выражения передаются в обработчик как аргументы.

Сигнатура:

php

public function onTextPreg(string $id, array|string $pattern = null): Action

Параметры:

Параметр	Тип	Описание
`$id`	`string`	Уникальный идентификатор маршрута.
`$pattern`	`string`\|`array`	Регулярное выражение или их массив.

Пример использования:

php

// Обработка сообщения с email
// Пользователь пишет: Моя почта example@google.com
$bot->onTextPreg('email', '/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/')
    ->func(function (TGZ $tg, $matches) {
        $email = $matches[0];
        $tg->reply("Спасибо! Мы получили ваш email: {$email}");
    });

onCallback()

Срабатывает, когда пользователь нажимает на inline-кнопку (кнопку, прикрепленную к сообщению).

Описание: Этот обработчик реагирует на callback_data от inline-кнопок. callback_data — это строка, которую вы задаете при создании кнопки.

Сигнатура:

php

public function onCallback(string $id, string $data = null): Action

Параметры:

Параметр	Тип	Описание
`$id`	`string`	Уникальный идентификатор маршрута.
`$data`	`string`	`callback_data` из кнопки для отслеживания.

Пример использования:

php

// В каком-то другом обработчике отправляем сообщение с inline-кнопкой
$bot->onCommand('menu', '/menu')->text('Выберите действие:')->inlineKbd([
    [$tg->buttonCallback('Показать профиль', 'show_profile')]
]);

// Обрабатываем нажатие на эту кнопку
$bot->onCallback('profile', 'show_profile')->func(function (TGZ $tg) {
    $userId = $tg->getUserID();
    // Отвечаем на callback, чтобы убрать "часики" на кнопке
    $tg->answerCallbackQuery($tg->getQueryID(), ['text' => 'Загружаю профиль...']);
    // Редактируем исходное сообщение
    $tg->msg("Ваш ID: {$userId}")->editText();
});

onStart()

Срабатывает, когда пользователь отправляет /start.

Сигнатура:

php

public function onStart(): Action

Параметры: Метод не принимает параметров

Пример использования:

php

$bot->onStart()->text('Приветствую в боте!');

onReferral()

Срабатывает, когда пользователь отправляет /start через реферальную ссылку.

Сигнатура:

php

public function onReferral(): Action

Параметры: Метод не принимает параметров

Пример использования:

php

$bot->onReferral()
    ->func(function (TGZ $tg, $referral) {
        $tg->reply("Приветствую в боте! Ваша реферальная ссылка: {$referral}");
    });

Обработчики медиа и системных событий

Эти обработчики не принимают параметров, кроме ID, так как они реагируют на сам факт наличия определенного типа контента в сообщении.

Метод	Описание
`onSticker()`	Срабатывает при получении любого стикера.
`onPhoto()`	Срабатывает при получении фотографии.
`onVideo()`	Срабатывает при получении видео.
`onAudio()`	Срабатывает при получении аудиофайла (музыки).
`onVoice()`	Срабатывает при получении голосового сообщения.
`onDocument()`	Срабатывает при получении любого документа (файла).
`onVideoNote()`	Срабатывает при получении видео-сообщения ("кружочка").
`onNewChatMember()`	Срабатывает, когда в чат вступает новый участник (или несколько). В обработчик передается массив объектов `User`.
`onLeftChatMember()`	Срабатывает, когда участник покидает чат. В обработчик передается объект `User` покинувшего участника.
`onEditedMessage()`	Срабатывает, когда участник редактирует своё сообщение.

Пример использования:

php

// Реакция на любую фотографию
$bot->onPhoto()
    ->func(function (TGZ $tg) {
        $tg->reply('Какое красивое фото!');
    });

// Приветствие нового участника
$bot->onNewChatMember()
    ->func(function (TGZ $tg, UserDto $newMember3, UserDto $newMember2) {
        $name1 = $newMember1->firstName;
        $name2 = $newMember2->firstName;
        
        $tg->reply("Добро пожаловать в чат, $name1 и $name2");
    });

// Прощание с ушедшим участником
$bot->onLeftChatMember()
    ->func(function (TGZ $tg, UserDto $leftMember) {
        $name = $leftMember->firsNname;
        $tg->reply("{$name} покинул(а) нас. Очень жаль.");
    });

$bot->onEditedMessage()->text("Вы изменили сообщение!");

Fallback-обработчики (Резервные)

Эти обработчики срабатывают, если ни один из более конкретных маршрутов не подошел.

onMessage()

Срабатывает на любое текстовое сообщение, которое не подошло ни под один из маршрутов onBotCommand, onCommand, onText или onTextPreg.

Описание: Полезен для ответа пользователю, если его команда не распознана. Этот обработчик имеет более высокий приоритет, чем обработчики медиа.

Сигнатура:

php

public function onMessage(): Action

Пример использования:

php

$bot->onMessage()->func(function (TGZ $tg) {
    $tg->reply('Я не понял вашу команду. Используйте /help для списка команд.');
});

onDefault()

Срабатывает на любое обновление, которое не было обработано ни одним из вышеперечисленных маршрутов. Это самый низкий приоритет.

Описание: Это "универсальный" обработчик последней инстанции. Он сработает, если пришел, например, стикер, а обработчик onSticker() не был определен.

Сигнатура:

php

public function onDefault(): Action

Пример использования:

php

$bot->onDefault()->func(function (TGZ $tg) {
    // Можно, например, логировать необработанные обновления
    error_log('Необработанное обновление: ' . json_encode($tg->context->getUpdateData()));
});

TGZ

Message

Poll

Inline

Bot

Action

Обработчики событий (Маршрутизация)

Основные обработчики

onBotCommand()

onCommand()

onText()

onTextPreg()

onCallback()

onStart()

onReferral()

Обработчики медиа и системных событий

Fallback-обработчики (Резервные)

onMessage()

onDefault()

Action

Обработчики событий (Маршрутизация) ​

Основные обработчики ​

onBotCommand() ​

onCommand() ​

onText() ​

onTextPreg() ​

onCallback() ​

onStart() ​

onReferral() ​

Обработчики медиа и системных событий ​

Fallback-обработчики (Резервные) ​

onMessage() ​

onDefault() ​

Обработчики событий (Маршрутизация)

Основные обработчики

onBotCommand()

onCommand()

onText()

onTextPreg()

onCallback()

onStart()

onReferral()

Обработчики медиа и системных событий

Fallback-обработчики (Резервные)

onMessage()

onDefault()