README

Фреймворк для создания Telegram ботов на Laravel с поддержкой мультибота и разделением окружений.

Возможности

🤖 Мультиботная архитектура - управление множественными ботами
🔄 Разделение окружений - отдельные токены и домены для dev/prod
🌍 i18n поддержка - встроенная система интернационализации без зависимостей
🛠️ Интерактивные команды - удобное управление через CLI
🔐 Безопасность - webhook secrets, валидация токенов
📊 Мониторинг - проверка здоровья ботов, метрики
🗄️ База данных - хранение настроек и состояний
🚀 Готовые команды - быстрая настройка и развертывание

Установка

composer require tbot/laravel

Публикация файлов

Стандартная публикация (пропускает существующие файлы)

php artisan bot:publish

Публикация с принудительным обновлением

php artisan bot:publish --force

Публикация конкретных компонентов

php artisan bot:publish --tag=bot-config --force

или

php artisan bot:publish --tag=bot-app --force

Миграции

php artisan migrate

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

1. Создание бота

php artisan bot:new

Команда проведет вас через интерактивную настройку:

Ввод имени бота
Настройка токена
Указание администраторов
Настройка webhook

2. Управление ботами

# Список всех ботов
php artisan bot:manage list

# Информация о конкретном боте
php artisan bot:manage show mybot

# Активация/деактивация бота
php artisan bot:manage enable mybot
php artisan bot:manage disable mybot

# Тестирование бота
php artisan bot:manage test mybot

3. Управление доменами

# Установка домена для окружения
php artisan bot:domain set mybot dev https://dev.example.com
php artisan bot:domain set mybot prod https://example.com

# Просмотр доменов бота
php artisan bot:domain show mybot

# Список всех доменов
php artisan bot:domain list

4. Управление webhook

# Настройка webhook (автоматически использует домен из БД)
php artisan bot:webhook set mybot

# Информация о webhook
php artisan bot:webhook info mybot

# Удаление webhook
php artisan bot:webhook delete mybot

# Тестирование webhook
php artisan bot:webhook test mybot

5. Управление окружениями

# Переключение на dev окружение
php artisan bot:env dev

# Переключение на prod окружение
php artisan bot:env prod

# Сброс к значению из env файла
php artisan bot:env dev --reset

6. Публикация файлов

# Публикация всех файлов
php artisan bot:publish

# Принудительное обновление всех файлов
php artisan bot:publish --force

# Обновление конкретных компонентов
php artisan bot:publish --tag=bot-config --force
php artisan bot:publish --tag=bot-app --force
php artisan bot:publish --tag=bot-routes --force

Разделение окружений

Фреймворк использует единую структуру для токенов и webhook URL:

Токены

token - токен бота

Webhook URL

webhook_url - полный URL webhook с доменом (например: https://example.com/webhook/botname)

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

// В коде бота
$bot = Bot::find(1);

// Получение токена
$token = $bot->token;

// Получение webhook URL
$webhookUrl = $bot->webhook_url;

// Проверка наличия токена
if ($bot->hasToken()) {
    // Бот имеет токен
}

// Проверка наличия webhook URL
if ($bot->hasWebhookUrl()) {
    // Бот имеет настроенный webhook
}

Структура проекта

app/
├── Bots/                    # Классы ботов
│   ├── AbstractBot.php     # Базовый класс бота
│   └── MyBot.php          # Ваш бот
├── Console/Commands/       # CLI команды
│   ├── BotCommand.php     # Управление ботами
│   ├── SetupCommand.php   # Настройка ботов
│   ├── WebhookCommand.php # Управление webhook
│   └── DomainCommand.php  # Управление доменами
└── Models/
    └── Bot.php            # Модель бота

config/
└── bot.php               # Конфигурация

database/migrations/      # Миграции БД

Конфигурация

Основные настройки в config/bot.php:

return [
    'multibot' => [
        'enabled' => true,
        'auto_create_classes' => true,
        'bots_path' => 'App\\Bots',
    ],
    
    'webhook' => [
        'base_url' => env('BOT_WEBHOOK_BASE_URL', env('APP_URL')),
        'auto_generate_secret' => true,
    ],
    
    'security' => [
        'webhook_secret' => env('BOT_WEBHOOK_SECRET'),
        'admin_ids' => array_filter(explode(',', env('BOT_ADMIN_IDS', ''))),
    ],
];

Команды

Основные команды

Команда	Описание
`bot:new`	Создание нового бота
`bot:manage list`	Список всех ботов
`bot:manage show {bot}`	Информация о боте
`bot:manage test {bot}`	Тестирование бота
`bot:webhook set {bot}`	Настройка webhook
`bot:domain set {bot} {env} {domain}`	Установка домена

Управление доменами

Команда	Описание
`bot:domain set {bot} {env} {domain}`	Установка домена
`bot:domain show {bot}`	Просмотр доменов бота
`bot:domain list`	Список всех доменов

Управление webhook

Команда	Описание
`bot:webhook set {bot} {url?}`	Настройка webhook
`bot:webhook info {bot}`	Информация о webhook
`bot:webhook delete {bot}`	Удаление webhook
`bot:webhook test {bot}`	Тестирование webhook

Интернационализация (i18n)

Фреймворк включает встроенную систему интернационализации без внешних зависимостей:

Использование модуля

Добавьте I18nModule в ваш бот:

use Bot\Modules\I18nModule;

class MyBot extends LightBot
{
    use I18nModule;
    
    public function start()
    {
        // Автоматический перевод в sendSelf/sendOut
        $this->sendSelf('messages.welcome', [
            ['messages.button.start'],
            ['messages.button.help']
        ]);
    }
}

Ручной перевод

// Перевод с параметрами
$greeting = $this->translate('messages.user.greeting', ['name' => 'John']);

// Перевод массивов
$buttons = $this->translateArray([
    ['messages.button.start'],
    ['messages.button.help']
]);

Файлы переводов

Создайте файлы переводов в resources/lang/{locale}/:

// resources/lang/en/messages.php
return [
    'welcome' => 'Welcome to our bot!',
    'button' => [
        'start' => 'Start',
        'help' => 'Help',
    ],
    'user' => [
        'greeting' => 'Hello, :name!',
    ],
];

Подробная документация: I18N_USAGE.md

Создание бота

После создания бота автоматически генерируется класс:

<?php

namespace App\Bots;

class MyBot extends AbstractBot
{
    public function main(): void
    {
        $this->commands();
        
        if ($this->hasMessageText() && $this->isMessageCommand()) {
            $this->handleCommand($this->getMessageText());
        }
    }

    public function commands(): void
    {
        $this->registerCommand('start', function () {
            $this->sendSelf('🎉 Привет! Я бот MyBot');
        }, [
            'description' => 'Запуск бота'
        ]);

        $this->registerCommand('help', function () {
            $this->sendSelf([
                '📋 Доступные команды:', 
                '', 
                '/start - Запуск бота', 
                '/help - Помощь'
            ]);
        }, [
            'description' => 'Помощь'
        ]);
    }
}

Безопасность

🔐 Автоматическая генерация webhook secrets
🛡️ Валидация токенов и доменов
🔒 Проверка SSL сертификатов
🚫 Защита от спама и rate limiting
👥 Система администраторов

Мониторинг

# Проверка здоровья всех ботов
php artisan bot:health

# Статистика
php artisan bot:stats

# Конфигурация
php artisan bot:config show

Лицензия

MIT License

tbot / laravel

Maintainers

Details