README

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

🚀 Features

Artisan Commands: Use xBot 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 al3x5/xbot-laravel

⚡ Quick Start

1. Install and Configure

php artisan xbot

This command will:

Configure the Laravel API (Sanctum)
Publish the xBot 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 xbot:register

4. Configure Webhook

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

5. Create Your Commands

php artisan xbot:telegram:command HelloWorld

🛠 Available Commands

Command	Description
`php artisan xbot`	Install and configure xBot
`php artisan xbot:register`	Register all commands and callbacks
`php artisan xbot:hook:set <url>`	Set webhook URL
`php artisan xbot:hook:delete`	Delete webhook
`php artisan xbot:hook:info`	Get webhook info
`php artisan xbot:hook:about`	Get bot info
`php artisan xbot:telegram:command <name>`	Create new command
`php artisan xbot:telegram:callback <name> <action>`	Create new callback handler
`php artisan xbot:telegram:conversation <name>`	Create new conversation
`php artisan xbot:telegram:handler <name>`	Create new handler
`php artisan xbot:telegram: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)
BOT_WEBHOOK_URL=https://yourdomain.com/bot (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.
BOT_WEBHOOK_URL — Public URL where Telegram will send updates. Only needed if using webhook instead of polling. 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('xbot')->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 Al3x5\xBot\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 Al3x5\xBot\Bot;

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

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

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

Note: Always use app('xbot') 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 \Al3x5\xBot\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 Al3x5\xBot\Telegram\Factorys\InlineButton;
    use ;

    $keyboard = Al3x5\xBot\Telegram\Factorys\Keyboard::inline()
    ->row([
        Al3x5\xBot\Telegram\Factorys\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.2+
Laravel 12.x
xBot Library v4 (automatically installed)

🆘 Support

📄 License

MIT License - see the LICENSE file for details.

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

al3x5 / xbot-laravel

Maintainers

Package info

Statistics

Security