README.md

Telegram Bot Inline Keyboard Pagination

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

Installation

Composer

composer require php-telegram-bot/inline-keyboard-pagination:^1.0.0

Usage

Test Data

$items         = range(1, 100); // required. 
$command       = 'testCommand'; // optional. Default: pagination
$selected_page = 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)
$callback_data_format = '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->setRangeOffset(1); //optional: if you change offsets of selected page, you can use this method. e.g if selected page is 6 and Range offset set as 1, you will have 5 & 7 in pagination
$ikp->setLabels($labels);

/*
 *optional: But recommended. if you want that max_page will set according to labels you defined,
 * please call this method. if you remove $label elements and then call this method, max_page will be defined according to labels
 */
$ikp->setMaxButtonsBasedOnLabels();
$ikp->setCallbackDataFormat($callback_data_format);

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

// or, in 2 steps.
$ikp->setSelectedPage($selected_page);
$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($callback_data);

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

// or, just use PHP directly if you like. (literally what the helper does!)
parse_str($callback_data, $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.