Handling Updates

When the bot receives an update, the library passes it through a pipline of registered handlers. Each handler must check if it should handle the update and may optionally stop further processing.

The library supports two ways to handle updates:

Use closures for simple tasks to keep your codebase clean:

php

$handler = function(TeleBot $bot, Update $update, $next) {
    if ($update->message->text === '/start') {
        return $bot->sendMessage(
            chat_id: $update->chat()->id,
            text: 'Hello, World!'
        );
    }

    return $next();
};

Registering Handlers

Handlers must be registered in your bot instance:

php

$bot = new TeleBot([
    'token' => '<your bot token>',
    'kernrel' => [
        \App\YourUpdateHandler::class,
        $handler
    ]
]);

// Or add later
$bot->handler(\App\YourUpdateHandler::class);
$bot->handler($handler);

Custom Kernel

Customize the handling pipeline by extending Kernel.

php

<?php

namespace App;

use WeStacks\TeleBot\Kernel as TeleBotKernel;
use WeStacks\TeleBot\TeleBot;

class Kernel extends TeleBotKernel
{
    public function __construct()
    {
        parent::__construct([
            \App\YourUpdateHandler::class,
        ]);
    }

    public function setCommands(TeleBot $bot)
    {
        return $bot->setMyCommands([
            'commands' => $this->getLocalCommands(),
            'scope' => 'default'
        ]);
    }

    public function deleteCommands(TeleBot $bot)
    {
        return $bot->deleteMyCommands([
            'scope' => 'default'
        ]);
    }
}

php

$bot = new TeleBot([
    'token' => '<your bot token>',
    'kernel' => \App\Kernel::class
]);

Bot Commands

The library provides a CommandHandler for handling bot commands efficiently.

php

<?php

namespace App;

use WeStacks\TeleBot\Foundation\CommandHandler;

class StartCommand extends CommandHandler
{
    protected static function aliases(): array
    {
        return ['/start', '/s'];
    }
    protected static function description(?string $locale = null): string
    {
        return trans('Start the bot', locale: $locale);
    }

    public function handle()
    {
        return $this->sendMessage([
            'text' => 'Hello, World!'
        ]);
    }
}

Requesting User Input

The library has a built-in state storage for requesting user input via RequestInputHandler. By default it will handle any update given by the user. You can change this behavior by extending trigger() method in your handler.

php

<?php

namespace App;

use WeStacks\TeleBot\Foundation\RequestInputHandler;

class AskNameHandler extends RequestInputHandler
{
    public function handle()
    {
        $data = $this->update->message()->toArray();

        $validator = Validator::make($data, [
            'text' => 'required|string|max:255'
        ]);

        if ($validator->fails()) {
            return $this->sendMessage([
                'text' => 'Invalid input!'
            ]);
        }

        $this->accept();

        $name = $validator->validated()['text'];

        return $this->sendMessage([
            'text' => "Hello, $name!",
        ]);
    }
}

Custom State Storage

Default: WeStacks\TeleBot\Foundation\FileStorage. You can use Redis, database, or your own.

php

<?php

namespace App;

use App\Models\User;
use WeStacks\TeleBot\Contracts\StorageContract;

class DatabaseStorage implements StorageContract
{
    public function get(string $key, $default = null): mixed
    {
        return User::where('telegram_id', $key)->value('input_state') ?? $default;
    }

    public function set(string $key, $value): true
    {
        return User::where('telegram_id', $key)->update(['input_state' => $value]);
    }

    public function delete(string $key): true
    {
        return $this->set($key, null);
    }
}

Callback Queries

Use CallbackHandler for managing callback queries.

php

<?php

namespace App;

use WeStacks\TeleBot\Foundation\CallbackHandler;

class ButtonPressHandler extends CallbackHandler
{
    protected string $match = "/^test:(delete|update):(\d+)$/";

    public function handle()
    {
        [$action, $id] = $this->arguments();

        match ($action) {
            'update' => $this->update($id),
            'delete' => $this->delete($id),
        };

        $this->answerCallbackQuery();
    }
}