Обработка ошибок (Error Handling)

Никто не пишет идеальный код с первого раза. В процессе работы бота могут возникать исключения, синтаксические ошибки или проблемы с API. Чтобы бот не "умирал" молча, в ZenithGram встроен мощный инструмент ErrorHandler.

Он позволяет:

1. Автоматически перехватывать все исключения и фатальные ошибки.
2. Отправлять подробный отчет (с трассировкой и участком кода) разработчику в Telegram.
3. Выполнять произвольную логику (например, запись в лог-файл) при возникновении ошибки.

Быстрый старт

Для включения обработчика ошибок необходимо вызвать метод enableDebug() и указать, куда отправлять отчеты.

$tg->enableDebug()->setSendIds(123456789);

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

Настройка получателей

Отправка в Telegram (setSendIds)

Самый удобный способ для разработки — получать ошибки прямо в личные сообщения или в чат разработчиков.

// Один получатель
$tg->enableDebug()->setSendIds(123456789);

// Несколько получателей (или чат)
$tg->enableDebug()->setSendIds([123456789, -100987654321]);

Свой обработчик (setHandler)

Если вам нужно логировать ошибки в файл, отправлять их в Sentry/Kibana или выполнять другую логику, используйте setHandler.

$tg->enableDebug()
    ->setHandler(function (ZG $tg, Throwable $e) {
        // $e - объект исключения
        // Записываем ошибку в системный лог
        error_log("Критическая ошибка бота: " . $e->getMessage());
        
        // Можно отправить вежливое сообщение пользователю, который столкнулся с ошибкой
        $tg->msg("Произошла ошибка, разработчики уже уведомлены.")->send();
    });

Комбинация

Вы можете использовать setSendIds и setHandler одновременно. Бот отправит отчет вам в ЛС и выполнит вашу функцию логирования.

Настройка трассировки (Stack Trace)

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

shortTrace(bool $enable)

Этот метод фильтрует стек вызовов.

• true (Рекомендуется): В отчете останутся только те файлы, которые относятся к вашему проекту (исключая папку vendor). Это позволяет мгновенно найти место ошибки в вашем коде.
• false (По умолчанию): Полный стек вызовов, включая все внутренние файлы библиотеки и фреймворка. Полезно для отладки самой библиотеки.

// Показываем только ошибки в моих файлах
$tg->enableDebug()->shortTrace(true);

setTracePathFilter(string $path)

Позволяет скрыть часть пути к файлам в отчете, чтобы сообщения были компактнее. Обычно туда передают путь к корню проекта.

// Вместо "/var/www/html/my-bot/bot.php" будет "bot.php"
$tg->enableDebug()->setTracePathFilter('/var/www/html/my-bot/');
// Или для Windows. Вместо "C:\my-bot\bot.php" будет "bot.php"
$tg->enableDebug()->setTracePathFilter('C:\my-bot\\');

Примеры использования

Пример 1: Webhook

При работе через Webhook важно инициализировать enableDebug в самом начале скрипта, сразу после создания объекта.

<?php
require_once __DIR__  . '/vendor/autoload.php';
use ZenithGram\ZenithGram\ZG;
use ZenithGram\ZenithGram\Bot;

$tg = ZG::create('BOT_TOKEN');

// Включаем отладку
$tg->enableDebug()
    ->setSendIds(123456789) // ID админа
    ->shortTrace(true);     // Только мой код

$bot = new Bot($tg);

// ... логика бота ...
// Допустим, здесь ошибка:
$bot->onCommand('error')->func(fn() => 10 / 0); 

$bot->run();

Пример 2: Long Polling

В режиме Long Polling обработчик ошибок настраивается у экземпляра класса LongPoll. Это гарантирует, что даже если скрипт упадет внутри цикла прослушивания, вы получите уведомление, и скрипт (в зависимости от критичности) может перезапуститься или корректно завершиться.

<?php
require_once __DIR__  . '/vendor/autoload.php';
use ZenithGram\ZenithGram\LongPoll;
use ZenithGram\ZenithGram\ZG;
use ZenithGram\ZenithGram\Bot;

$lp = LongPoll::create('BOT_TOKEN');

// Включаем отладку для LongPoll
$lp->enableDebug()
   ->setSendIds([123456789])
   ->shortTrace(true);

$bot = new Bot();

// ... логика бота ...
// Допустим, здесь ошибка:
$bot->onCommand('error')->func(fn() => 10 / 0); 

// Запускаем
echo "Бот запущен...";
$lp->listen(function (ZG $tg) use ($bot) {
    $bot->zg($tg)->run();
});

Примеры вывода

Сообщение в Telegram

---

Терминал