Конструктор Сообщений (Message Builder)

Класс Message предоставляет удобный "текучий интерфейс" (fluent interface) для создания, форматирования и отправки сообщений. Вместо того чтобы собирать массив параметров вручную, вы можете выстраивать сообщение в виде цепочки вызовов, что делает код более чистым и читаемым.

Основы использования

Основной принцип — вы создаете экземпляр сообщения, настраиваете его с помощью различных методов и в конце вызываете метод отправки (send()) или редактирования (editText(), editCaption() и т.д.).

Простое текстовое сообщение

Это самый базовый пример. Метод $tg->msg() является фабрикой, которая создает и возвращает экземпляр класса Message.

php

$bot->onCommand('start')->func(function(TGZ $tg) {
    $tg->msg("Привет, мир!")->send();
});

Цепочка вызовов (Chaining)

Сила конструктора в возможности объединять методы в цепочку. Например, отправим фото в ответ на сообщение пользователя.

php

$tg->msg("Вот ваше фото:")
   ->img('/path/to/image.jpg')  // Добавляем изображение
   ->reply()                    // Отвечаем на текущее сообщение
   ->send();                    // Отправляем

Основные методы

`text(string $text)`

Задает или изменяет основной текст сообщения или подпись к медиа.

php

$tg->msg("Начальный текст.")
   ->text("Текст изменен.") // Этот текст будет отправлен
   ->send();

`parseMode(?string $mode)`

Устанавливает режим форматирования текста.

Доступные режимы: 'HTML', 'MarkdownV2', 'Markdown'.
Если передать null или пустую строку, форматирование будет отключено.

php

// Использование HTML
$tg->msg("<b>Жирный текст</b> и <i>курсив</i>.")
   ->parseMode('HTML')
   ->send();

// Использование MarkdownV2
$tg->msg("*Жирный текст* и _курсив_.")
   ->parseMode('MarkdownV2')
   ->send();

`reply(?int $message_id = null)`

Делает сообщение ответом на другое сообщение.

Если $message_id не указан, ответ будет на текущее сообщение из контекста.

php

// Ответ на текущее сообщение
$tg->msg("Это ответ.")->reply()->send();

// Ответ на конкретное сообщение
$tg->msg("Отвечаю на сообщение c ID 12345.")->reply(12345)->send();

`action(?string $action = 'typing')`

Этот метод отправляет в чат статус действия, чтобы показать пользователю, что бот занят какой-то задачей (например, 'печатает...', 'загружает фото...'). Это улучшает пользовательский опыт, так как дает понять, что бот не завис, а выполняет операцию.

Ключевая особенность: в отличие от других методов конструктора, action() отправляет запрос к Telegram API немедленно в момент своего вызова, а не при вызове send(). Тем не менее, он возвращает экземпляр Message, позволяя продолжать цепочку вызовов.

php

$bot->onCommand('process')->func(function(TGZ $tg) {
    $tg->msg("Начинаю обработку, это займет несколько секунд...")->send();
    
    $Message = $tg->msg("Готово! Ваш отчет сформирован.")
       ->action(); // По умолчанию отправится 'typing'
       
    sleep(4); // Для реального проекта не рекомендуется использовать sleep

    $Message->send();
    // После использования метода send(), action пропадёт автоматически
});

Доступные действия

Параметр $action принимает одну из следующих строк:

typing (по умолчанию) - для текстовых сообщений
upload_photo - при отправке фото
record_video / upload_video - при работе с видео
record_voice / upload_voice - при работе с голосовыми сообщениями
upload_document - при отправке файлов
choose_sticker - при выборе стикера
find_location - при работе с геолокацией
record_video_note / upload_video_note - при работе с видео-кружочками

Работа с медиа

Конструктор позволяет легко отправлять различные типы медиа. В качестве источника файла можно использовать:

Локальный путь: /path/to/file.jpg
URL: https://example.com/image.png
Telegram file_id: AgACAgIAAxkBAA...

Отправка одного медиафайла

php

// Отправка фото по URL
$tg->msg("Фото из интернета")
   ->img('https://placehold.co/600x400')
   ->send();

// Отправка видео с диска
$tg->msg("Видео с диска")
   ->video('/data/my_video.mp4')
   ->send();

// Отправка документа по file_id
$tg->msg("Документ по ID")
   ->doc('BQACAgIAAxkBAAE..._')
   ->send();

Отправка группы медиа (Media Group)

Чтобы отправить несколько фото или видео в одном сообщении (альбомом), передайте в соответствующий метод массив источников.

Важно: Подпись (text()) будет добавлена только к первому элементу в медиагруппе. В одной группе можно смешивать фото и видео. Документы и аудиофайлы можно группировать только с файлами того же типа.

php

$photos = [
    'https://placehold.co/600x400/EEE/31343C',
    '/path/to/local/image.jpg',
    'AgACAgIAAxkBAAE...' // file_id
];

$tg->msg("Вот альбом из трех фото")
   ->img($photos)
   ->send();

`mediaPreview(string $url)`

Этот метод позволяет добавить к сообщению предпросмотр ссылки (rich preview), не отображая саму ссылку в тексте. Это достигается за счет добавления невидимой ссылки в начало текста.

php

$tg->msg("Эта статья очень полезна.")
   ->mediaPreview('https://example.com/some-article')
   ->send();

Клавиатуры

Метод kbd() позволяет управлять как обычными (reply), так и встроенными (inline) клавиатурами.

Reply-клавиатура

php

$buttons = [
    [
        $tg->buttonText('Кнопка 1'), 
        $tg->buttonText('Кнопка 2')
    ]
];

$tg->msg("Выберите кнопку:")
   ->kbd($buttons, resize_keyboard: true, one_time_keyboard: true)
   ->send();

Inline-клавиатура

php

$buttons = [
    [$tg->buttonUrl('Google', 'https://google.com')],
    [$tg->buttonCallback('Нажми меня', 'button_pressed')]
];

$tg->msg("Это inline-клавиатура:")
   ->kbd($buttons, inline: true)
   ->send();

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

Чтобы убрать reply-клавиатуру у пользователя, вызовите kbd() с параметром remove_keyboard: true.

php

$tg->msg("Клавиатура убрана.")
   ->kbd(remove_keyboard: true)
   ->send();

Редактирование сообщений

Вы можете редактировать уже отправленные сообщения.

`editText(?string $messageID = null, ?int $chatID = null)`

Редактирует текст сообщения.

php

// Пример в обработчике callback-запроса
$bot->onCallback('edit_text')
    ->func(function(TGZ $tg) {
        $query_id = $tg->getQueryID();
        $tg->answerCallbackQuery($query_id);
        
        $tg->msg("Этот текст изменён")->editText();
    });

`editCaption(?string $messageID = null, ?int $chatID = null)`

Редактирует подпись к медиа. Работает аналогично editText.

`editMedia(?string $messageID = null, ?int $chatID = null)`

Заменяет медиа в сообщении.

php

$tg->msg("Новая подпись к новому фото")
   ->img('/path/to/new_image.jpg')
   ->editMedia();

Полный список методов

Метод	Описание
`text(string $text)`	Устанавливает текст сообщения или подпись к медиа.
`parseMode(?string $mode)`	Задает режим парсинга (`HTML`, `MarkdownV2`).
`kbd(array $buttons, ...)`	Добавляет Reply или Inline клавиатуру, или удаляет её.
`reply(?int $message_id)`	Делает сообщение ответом на другое.
`img(string\|array $source)`	Добавляет фото или группу фото.
`video(string\|array $source)`	Добавляет видео или группу видео.
`doc(string\|array $source)`	Добавляет документ или группу документов.
`audio(string\|array $source)`	Добавляет аудио или группу аудио.
`voice(string $source)`	Добавляет голосовое сообщение.
`gif(string\|array $source)`	Добавляет GIF-анимацию.
`sticker(string $file_id)`	Отправляет стикер по его `file_id`.
`dice(string $emoji)`	Отправляет анимированный эмодзи-кубик (`🎲`, `🎯`, `🏀`, `⚽`, `🎳`, `🎰`).
`entities(array $entities)`	Устанавливает массив сущностей для форматирования.
`mediaPreview(string $url)`	Добавляет "невидимый" предпросмотр ссылки.
`params(array $params)`	Добавляет любые дополнительные параметры в запрос к API.
`action(?string $action)`	Отправляет действие в чат (`typing`, `upload_photo` и др.).
`send(?int $chatID)`	Завершающий метод. Отправляет собранное сообщение.
`editText(...)`	Завершающий метод. Редактирует текст существующего сообщения.
`editCaption(...)`	Завершающий метод. Редактирует подпись к медиа в существующем сообщении.
`editMedia(...)`	Завершающий метод. Заменяет медиа в существующем сообщении.
`sendEdit(...)`	Устаревший. Алиас для `editText` и `editCaption`.

TGZ

Message

Poll

Inline

Bot

Action

Конструктор Сообщений (Message Builder)

Основы использования

Простое текстовое сообщение

Цепочка вызовов (Chaining)

Основные методы

`text(string $text)`

`parseMode(?string $mode)`

`reply(?int $message_id = null)`

`action(?string $action = 'typing')`

Доступные действия

Работа с медиа

Отправка одного медиафайла

Отправка группы медиа (Media Group)

`mediaPreview(string $url)`

Клавиатуры

Reply-клавиатура

Inline-клавиатура

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

Редактирование сообщений

`editText(?string $messageID = null, ?int $chatID = null)`

`editCaption(?string $messageID = null, ?int $chatID = null)`

`editMedia(?string $messageID = null, ?int $chatID = null)`

Полный список методов

Action

Конструктор Сообщений (Message Builder) ​

Основы использования ​

Простое текстовое сообщение ​

Цепочка вызовов (Chaining) ​

Основные методы ​

text(string $text) ​

parseMode(?string $mode) ​

reply(?int $message_id = null) ​

action(?string $action = 'typing') ​

Доступные действия ​

Работа с медиа ​

Отправка одного медиафайла ​

Отправка группы медиа (Media Group) ​

mediaPreview(string $url) ​

Клавиатуры ​

Reply-клавиатура ​

Inline-клавиатура ​

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

Редактирование сообщений ​

editText(?string $messageID = null, ?int $chatID = null) ​

editCaption(?string $messageID = null, ?int $chatID = null) ​

editMedia(?string $messageID = null, ?int $chatID = null) ​

Полный список методов ​

Конструктор Сообщений (Message Builder)

Основы использования

Простое текстовое сообщение

Цепочка вызовов (Chaining)

Основные методы

`text(string $text)`

`parseMode(?string $mode)`

`reply(?int $message_id = null)`

`action(?string $action = 'typing')`

Доступные действия

Работа с медиа

Отправка одного медиафайла

Отправка группы медиа (Media Group)

`mediaPreview(string $url)`

Клавиатуры

Reply-клавиатура

Inline-клавиатура

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

Редактирование сообщений

`editText(?string $messageID = null, ?int $chatID = null)`

`editCaption(?string $messageID = null, ?int $chatID = null)`

`editMedia(?string $messageID = null, ?int $chatID = null)`

Полный список методов