README

Installation
- Composer
Usage
- Test Data
- How To Use
Code Quality
License

Installation

Composer

composer require php-telegram-bot/inline-keyboard-pagination

Usage

Test Data

$items        = range(1, 100); // required. 
$command      = 'testCommand'; // optional. Default: pagination
$selectedPage = 10;            // optional. Default: 1
$labels       = [              // optional. Change button labels (showing defaults)
    'default'  => '%d',
    'first'    => '« %d',
    'previous' => '‹ %d',
    'current'  => '· %d ·',
    'next'     => '%d ›',
    'last'     => '%d »',
];

// optional. Change the callback_data format, adding placeholders for data (showing default)
$callbackDataFormat = 'command={COMMAND}&oldPage={OLD_PAGE}&newPage={NEW_PAGE}'

How To Use

// Define inline keyboard pagination.
$ikp = new InlineKeyboardPagination($items, $command);
$ikp->setMaxButtons(7, true); // Second parameter set to always show 7 buttons if possible.
$ikp->setLabels($labels);
$ikp->setCallbackDataFormat($callbackDataFormat);

// Get pagination.
$pagination = $ikp->getPagination($selectedPage);

// or, in 2 steps.
$ikp->setSelectedPage($selectedPage);
$pagination = $ikp->getPagination();

Now, $pagination['keyboard'] is basically a row that contains the pagination.

// Use it in your request.
if (!empty($pagination['keyboard'])) {
    //$pagination['keyboard'][0]['callback_data']; // command=testCommand&oldPage=10&newPage=1
    //$pagination['keyboard'][1]['callback_data']; // command=testCommand&oldPage=10&newPage=7
    
    ...
    $data['reply_markup'] = [
        'inline_keyboard' => [
            $pagination['keyboard'],
        ],
    ];
    ...
}

To get the callback data, you can use the provided helper method (only works when using the default callback data format):

// e.g. Callback data.
$callback_data = 'command=testCommand&oldPage=10&newPage=1';

$params = InlineKeyboardPagination::getParametersFromCallbackData($callbackData);

//$params = [
//    'command' => 'testCommand',
//    'oldPage' => '10',
//    'newPage' => '1',
//];

// or, just use PHP directly if you like. (literally what the helper does!)
parse_str($callbackData, $params);

Code Quality

Run the PHPUnit tests via Composer script.

composer test

License

The MIT License (MIT). Please see License File for more information.

Project based on Telegram Bot Pagination by lartie.

php-telegram-bot / inline-keyboard-pagination

Maintainers

Details