README

A keyboard builder for Telegram Api & Mtproto syntax

Installation

Install the package using composer:

composer require reymon/tg-keyboard

(back to top)

Usage

If you need to create a keyboard you can use the classes provided by this package as a drop-in replacement.

This is best explained with an example:

KeyboardMarkup::new()
        ->singleUse()
        ->addButton(KeyboardButton::Text('Cancel'))
        ->addButton(KeyboardButton::Text('OK'));

A ReplyKeyboardMarkup is created by calling the static new() method on KeyboardMarkup. After that every field, like singleUse, ... add some extras. Buttons can be added by calling the addButton() method. We have a detailed look on that later.

(back to top)

Defining a Keyboard

You can create a keyboard by calling the static new() method on its class.

After that you can chain methods to set additional fields that are available in the Bot API. This is done by calling the placeholder() method.

KeyboardMarkup::new()
    ->placeholder('Placeholder');

(back to top)

Defining Buttons

The Buttons are created in the different way:

$button = KeyboardButton::Phone('Send my Contact');
$button->getText();
$button->setText('Give me contact');

This is done the same way for InlineButton:

$button = InlineButton::Url('hello','https://example.com');
$button->getUrl();
$button->setUrl('github.com');

(back to top)

Bind Buttons to a Keyboard

The keyboard does not work without any buttons, so you need to pass the buttons to the keyboard. There are a few ways to do this.

By Row

KeyboardMarkup::new()
    ->row(
        KeyboardButton::Text('Cancel'),
        KeyboardButton::Text('OK')
    );

If you need more than one row, call row() multiple times:

KeyboardInline::new()
    ->row(
        InlineButton::Callback('1', 'page-1'),
        InlineButton::Callback('2', 'page-2'),
        InlineButton::Callback('3', 'page-3')
    )
    ->row(
        InlineButton::Callback('prev', 'page-prev'),
        InlineButton::Callback('next', 'page-next')
    );

You can add array of callbacks or texts keyboard in another way!

KeyboardInline::new()
    ->addCallbacks([
        '1' => 'page-1',
        '2' => 'page-2',
        '3' => 'page-3',
    ],[
        'prev' => 'page-prev',
        'next' => 'page-next'
    ]);

KeyboardMarkup::new()
    ->addTexts([
       'Cancel',
       'Ok'
    ]);

You can even use these methods

for InlineKeyboard:

• addCallback
• addCallbacks
• addCopyText
• addUrl
• addWebApp
• addLoginUrl
• addGame
• addBuy
• addSwitchInline
• addSwitchInlineCurrent
• addSwitchInlineFilter

and for ReplyKeyboard:

• addText
• addTexts
• addWebApp
• requestPoll
• requestPollQuiz
• requestPollRegular
• requestLocation
• requestPhone
• requestUsers
• requestGroup
• requestChannel

By Button

KeyboardMarkup::new()
    ->addButton(KeyboardButton::Text('First Button'))
    ->addButton(KeyboardButton::Text('Second Button'));

If you need more than one row, just call the row method without arguments, and continue calling addButton():

KeyboardInline::new()
    ->addButton(
        InlineButton::Callback('A','answer-a'),
        InlineButton::Callback('B','answer-b')
    )
    ->row()
    ->addButton(
        InlineButton::Callback('C', 'answer-c'),
        InlineButton::Callback('D', 'answer-d')
    );

It's up to you if you define your buttons inline like in these examples or if you'd like to generate a whole row beforehand and pass the variable to the row() method.

You can remove the last button by calling remove method here is an example :

KeyboardInline::new()
    ->addButton(InlineButton::Callback('A', 'answer-a'))
    ->addButton(InlineButton::Callback('B', 'answer-b'))
    ->row()
    ->addButton(InlineButton::Callback('C', 'answer-c'))
    ->addButton(InlineButton::Callback('D', 'answer-d'))
    ->remove();

In this example button D will remove from buttons.

By Coordinates

You can add button to each coordinates you want! (Note that coordinates start from 0 just like array indexes.) for example imagine we have this keyboard :

$keyboard = KeyboardInline::new()
    ->addButton(InlineButton::Callback('Numbers', 'Numbers'))
    ->addButton(InlineButton::Callback('Status', 'Status'))
    ->row()
    ->addButton(InlineButton::Callback('Add', 'Add'))
    ->addButton(InlineButton::Callback('Remove', 'Remove'));

we can add new button with it coordinates(raw and column) by calling addToCoordinates method. This methods will add new button in the coordinate that you passed and shift next buttons of the coordinates. This picture show you the position of new button :

$keyboard->addToCoordinates(0, 1, InlineButton::Callback('Middle','Middle'));

The results should like this image :

You can also replace into specific coordinates unlike addToCoordinates the replaceIntoCoordinates method will replace your new button into passed coordinate for example if we want to replace Add in this example like this picture :

we should use this code :

$keyboard->replaceIntoCoordinates(1, 0, InlineButton::Callback('Replaced Add','Add'));

The result should like this image :

You can also remove the button by it's coordinates for example if we want remove Add button(in last example) we should run this code:

$keyboard->removeFromCoordinates(1,0);

As Stack

If you want to add a bunch of buttons that have each a row for themselves you can use the Stack() method.

KeyboardInline::new()
    ->Stack(
        InlineButton::LoginUrl('Login','https://example.com/login'),
        InlineButton::Url('Visit Homepage','https://example.com')
    );

You can mix and match the row(), Stack() and addButton() methods as it fits your needs.

(back to top)

KeyboardForceReply and KeyboardHide

KeyboardForceReply and KeyboardHide can be used the same way as a normal keyboard, but they do not receive any buttons:

$keyboard = KeyboardHide::new();

KeyboardForceReply::new()
    ->addButton(KeyboardButton::Text('Hello please reply'))
    ->placeholder('must reply');

(back to top)

Keyboard Peer Type

We have 3 types of peer type can be requested by bots RequestUsers , RequestGroup and RequestChannel

KeyboardMarkup::new()
    ->addButton(KeyboardButton::PeerUsers('Request for user', 0, bot: false));

KeyboardMarkup::new()
    ->addButton(KeyboardButton::PeerGroup('Request for chat', 1));

KeyboardMarkup::new()
    ->addButton(KeyboardButton::PeerChannel('Request for channel', 2));

You can also use easier syntax to create better one

KeyboardMarkup::new()
    ->requestUsers('Request for user', 0);

KeyboardMarkup::new()
    ->requestGroup('Request for chat', 1);

KeyboardMarkup::new()
    ->requestChannel('Request for broadcast', 2);

(back to top)

Convert Keyboards

You can now easily convert telegram keyboards for modify and ... using fromBotApi or fromMtproto (for MadelineProto) methods!

Here is an example

(for now fromBotApi only accepts inline keyboards)

Telegram API

$keyboard = Keyboard::fromBotApi([
    "inline_keyboard": [
        [
            ["text" => "Callback data", "callback_data" => "Some data"]
        ],
        [
            [ "text" => "Hide keyboard", "callback_data" => "HIDE"]
        ]
    ]
]);
$keyboard->addButton(InlineButton::Callback('End','End'));
// Convert to mtproto syntax
$keyborad->toMtproto();

Mtproto

$keyboard = Keyboard::fromMtproto([
    '_' => 'replyInlineMarkup',
    'rows' => [
        [
            '_' => 'keyboardButtonRow',
            'buttons' => [
                ['_' => 'keyboardButtonCallback', 'text' => '1', 'data' => '0'],
                ['_' => 'keyboardButtonCallback', 'text' => '2', 'data' => '1'],
                ['_' => 'keyboardButtonCallback', 'text' => '🟢', 'data' => 'stat'],
                ['_' => 'keyboardButtonCallback', 'text' => '3', 'data' => '2'],
                ['_' => 'keyboardButtonCallback', 'text' => '4', 'data' => '3']
            ]
        ],
        [
            '_' => 'keyboardButtonRow',
            'buttons' => [
                ['_' => 'keyboardButtonCallback', 'text' => '10', 'data' => '9'],
                ['_' => 'keyboardButtonCallback', 'text' => '11', 'data' => '10'],
                ['_' => 'keyboardButtonCallback', 'text' => '12', 'data' => '11'],

            ]
        ],
        [
            '_' => 'keyboardButtonRow',
            'buttons' => [
                ['_' => 'keyboardButtonCallback','text' => '13', 'data' => '12'],
                ['_' => 'keyboardButtonCallback','text' => '14', 'data' => '13']
            ]
        ]
    ],
]);
$keyboard->addButton(InlineButton::Callback('15','14'));
// Convert to telegram api syntax
$keyborad->toApi();
json_encode($keyborad);

As you know $keyboard is object here and you can modify and add more buttons to it. Or event iterate it!:

foreach ($keyboard as $row) {
    foreach ($row as $button) {
        printf("Text: %s Callback: %s", $button->getText(), $button->getCallback());
    }
}

(back to top)