README

Seamless integration of TGram the powerful PHP library for creating Telegram bots with the Laravel framework.

🚀 Features

Artisan Commands: Use TGram through familiar Laravel commands
Laravel Cache Integration: Automatic PSR-16 adapter
Laravel Configuration: Native Laravel configuration system
Dependency Injection: Type-hint Bot in controllers for automatic injection
Service Container: Bot registered as singleton in Laravel container
Webhook Management: Easy webhook configuration for Telegram bots

📦 Installation

composer require mk4u/larabot

⚡ Quick Start

1. Install and Configure

php artisan tgram

This command will:

Configure the Laravel API (Sanctum)
Publish the TGram configuration
Create bot directory structure (commands, callbacks, middlewares)
Create default command classes (Start, Help)
Generate middleware configuration

2. Configure your Bot

Add to your .env file:

BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOQRSTZ

3. Register default commands and callback functions

php artisan tgram:register

4. Configure Webhook

php artisan tgram:hook:set https://yourdomain.com/bot/api/webhook

5. Create Your Commands

php artisan tgram:command HelloWorld

🛠 Available Commands

Command	Description
`php artisan tgram`	Install and configure TGram
`php artisan tgram:register`	Register all commands and callbacks
`php artisan tgram:hook:set <url>`	Set webhook URL
`php artisan tgram:hook:delete`	Delete webhook
`php artisan tgram:hook:info`	Get webhook info
`php artisan tgram:hook:about`	Get bot info
`php artisan tgram:poll <interval>`	Start long polling
`php artisan tgram:command <name>`	Create new command
`php artisan tgram:callback <name> <action>`	Create new callback handler
`php artisan tgram:conversation <name>`	Create new conversation
`php artisan tgram:handler <name>`	Create new handler
`php artisan tgram:middleware <name>`	Create new middleware

⚙️ Settings

After installation, add to your .env:

BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOQRSTZ
BOT_SECRET=your_secret_key (optional)
BOT_MANAGERS=123456789,985632147 (optional)

Parameter descriptions:

BOT_TOKEN — Your Telegram bot token (issued by @BotFather). Required.
BOT_SECRET — Secret token to verify webhook authenticity (X-Telegram-Bot-Api-Secret-Token header). Optional but recommended.
BOT_MANAGERS — Telegram user IDs of bot administrators, comma-separated. Enables the isAdmin() method to restrict commands. Optional.

🌐 Webhook Route

Add to your routes/api.php:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/bot', function (Request $request) {
    app('tgram')->run();
});

🔧 Dependency Injection

Type-hinting in Controllers

The Bot is registered as a singleton in Laravel's service container. You can inject it directly:

<?php

namespace App\Http\Controllers;

use Mk4U\TGram\Bot;

class TelegramController extends Controller
{
    public function sendMessage(Bot $bot)
    {
        $bot->sendMessage(
            chat_id: '123456789',
            text: 'Hello from Laravel!'
        );

        return response()->json(['status' => 'sent']);
    }
}

Using the Service Container

use Mk4U\TGram\Bot;

// Method 1: via type-hinting (recommended)
public function myMethod(Bot $bot) { ... }

// Method 2: via alias 'tgram' (recommended)
$bot = app('tgram');

// Method 3: via app() helper
$bot = app(Bot::class);

Note: Always use app('tgram') or app(Bot::class) instead of new Bot(...). The singleton handles Laravel cache integration automatically.

Using Facade (if needed)

Create a Facade in your Laravel app app/Facades/Bot.php:

<?php

namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class Bot extends Facade
{
    protected static function getFacadeAccessor()
    {
        return \Mk4U\TGram\Bot::class;
    }
}

Then use: Bot::sendMessage([...])

🎯 Usage Examples

Send a Message

public function example(Bot $bot)
{
    $bot->sendMessage(
        chat_id:'123456789',
        text:'Hello World!'
    );
}

Send with Keyboard

public function withKeyboard(Bot $bot)
{
    use Mk4U\TGram\Core\Factories\InlineButton;

    $keyboard = Mk4U\TGram\Core\Factories\Keyboard::inline()
    ->row([
        Mk4U\TGram\Core\Factories\InlineButton::make('👥 Community')
        ->url('https://t.me/myGroup')
    ])->build();

    $bot->sendMessage(
        chat_id:'123456789',
        text:'Join my group!',
        reply_markup:$keyboard
    );
}

Answer Callback Query

public function handleCallback(Bot $bot)
{
    $bot->answerCallbackQuery(
        callback_query_id:$callback_query_id,
        text:'Action completed!'
    );
}

📚 Requirements

PHP 8.5+
Laravel 13.x+
TGram Library (automatically installed)

🆘 Support

📄 License

MIT License - see the LICENSE file for details.

Need help? Open an issue on GitHub or consult the TGram documentation.

mk4u / larabot

Maintainers

Package info

Statistics

Security