KeyboardBuilder
in package
Abstract builder that manages a two-dimensional button grid.
Port of upstream aiogram/utils/keyboard.py — KeyboardBuilder class.
The concrete subclasses bind T via a @extends PHPDoc tag on the subclass
itself (e.g. @extends KeyboardBuilder<InlineKeyboardButton>).
Tags
Table of Contents
Constants
- MAX_BUTTONS : int = 0
- Maximum total number of buttons. 0 means no cap.
- MAX_WIDTH : int = 0
- Maximum number of buttons per row. 0 means no row-width limit.
- MIN_WIDTH : int = 1
- Minimum acceptable row width for `adjust()` size validation.
Properties
- $buttonType : string
- $markup : array<int, array<int, T>>
- Internal two-dimensional markup storage.
Methods
- __construct() : mixed
- add() : static
- Flow buttons into rows. When `MAX_WIDTH` is 0, each call appends a new row containing all the given buttons (no row-fill; matches upstream `keyboard.py` behaviour for `max_width == 0`). When `MAX_WIDTH` is positive, the last incomplete row is filled first, then remaining buttons are chunked into full rows of that width.
- adjust() : static
- Reshape all buttons into rows of the given widths. The last size is repeated for any remaining buttons (upstream `repeat=False` default).
- adjustRepeating() : static
- Reshape all buttons into rows of the given widths, cycling through the size list (upstream `repeat=True` variant).
- asMarkup() : InlineKeyboardMarkup|ReplyKeyboardMarkup
- Wrap the internal markup in the concrete Markup DTO.
- attach() : static
- Concatenate another builder's markup onto this one.
- buttons() : Generator<int, T>
- Flatten all buttons into a single iterator.
- export() : array<int, array<int, T>>
- Return a deep copy of the internal markup.
- row() : static
- Append buttons as one or more new rows.
- validateButton() : void
- Assert that a button is an instance of `$buttonType`.
- validateMarkup() : void
- Assert that every row in a markup array is a list of valid buttons, and that the total button count does not exceed `MAX_BUTTONS`.
- doAdjust() : static
- Shared implementation for `adjust()` and `adjustRepeating()`.
- enforceMaxButtons() : void
- Throw if the total button count across all rows now exceeds `MAX_BUTTONS`.
Constants
MAX_BUTTONS
Maximum total number of buttons. 0 means no cap.
public
int
MAX_BUTTONS
= 0
MAX_WIDTH
Maximum number of buttons per row. 0 means no row-width limit.
public
int
MAX_WIDTH
= 0
MIN_WIDTH
Minimum acceptable row width for `adjust()` size validation.
public
int
MIN_WIDTH
= 1
Properties
$buttonType read-only
protected
string
$buttonType
$markup
Internal two-dimensional markup storage.
protected
array<int, array<int, T>>
$markup
= []
Methods
__construct()
public
__construct(T> $buttonType[, null|array<int, array<int, T>> $markup = null ]) : mixed
Parameters
- $buttonType : T>
- $markup : null|array<int, array<int, T>> = null
-
Pre-existing rows (deep-cloned on write).
add()
Flow buttons into rows. When `MAX_WIDTH` is 0, each call appends a new row containing all the given buttons (no row-fill; matches upstream `keyboard.py` behaviour for `max_width == 0`). When `MAX_WIDTH` is positive, the last incomplete row is filled first, then remaining buttons are chunked into full rows of that width.
public
add(T ...$buttons) : static
Parameters
- $buttons : T
Return values
staticadjust()
Reshape all buttons into rows of the given widths. The last size is repeated for any remaining buttons (upstream `repeat=False` default).
public
adjust(int ...$sizes) : static
Pass no arguments to default to [MAX_WIDTH].
Parameters
- $sizes : int
Return values
staticadjustRepeating()
Reshape all buttons into rows of the given widths, cycling through the size list (upstream `repeat=True` variant).
public
adjustRepeating(int ...$sizes) : static
Parameters
- $sizes : int
Return values
staticasMarkup()
Wrap the internal markup in the concrete Markup DTO.
public
abstract asMarkup() : InlineKeyboardMarkup|ReplyKeyboardMarkup
Subclasses narrow this return type to the specific Markup they produce:
InlineKeyboardMarkup or ReplyKeyboardMarkup.
Return values
InlineKeyboardMarkup|ReplyKeyboardMarkupattach()
Concatenate another builder's markup onto this one.
public
attach(KeyboardBuilder<string|int, T> $other) : static
Both builders must have the same $buttonType — a mismatch throws
InvalidArgumentException to mirror upstream's type validation.
Parameters
- $other : KeyboardBuilder<string|int, T>
Tags
Return values
staticbuttons()
Flatten all buttons into a single iterator.
public
buttons() : Generator<int, T>
Return values
Generator<int, T>export()
Return a deep copy of the internal markup.
public
export() : array<int, array<int, T>>
Return values
array<int, array<int, T>>row()
Append buttons as one or more new rows.
public
row(array<int, T> $buttons[, int|null $width = null ]) : static
When $width is null, the effective width defaults to MAX_WIDTH
(upstream keyboard.py parity: width = self.max_width). When
MAX_WIDTH is 0 and $width is null, all buttons go into a single
row (no width limit). An explicit $width > 0 overrides the default
but is capped to MAX_WIDTH when that constant is positive.
Parameters
- $buttons : array<int, T>
- $width : int|null = null
Return values
staticvalidateButton()
Assert that a button is an instance of `$buttonType`.
protected
validateButton(object $button) : void
Parameters
- $button : object
Tags
validateMarkup()
Assert that every row in a markup array is a list of valid buttons, and that the total button count does not exceed `MAX_BUTTONS`.
protected
validateMarkup(array<int, array<int, T>> $markup) : void
Parameters
- $markup : array<int, array<int, T>>
Tags
doAdjust()
Shared implementation for `adjust()` and `adjustRepeating()`.
private
doAdjust(bool $repeat, int ...$sizes) : static
Parameters
- $repeat : bool
- $sizes : int
Return values
staticenforceMaxButtons()
Throw if the total button count across all rows now exceeds `MAX_BUTTONS`.
private
enforceMaxButtons() : void
Called after every mutation that can increase the button count (add()
and the constructor path through validateMarkup()).