Download the PHP package grobolof/bot-payload without Composer
On this page you can find all versions of the php package grobolof/bot-payload. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package bot-payload
bot-payload
PHP-библиотека для чат-ботов Telegram и VK.
Пакет не ходит в API. Он делает две вещи:
- Гидратация — входящий JSON вебхука превращается в PHP-объекты.
- Форматирование — исходящие текст и клавиатуры собираются в массив параметров, который можно сразу отдать HTTP-клиенту (
sendMessage,messages.sendи т.д.).
Установка
PHP ^8.2, Symfony Serializer ^6.4 || ^7.4 || ^8.0.
Если пакет ещё не на Packagist, подключите репозиторий:
Telegram
Что присылает Telegram (гидратация)
После setWebhook Telegram шлёт POST с JSON-объектом Update. Обязательное поле одно: update_id. Дальше присутствует не больше одного события.
Пакет гидратирует три самых нужных типа:
| Поле Update | Когда приходит | Что внутри |
|---|---|---|
message |
Пользователь написал текст, отправил контакт, фото и т.д. | message_id, date, chat, from, text, entities, contact, вложения |
edited_message |
Пользователь отредактировал сообщение | тот же объект Message |
callback_query |
Нажата inline-кнопка | id, from, data, chat_instance, message |
Остальные типы Update (inline_query, my_chat_member, …) библиотека не маппит: TelegramMapper::exec() всё равно вернёт TelegramUpdate с одним updateId.
Текстовое сообщение / команда
Контакт (кнопка «Поделиться номером»)
Вложения (photo, document, voice, audio, video, sticker, location, web_app_data) сохраняются как массивы, без отдельной модели на каждый тип.
Нажатие inline-кнопки
После каждого callback_query Telegram ждёт answerCallbackQuery, иначе у пользователя крутится прогресс на кнопке.
Некорректный JSON бросает BotPayload\Exception\InvalidPayloadException.
Что принимать в ответ (отправка в Telegram)
Библиотека собирает параметры методов Bot API. Отправку делает ваш HTTP-клиент, например:
POST https://api.telegram.org/bot<token>/sendMessage
Если тело запроса application/json, массив можно кодировать целиком. Если application/x-www-form-urlencoded, поле reply_markup нужно отдельно json_encode.
sendMessage
Поля, которые заполняет пакет:
| Параметр | Откуда | Обязателен |
|---|---|---|
chat_id |
int\|string |
да |
text |
строка; при parseMode ещё прогоняется через MarkdownV2 |
да |
parse_mode |
Mod::MARKDOWN_V2 → MarkdownV2 |
нет |
reply_markup |
объект клавиатуры | нет |
disable_notification |
bool | нет |
reply_to_message_id |
int | нет |
message_thread_id |
int, топик форума | нет |
Без parseMode текст уходит как есть, parse_mode в payload нет.
MarkdownV2
Telegram требует экранировать _ * [ ] ( ) ~ \ > # + - = | { } . !`. Пакет экранирует их сам. Разметку размечайте маркерами, а не сырым Markdown — иначе звёздочки в тексте пользователя сломают парсер.
| Маркер | Результат |
|---|---|
#__MARKER_FONT_BOLD_OPEN__# / _CLOSE__# |
*жирный* |
#__MARKER_URL_TEXT_OPEN__# / _CLOSE__# |
[текст](...) |
#__MARKER_URL_LINK_OPEN__# / _CLOSE__# |
(https://...) |
#__MARKER_LOWERCASE_CODE_OPEN__# / _CLOSE__# |
`code` |
#__MARKER_LINEFEED__# |
перевод строки |
Обычные \n тоже сохраняются. Несбалансированные маркеры бросают TagsMismatchException.
Можно вызвать только форматтер текста:
Клавиатуры (reply_markup)
Три варианта, все через TelegramFormatter::replyMarkup() / sendMessage(..., replyMarkup: ...).
1. Reply-клавиатура — кнопки вместо системной клавиатуры. Нажатие присылает обычный message с текстом кнопки. У reply-кнопок нет callback_data.
Уходит как:
Если buttonsPerRow не задан, ряд берётся из Button::$row (нумерация с 1).
Дополнительно у Keyboard: isPersistent, selective, inputFieldPlaceholder.
2. Inline-клавиатура — кнопки под сообщением. Нажатие присылает callback_query (или открывает URL / inline-режим).
Каждая кнопка должна содержать ровно одно действие: callbackData (1–64 байта), url или switchInlineQuery.
3. Удалить reply-клавиатуру
answerCallbackQuery
Опционально: showAlert, url, cacheTime.
Старый метод replayMarkup() оставлен как алиас replyMarkup().
VK
Что присылает VK (гидратация)
Callback API / Bots Long Poll шлёт JSON:
VKMapper::exec() понимает три типа, нужных боту. Остальные (group_join, message_reply, …) возвращают null — их можно игнорировать.
Ответ серверу на вебхук: строка ok (кроме confirmation). Сама отправка сообщения — отдельный запрос к messages.send.
confirmation — проверка Callback URL
message_new — входящее сообщение или нажатие text-кнопки
Для API 5.103+ object содержит message и client_info. Text-кнопка обычной клавиатуры тоже приходит как message_new: текст кнопки в message.text, ваши данные — в message.payload (JSON-строка).
payload в VK приходит строкой — пакет сам делает json_decode. Сырая строка: getRawPayload().
Вложения, пересланные сообщения, reply_message, geo, action, keyboard доступны как массивы с сообщения.
client_info.button_actions — какие типы кнопок клиент умеет (text, callback, open_link, …). Имеет смысл не слать callback, если его нет в списке.
message_event — нажатие callback-кнопки
Здесь два разных event_id:
- корневой — идентификатор события Callback API;
object.event_id— одноразовый id нажатия (живёт ~1 минуту), его нужно отдать вmessages.sendMessageEventAnswer.
Что принимать в ответ (отправка в VK)
messages.send
POST https://api.vk.ru/method/messages.send
| Параметр | Откуда | Обязателен |
|---|---|---|
peer_id |
из входящего события | да |
message |
текст как есть (у VK нет MarkdownV2) | да, если нет attachment |
random_id |
ваш int или случайный | да |
keyboard |
JSON-строка, не объект | нет |
attachment |
photo123_456, … |
нет |
reply_to |
id сообщения | нет |
Плюс ваш access_token и v.
Клавиатура VK
Формат официальной клавиатуры:
Keyboard |
Смысл |
|---|---|
oneTime: true |
скрыть после нажатия (только обычная клавиатура) |
inline: true |
кнопки под сообщением |
buttonsPerRow |
нарезка рядов; иначе используется Button::$row |
ButtonType |
Когда жать | Что придёт боту |
|---|---|---|
TEXT |
обычная / inline | message_new, текст + payload |
CALLBACK |
inline | message_event + payload |
OPEN_LINK |
нужен link |
ничего, клиент открывает URL |
OPEN_APP |
нужны appId, опционально ownerId/hash |
открывает VK Mini App |
LOCATION |
запрос геоточки | message_new с geo |
Цвета (ButtonColor) для text и callback: primary, secondary, positive, negative.
payload можно передать массивом — пакет сам сделает JSON-строку (лимит VK — 255 символов).
Скрыть клавиатуру:
Эту структуру нужно json_encode и передать в messages.send как keyboard. Либо используйте VKFormatter::keyboardJson($markup).
Лимиты VK: до 10 рядов; в ряду до 4 кнопок у обычной клавиатуры и до 5 у inline.
messages.sendMessageEventAnswer
Обязателен после message_event, иначе у пользователя крутится индикатор на кнопке.
Готовые event_data:
Минимальный цикл бота
Telegram
VK
Тесты
All versions of bot-payload with dependencies
symfony/http-client Version ^6.4 || ^7.4 || ^8.0
symfony/property-access Version ^6.4 || ^7.4 || ^8.0
symfony/property-info Version ^6.4 || ^7.4 || ^8.0
symfony/serializer Version ^6.4 || ^7.4 || ^8.0