Отделяем каталог от состояния меню
Используем PHP 8.3+, 64-битные целые числа, PDO SQLite и уже настроенный обработчик webhook. Каталог содержит только текстовый список и навигацию; оформление покупки и оплата — отдельные сценарии. Клиент Telegram не хранит для сервера надёжную сессию меню, поэтому нужные сведения записываем в БД.
Таблица categories содержит id, title и version. Products содержит id, category_id, title, price_minor, is_active и sort_order. Цена хранится целым числом в копейках, все позиции примера — в рублях. Для простоты ограничьте название товара 80 символами, чтобы пять строк помещались в одно сообщение.
В catalog_sessions сохраняйте token, bot_id, user_id, chat_id, message_id, category_id, catalog_version, revision, page и expires_at. Случайный token создавайте через bin2hex(random_bytes(8)); уникальное ограничение отклоняет редкую коллизию, после которой создаётся другой token. Session действует, например, 30 минут и принадлежит одному пользователю.
Catalog_version — снимок categories.version в момент открытия меню. Увеличивайте версию категории в одной транзакции с изменением её товаров, цены, доступности и порядка. Если товар переносится в другую категорию, обновите обе версии. Так бот не показывает навигацию от уже изменённого набора данных.
Базовые правила callback описаны в руководстве о неработающих inline-кнопках. Здесь сосредоточимся на полноценном меню с состоянием, а не только на доставке нажатия.
Загружаем страницу в стабильном порядке
Сортировка должна быть определённой. Одного ORDER BY sort_order недостаточно: у двух товаров может быть одинаковый порядок. Добавляем id, считаем страницы и ограничиваем запрошенный номер допустимыми границами. Для небольшого каталога OFFSET подходит; на больших наборах стоит перейти к навигации по курсору.
<?php
declare(strict_types=1);
/** @return array{page: int, text: string, reply_markup: array<string, mixed>} */
function catalogPage(PDO $db, int $categoryId, int $requestedPage, string $token, int $revision): array
{
$size = 5;
$count = $db->prepare('SELECT COUNT(*) FROM products WHERE category_id = ? AND is_active = 1');
$count->execute([$categoryId]);
$total = (int) $count->fetchColumn();
$pages = max(1, (int) ceil($total / $size));
$page = max(0, min($requestedPage, $pages - 1));
$query = $db->prepare(
'SELECT id, title, price_minor FROM products
WHERE category_id = :category AND is_active = 1
ORDER BY sort_order, id LIMIT :size OFFSET :offset'
);
$query->bindValue(':category', $categoryId, PDO::PARAM_INT);
$query->bindValue(':size', $size, PDO::PARAM_INT);
$query->bindValue(':offset', $page * $size, PDO::PARAM_INT);
$query->execute();
$lines = ['Каталог · страница '.($page + 1).' из '.$pages];
foreach ($query->fetchAll(PDO::FETCH_ASSOC) as $product) {
$price = number_format((int) $product['price_minor'] / 100, 2, ',', ' ');
$lines[] = $product['title'].' — '.$price.' ₽';
}
if ($total === 0) {
$lines[] = 'В этой категории пока нет доступных позиций.';
}
$buttons = [];
if ($page > 0) {
$buttons[] = ['text' => 'Назад', 'callback_data' => 'nav:'.$token.':'.$revision.':'.($page - 1)];
}
if ($page + 1 < $pages) {
$buttons[] = ['text' => 'Вперёд', 'callback_data' => 'nav:'.$token.':'.$revision.':'.($page + 1)];
}
return [
'page' => $page, 'text' => implode("\n", $lines),
'reply_markup' => ['inline_keyboard' => $buttons === [] ? [] : [$buttons]],
];
}
Функция возвращает данные для sendMessage или editMessageText, но сама ничего не отправляет. Служебное поле page запишите в сессию и уберите из параметров API. Parse_mode намеренно отсутствует: названия товаров не должны неожиданно интерпретироваться как HTML или Markdown.
На первой странице нет «Назад», на последней нет «Вперёд». Для пустой категории функция выдаёт понятное сообщение и пустую inline-клавиатуру. Товарные описания и фотографии лучше открывать отдельным экраном, сохранив обратный переход в ту же категорию.
Открываем категорию и связываем её с сообщением
Для выбора категории сначала отправьте меню с кнопками вида category:12. Получив callback, проверьте, что категория существует и доступна пользователю. Сам ID категории в callback не даёт права доступа; если каталог содержит закрытые цены, проверка обязательна при каждом чтении.
После выбора создайте новую catalog_sessions с page=0 и revision=1. Category_id берётся из проверенной категории, catalog_version — из её текущей версии. Случайный token нужен для ссылки на конкретное меню, а не для хранения самой категории в каждой кнопке.
Сформируйте первую страницу через catalogPage и отправьте sendMessage с chat_id, text и reply_markup. Из успешного ответа сохраните result.message_id. Пока message_id не сохранён, сессия не должна принимать навигацию: при очень быстром нажатии предложите открыть каталог заново. Ошибка сохранения связи не повод принимать кнопки от любого сообщения.
При каждом новом /catalog создавайте новую сессию и закрывайте предыдущую активную сессию пользователя для этого бота. Повторная команда не должна незаметно менять category_id старого сообщения. Если разрешаете несколько открытых меню одновременно, оставляйте им отдельные token и отдельные message_id.
Формат nav:token:revision:page укладывается в лимит callback_data 1–64 байта. Лимит считается в байтах, поэтому короткие ASCII-значения удобнее длинных русских названий и сериализованного JSON. Категория и права остаются на сервере.
Проверяем владельца, сообщение и версию кнопки
Следующая функция проверяет принадлежность callback к сохранённой сессии. Она не загружает сессию по данным клиента целиком: сначала извлеките token по такому же шаблону и найдите строку по (bot_id, token), затем передайте результат функции. currentCatalogVersion загрузите из categories по category_id найденной сессии.
<?php
declare(strict_types=1);
/** @param array<string, mixed> $callback
* @param array<string, mixed> $session
*/
function requestedCatalogPage(
array $callback, array $session, string $botId,
int $currentCatalogVersion, int $now,
): ?int {
$data = $callback['data'] ?? null;
if (!is_string($data)
|| !preg_match('/\Anav:([a-f0-9]{16}):([0-9]{1,9}):([0-9]{1,6})\z/', $data, $parts)) {
return null;
}
$message = $callback['message'] ?? [];
if (($session['bot_id'] ?? null) !== $botId
|| $session['token'] !== $parts[1]
|| (int) $session['user_id'] !== ($callback['from']['id'] ?? null)
|| (int) $session['chat_id'] !== ($message['chat']['id'] ?? null)
|| (int) $session['message_id'] !== ($message['message_id'] ?? null)
|| ($message['date'] ?? 0) === 0
|| (int) $session['expires_at'] <= $now
|| (int) $session['revision'] !== (int) $parts[2]
|| (int) $session['catalog_version'] !== $currentCatalogVersion) {
return null;
}
$page = (int) $parts[3];
return abs($page - (int) $session['page']) === 1 ? $page : null;
}
Expires_at в этом примере — Unix timestamp. Cast к int нужен для значений, полученных из PDO строками; Telegram-числа из json_decode остаются целыми. Пример не поддерживает inline_message_id и недоступное исходное сообщение: в этих случаях откройте новое меню, вместо попытки угадать chat_id.
Даже если token выглядит случайным, проверяйте from.id. Иначе чужой участник группового чата сможет управлять меню пользователя. Для личного каталога это ещё и защита от ошибочной привязки сессии при повторной обработке.
На каждое нажатие вызывайте answerCallbackQuery с callback_query_id. Для отклонённого callback добавьте text «Это меню устарело. Откройте /catalog»; для принятого достаточно ответа без текста. Не ждите длительного чтения каталога или очереди, прежде чем убрать индикатор ожидания. Это отдельный метод, а не HTTP-ответ webhook.
Меняем страницу и защищаемся от двойного нажатия
Проверка callback и изменение revision должны быть согласованы. В короткой транзакции перечитайте сессию, проверьте её владельца/срок и версию категории, сформируйте страницу, затем обновите сессию условием WHERE bot_id=? AND token=? AND revision=?. Если обновлена не одна строка, другой обработчик уже забрал этот переход: не отправляйте второй edit.
Revision увеличивайте на единицу и используйте новое значение в клавиатуре, которую вернул catalogPage. Запишите фактическую page, потому что функция могла ограничить запрошенный номер границами. При достижении предела формата revision или более миллиона страниц создайте новую сессию либо измените формат с проверкой длины callback_data.
Транзакцию завершите до HTTP-запроса. После этого отправьте editMessageText с сохранёнными chat_id/message_id, новым text и reply_markup. Не добавляйте page в API-параметры и не берите category_id из callback. Не запускайте редактирование, если выборка товаров и её версия не относятся к согласованному снимку БД.
{
"chat_id": 123456789,
"message_id": 340,
"text": "Каталог · страница 1 из 1\nВ этой категории пока нет доступных позиций.",
"reply_markup": {"inline_keyboard": []}
}
Если два нажатия пришли из одной старой клавиатуры, только первое изменит revision. Второе получит сообщение об устаревшем меню. Пользователь может нажать ещё раз уже на новой странице. Ключ (bot_id, update_id) дополнительно защищает от повторной доставки того же обновления.
Состояние в БД и сообщение Telegram не обновляются атомарно. Если edit завершился ошибкой или таймаутом после увеличения revision, старые кнопки могут перестать проходить проверку. Зафиксируйте проблему и предложите /catalog; не откатывайте revision вслепую после потери ответа, потому что Telegram мог уже применить новую клавиатуру.
Если нужен автоматический ремонт меню, храните желаемые text/reply_markup и состояние операции редактирования отдельно. Последовательный обработчик может восстановить именно последнее состояние, избегая перезаписи свежей страницы запоздавшим старым заданием. Для небольшого каталога повторное открытие — более простой явный путь восстановления.
Что делать при изменении товаров
Когда версия категории изменилась, отклоняйте старую кнопку и предлагайте открыть актуальный каталог. Это яснее, чем незаметно показывать другую страницу под прежними номерами. Категорию можно сохранить при повторном открытии, предварительно проверив, что она ещё существует и доступна.
Если позже добавите кнопку «Выбрать товар», передавайте стабильный product_id и проверяйте товар заново на сервере. Цена, наличие и категория могли измениться с момента показа. Нельзя принимать стоимость заказа из callback_data или считать показанную страницу резервированием товара.
Для варианта, где каталог меняется часто, допустима другая политика: пересчитать страницы и сообщить об обновлении. Но тогда задайте её явно и проверяйте соответствие выбранного товара. Код этого руководства использует строгую проверку версии и просит открыть новое меню.
Проверяем навигацию и восстановление
На 0, 1, 5, 6 и 11 активных товарах проверьте число страниц и крайние кнопки. Неактивные позиции не показываются.
Пройдите «Вперёд → Назад»: категория и стабильный порядок остаются теми же; новое сообщение при каждом нажатии не создаётся.
Повторите старый callback и дважды нажмите одну кнопку. Старая revision не должна переключать меню повторно.
Подставьте другого пользователя, chat_id, message_id, истёкшую сессию и неверный token. Ни один запрос не должен редактировать чужое меню.
Измените товар и версию категории. Старое меню предлагает открыть /catalog, новое показывает актуальные сведения.
Смоделируйте сбой editMessageText: пользователь может открыть меню заново, а журнал не утверждает, что редактирование подтвердилось.
Если Telegram-вызовы идут через BotGate, логика сессий и версий остаётся в приложении. Методы sendMessage, answerCallbackQuery и editMessageText вызываются с теми же Telegram-параметрами через API BotGate; транспорт не проверяет владельца вашего меню и актуальность товаров.
Первичные источники: InlineKeyboardButton и callback_data, CallbackQuery, answerCallbackQuery, editMessageText.