Add custom callback_data format.

Rename callback_data parameters.

Author: noplanman

README.md

@@ -38,6 +38,9 @@ $labels        = [              // optional. Change button labels (showing defau
     '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
@@ -46,6 +49,7 @@ $labels        = [              // optional. Change button labels (showing defau
 $ikp = new InlineKeyboardPagination($items, $command);
 $ikp->setMaxButtons(7, true); // Second parameter set to always show 7 buttons if possible.
 $ikp->setLabels($labels);
+$ikp->setCallbackDataFormat($callback_data_format);
 
 // Get pagination.
 $pagination = $ikp->getPagination($selected_page);
@@ -60,8 +64,8 @@ Now, `$pagination['keyboard']` is basically a row that contains the pagination.
 ```php
 // Use it in your request.
 if (!empty($pagination['keyboard'])) {
-    //$pagination['keyboard'][0]['callback_data']; // command=testCommand&currentPage=10&nextPage=1
-    //$pagination['keyboard'][1]['callback_data']; // command=testCommand&currentPage=10&nextPage=7
+    //$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' => [
@@ -73,17 +77,17 @@ if (!empty($pagination['keyboard'])) {
 }
 ```
 
-To get the callback data, you can use the provided helper method:
+To get the callback data, you can use the provided helper method (only works when using the default callback data format):
 ```php
 // e.g. Callback data.
-$callback_data = 'command=testCommand&currentPage=10&nextPage=1';
+$callback_data = 'command=testCommand&oldPage=10&newPage=1';
 
 $params = InlineKeyboardPagination::getParametersFromCallbackData($callback_data);
 
 //$params = [
-//    'command'     => 'testCommand',
-//    'currentPage' => '10',
-//    'nextPage'    => '1',
+//    'command' => 'testCommand',
+//    'oldPage' => '10',
+//    'newPage' => '1',
 //];
 
 // or, just use PHP directly if you like. (literally what the helper does!)

src/InlineKeyboardPagination.php

@@ -41,6 +41,11 @@ class InlineKeyboardPagination implements InlineKeyboardPaginator
      */
     private $command;
 
+    /**
+     * @var string
+     */
+    private $callback_data_format = 'command={COMMAND}&oldPage={OLD_PAGE}&newPage={NEW_PAGE}';
+
     /**
      * @var array
      */
@@ -68,6 +73,30 @@ public function setMaxButtons(int $max_buttons = 5, bool $force_button_count = f
         return $this;
     }
 
+    /**
+     * Get the current callback format.
+     *
+     * @return string
+     */
+    public function getCallbackDataFormat(): string
+    {
+        return $this->callback_data_format;
+    }
+
+    /**
+     * Set the callback_data format.
+     *
+     * @param string $callback_data_format
+     *
+     * @return InlineKeyboardPagination
+     */
+    public function setCallbackDataFormat(string $callback_data_format): InlineKeyboardPagination
+    {
+        $this->callback_data_format = $callback_data_format;
+
+        return $this;
+    }
+
     /**
      * Return list of keyboard button labels.
      *
@@ -315,7 +344,11 @@ protected function generateButton(int $page): array
      */
     protected function generateCallbackData(int $page): string
     {
-        return "command={$this->command}&currentPage={$this->selected_page}&nextPage={$page}";
+        return str_replace(
+            ['{COMMAND}', '{OLD_PAGE}', '{NEW_PAGE}'],
+            [$this->command, $this->selected_page, $page],
+            $this->callback_data_format
+        );
     }
 
     /**
@@ -337,7 +370,7 @@ protected function getOffset(): int
     }
 
     /**
-     * Get the parameters from the calback query.
+     * Get the parameters from the callback query.
      *
      * @param string $data
      *

tests/InlineKeyboardPaginationTest.php

@@ -75,6 +75,27 @@ public function testEmptyItemsConstructor()
         $ikp->getPagination();
     }
 
+    public function testCallbackDataFormat()
+    {
+        $ikp = new InlineKeyboardPagination(range(1, 10), 'cmd', 2, 5);
+
+        self::assertAllButtonPropertiesEqual([
+            [
+                'command=cmd&oldPage=2&newPage=1',
+                'command=cmd&oldPage=2&newPage=2',
+            ],
+        ], 'callback_data', [$ikp->getPagination()['keyboard']]);
+
+        $ikp->setCallbackDataFormat('{COMMAND};{OLD_PAGE};{NEW_PAGE}');
+
+        self::assertAllButtonPropertiesEqual([
+            [
+                'cmd;2;1',
+                'cmd;2;2',
+            ],
+        ], 'callback_data', [$ikp->getPagination()['keyboard']]);
+    }
+
     public function testCallbackDataParser()
     {
         $ikp  = new InlineKeyboardPagination($this->items, $this->command, $this->selected_page, $this->items_per_page);
@@ -83,9 +104,9 @@ public function testCallbackDataParser()
         $callback_data = $ikp::getParametersFromCallbackData($data['keyboard'][0]['callback_data']);
 
         self::assertSame([
-            'command'     => $this->command,
-            'currentPage' => "$this->selected_page",
-            'nextPage'    => '1', // because we're getting the button at position 0, which is page 1
+            'command' => $this->command,
+            'oldPage' => "$this->selected_page",
+            'newPage' => '1', // because we're getting the button at position 0, which is page 1
         ], $callback_data);
     }
 
@@ -121,9 +142,7 @@ public function testSetMaxButtons()
 
     public function testForceButtonsCount()
     {
-        $cbdata  = 'command=%s&currentPage=%d&nextPage=%d';
-        $command = 'cbdata';
-        $ikp     = new InlineKeyboardPagination(range(1, 10), $command, 1, 1);
+        $ikp = new InlineKeyboardPagination(range(1, 10), 'cbdata', 1, 1);
 
         // testing with 8 flexible buttons
         $ikp->setMaxButtons(8, false);
@@ -207,7 +226,7 @@ public function testInvalidItemsPerPage()
 
     public function testButtonLabels()
     {
-        $cbdata  = 'command=%s&currentPage=%d&nextPage=%d';
+        $cbdata  = 'command=%s&oldPage=%d&newPage=%d';
         $command = 'cbdata';
         $ikp1    = new InlineKeyboardPagination(range(1, 1), $command, 1, $this->items_per_page);
         $ikp10   = new InlineKeyboardPagination(range(1, $this->items_per_page * 10), $command, 1, $this->items_per_page);