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

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

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

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

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

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

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

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

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

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

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

text(string $text)

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

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

parseMode(?string $mode)

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

Доступные режимы описаны в MessageParseMode

use ZenithGram\ZenithGram\Enums\MessageParseMode;

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

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

reply(?int $message_id = null)

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

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

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

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

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

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

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

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

// Отправка фото по 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()) будет добавлена только к первому элементу в медиагруппе. В одной группе можно смешивать фото и видео. Документы и аудиофайлы можно группировать только с файлами того же типа.

$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), не отображая саму ссылку в тексте. Это достигается за счет добавления невидимой ссылки в начало текста.

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

Клавиатуры

Для управления клавиатурами существует 3 метода: kbd(), inlineKbd() и removeKbd() для reply, inline и удаления соответственно.

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

use ZenithGram\ZenithGram\Button;

$buttons = [
    [
        Button::text('Кнопка 1'), 
        Button::text('Кнопка 2')
    ]
];

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

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

use ZenithGram\ZenithGram\Button;

$buttons = [
    [Button::url('Google', 'https://google.com')],
    [Button::cb('Нажми меня', 'button_pressed')]
];

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Метод	Описание
text	Устанавливает текст сообщения или подпись к медиа.
parseMode	Задает режим парсинга.
kbd	Добавляет Reply-клавиатуру.
inlineKbd	Добавляет Inline-клавиатуру.
removeKbd	Удаляет клавиатуру.
reply	Делает сообщение ответом на другое.
img	Добавляет фото или группу фото.
video	Добавляет видео или группу видео.
doc	Добавляет документ или группу документов.
audio	Добавляет аудио или группу аудио.
voice	Добавляет голосовое сообщение.
gif	Добавляет GIF-анимацию.
sticker	Отправляет стикер по его file_id.
dice	Отправляет анимированный эмодзи-кубик (🎲, 🎯, 🏀, ⚽, 🎳, 🎰).
entities	Устанавливает массив сущностей для форматирования.
mediaPreview	Добавляет "невидимый" предпросмотр ссылки.
params	Добавляет любые дополнительные параметры в запрос к API.
send	Завершающий метод. Отправляет собранное сообщение.
editText	Завершающий метод. Редактирует текст существующего сообщения.
editCaption	Завершающий метод. Редактирует подпись к медиа в существующем сообщении.
editMedia	Завершающий метод. Заменяет медиа в существующем сообщении.
sendEdit	Устаревший. Алиас для editText и editCaption.

Более подробное описание каждого метода в описании класса Message