Defining a payload type

CallbackData is an abstract base. A subclass tags itself with #[CallbackPrefix('order')] and exposes constructor-promoted readonly properties. pack() walks the constructor's parameter list (not the property set) to build the wire string prefix:val1:val2:... . Iterating parameters guarantees field order matches across encode and decode, and excludes derived properties assigned in the constructor body — matching Pydantic's model_dump() semantic of "fields, not attributes".

use Gruven\PhpBotGram\Filters\CallbackData;
use Gruven\PhpBotGram\Filters\CallbackPrefix;

#[CallbackPrefix('order')]
final class OrderCallback extends CallbackData
{
    public function __construct(
        public readonly int    $id,
        public readonly string $action,
        public readonly bool   $deleted = false,
    ) {}
}

The type-encoding table is fixed: null → '' , bool → '1'/'0' , int|float → (string)$value , string → as-is , \Stringable → (string)$value , \UnitEnum → $value->value , anything else throws LogicException . Decoding does the inverse: a typed property constructor parameter drives the reverse coercion (?int parses back from the integer string, nullable types parse '' back to null , backed enums route through ::from ). The fixed table avoids the "what does this type encode to" question on a per-call basis — the choices are pinned to upstream aiogram/filters/callback_data.py verbatim.

MAX_CALLBACK_LENGTH = 64 enforces Telegram's wire-length cap. pack() measures with strlen — PHP strings are byte sequences and the protocol expects UTF-8, so byte-count equals UTF-8-byte-count when the input is valid UTF-8. Overflow throws LogicException , not InvalidArgumentException : a too-long callback payload is a programming error (you chose the field shape), not user input. The limit is hard-coded on Telegram's side; the framework cannot soften it without breaking the wire contract.

Packing a payload into a button

InlineKeyboardBuilder::button() accepts a CallbackData instance directly and calls pack() for you:

use Gruven\PhpBotGram\Types\Message;
use Gruven\PhpBotGram\Utils\Keyboard\InlineKeyboardBuilder;

// Pack a payload into a button.
$keyboard = (new InlineKeyboardBuilder())
    ->button('Confirm',  callbackData: new OrderCallback(id: 42, action: 'confirm'))
    ->button('Cancel',   callbackData: new OrderCallback(id: 42, action: 'cancel'))
    ->asMarkup();

// Attach to a reply.
// $event->answer('Pick an action:', replyMarkup: $keyboard)->emit();

Registering a handler and unpacking the payload

The matching filter is OrderCallback::filter() — a static factory that returns a CallbackQueryFilter configured to match the subclass's prefix. Handlers receive the unpacked object via the callback_data kwarg:

use Gruven\PhpBotGram\Dispatcher\Dispatcher;
use Gruven\PhpBotGram\Types\CallbackQuery;

$dispatcher = new Dispatcher();

// Register a handler that fires only for OrderCallback payloads.
$dispatcher->callbackQuery->register(
    static function (CallbackQuery $event, OrderCallback $callback_data): void {
        $event->answer("Order #{$callback_data->id} — {$callback_data->action}")->emit();
    },
    filters: [OrderCallback::filter()],
);

$callback_data is already unpacked — no manual CallbackData::unpack() call needed. The filter rejects any CallbackQuery whose data string does not begin with the order: prefix, so the handler only runs for well-shaped payloads.

The separator defaults to : but can be overridden via the attribute: #[CallbackPrefix('order', sep: '|')] . Choose the separator carefully — it cannot appear in any field's encoded value. For most bots the default colon is safe; bots that encode UUIDs or other string values that might contain colons should pick a separator unlikely to collide.