Простой роутер для бота на PHP

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

От Телеграм "прилетают" обновления (update) с разным набором свойств. Можно с легкостью это все дело ловить и направлять в нужное место с нужными данными.

Для определения чем обрабатывать пришедшие данные нам нужен роутер. Роутер должен быть в любом приложении, где это требуется, на этом сайте он также присутствует. Телеграм бот не исключение:

1. Поймать Старт бота
2. Отловить нажатие по inline-кнопке
3. Определить inline запрос
4. Вывести информацию при нажатии по клавиатуре
5. Направить на сохранение веденных данных от пользователя
6. ...

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

Для начала посмотрим какие данные приходят от Телеграм

Update от Телеграм не может сразу иметь более одного типа объекта.

Вот пример update при старте бота:

{
  update_id: 123456789000,
  message: {
    message_id: 1,
    from: {
      id: 123456,
      is_bot: false,
      first_name: '—',
      last_name: '—',
      language_code: 'ru'
    },
    chat: { id: 123456, first_name: '—', last_name: '—', type: 'private' },
    date: 1666004497,
    text: '/start',
    entities: [{"offset":0,"length":6,"type":"bot_command"}]
  }
}

Если отправлена команда Start или любое другое текстовое сообщение в том числе и команда от клавиатуры - то это объект Message со свойством text (пример выше).

Если это медиа сообщение, то это также объект Message с соответствующими свойствами:

1. photo - картинка
2. video - видео-файл
3. audio - аудио-файл
4. document - файл любого формата, в том числе и photo, video или audio, но направленные в виде файла без визуализации
5. video_note - видео-заметка
6. voice - аудио-заметка
7. location - геолокация
8. sticker - стикер
9. animation - анимация (gif)

В этих объектах нам будет интересны свойства:

1. message->from
2. message->[text | photo | video | audio | document | video_note | voice | location | sticker | animation]
3. message->[entities | caption_entities]

Если мы работаем с приватным типом chat, то message->chat не всегда пригодиться, только если для проверки типа чата.

message->from - в этом объекте лежат данные пользователя, в частности его Телеграм id, можно еще использовать другие данные объекта, например для приветствия пользователя по его имени.

message->[text | photo | video | audio | document | video_note | voice | location | sticker | animation] - направленные пользователем данные

message->[entities | caption_entities] - форматирование текстового содержания сообщения

* * *

При нажатии на inline-кнопку приходит уже другой тип объекта: CallBack_Query 

{
  update_id: 123456789001,
  callback_query: {
    id: '00001222',
    from: {
      id: 123456,
      is_bot: false,
      first_name: '—',
      last_name: '—',
      language_code: 'ru'
    },
    message: {
      message_id: 11,
      from: {
        id: 123456,
        is_bot: false,
        first_name: '—',
        last_name: '—',
        language_code: 'ru'
      },
      chat: { id: 123456, first_name: '—', last_name: '—', type: 'private' },
      date: 1665488669,
      text: 'Текст сообщения',
      reply_markup: {"inline_keyboard":[[{"text":"Test Button","callback_data":"inline_click"}]]}
    },
    chat_instance: '040495084748393',
    data: 'inline_click'
  }
}

Из этого объекта нам практически всегда потребуются несколько свойств:

1. callback_query->id - id запроса
2. callback_query->from - объект пользователя
3. callback_query->message->message_id - id сообщения по кнопке которого было событие click
4. callback_query->data - здесь зашитые данные кнопки, очень важная часть данных

callback_query->id - это свойство нам необходимо для уведомления Телеграм через метод answerCallbackQuery.

Когда мы не уведомим Телеграм, что запрос пришел по месту назначения и обработан, то он будет засылать повторно один и тот же запрос (update) в соответсвии со своей политикой.

Также это происходит когда в момент обработки сервер ответил ошибкой.

По моему опыту повторы идут через: 1 сек, 5 сек, 20 сек, 1 мин, 2 мин, 5 мин ... и т.д. в течении дня.

Повторные update от Телеграм чреваты! Например если у вас нажатие по кнопке должно быть пополнение баланса на определенную сумму, и если у вас в коде будет ошибка до выполнения уведомления или вообще отсутствие уведомления, то нажав один раз пользователь может не по своей вине пополнять свой баланс "за кадром" в течении дня, он будет рад, но для вас это будет проблемой. 

callback_query->from - в этом объекте лежат данные пользователя, в частности его Телеграм id.

callback_query->message->message_id - нам может пригодиться, например для удаления сообщения, чтобы закрепленные inline-кнопки не были доступны для повторного нажатия.

callback_query->data - самое важное свойство, в нем лежат параметры для выполнения задуманной логики

Строим простой роутер на php 

Телеграм направляет на установленный webHook POST запрос с update, нам необходимо получить эти данные, так как они в формате JSON, мы может спокойно их перевести или в объект stdClass() или в ассоциативный массив используя функцию json_decode.

Данные мы получим в сыром виде из потока php://input

// получаем данные от телеграм - преобразуем в объект stdClass
$data = json_decode(file_get_contents("php://input"));

Так как $data это объект, то обращаться к его свойствам мы можем используя конструкцию ->

// получим update_id
$update_id = $data->update_id;

Проверить существование свойства у объекта можно используя функцию isset() 

// проверим существует ли свойство update_id
$isSetUpdateId = isset($data->update_id);

Или через функцию property_exists()

// проверим существует ли свойство update_id
$isPropertyExists = property_exists($data, "update_id");

Оба варианта вернут bool значение, с разницей при значении у свойства null если оно существует - property_exists() вернет true

$data->update_id = null;

return property_exists($data, "update_id");    // true
return isset($data->update_id);                // false

Теперь с умением проверять наличие свойств у объекта можно смело начинать строить роутер.

/**
 * Простой роутер бота
 */
if (isset($data->message)) {
    // получим id чата
    $chat_id = $data->message->from->id;
    // проверим что это текстовое сообщение
    if (isset($data->message->text)) {
        // проверим что это старт бота
        if ($data->message->text == "/start") {
            // направим запрос в метод старта бота
            startBot($chat_id);
        }
    } elseif(isset($data->message->photo)) {
        // направим на сохранение photo
        savePhoto($chat_id, $data->message->photo);
    }
// если это нажатие по кнопке
} elseif (isset($data->callback_query)) {
    // получим id чата
    $chat_id = $data->callback_query->from->id;
    // получим callBackQuery_id
    $cbq_id = $data->callback_query->id;
    // получим переданное значение в кнопке
    $c_data = $data->callback_query->data;
    // спарсим значения
    $params = explode("_", $c_data);
    /**
     В этом месте мы в зависимости от заложенных параметров по принципу
     param1_param2_param3_param4 и т.д.
     можем направлять запрос в нужный метод
    */
    if($params[1] === "getPrice") {
        price($chat_id, $cbq_id, $params);
    } elseif($params[1] === "getDemo") {
        demo($chat_id, $cbq_id, $params);
    }
}