phpbotgram

MediaGroupBuilder
in package

FinalYes

Fluent builder for Telegram media groups.

Port of upstream aiogram/utils/media_group.py — MediaGroupBuilder class.

Telegram media-group homogeneity rules:

  • Photo and Video items may coexist in the same group.
  • Audio items must form a homogeneous group (no mixing with other types).
  • Document items must form a homogeneous group (no mixing with other types).

Usage:

$builder = new MediaGroupBuilder(caption: 'My album');
$builder->addPhoto('file_id_1')->addPhoto('file_id_2')->addVideo('file_id_3');
$mediaList = $builder->build();

Table of Contents

Constants

MAX_MEDIA_GROUP_SIZE  : int = 10
Maximum number of items in a Telegram media group.

Properties

$caption  : string|null
$captionEntities  : array<string|int, mixed>|null
$media  : array<int, InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo>

Methods

__construct()  : mixed
addAudio()  : static
Add an audio file to the media group.
addDocument()  : static
Add a document to the media group.
addPhoto()  : static
Add a photo to the media group.
addVideo()  : static
Add a video to the media group.
build()  : array<int, InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo>
Build and return the assembled media list.
append()  : static
Append a media item to the internal list after validating homogeneity and group-size constraints.
copy()  : InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo
Return a shallow copy of an item (all constructor args preserved as-is).
copyWithCaption()  : InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo
Return a copy of an item with `caption`, `captionEntities`, and `parseMode` overridden. Used by `build()` to inject the builder-level caption into the first item.
groupType()  : string
Infer the "type class" of the current group from the first element.
validateHomogeneity()  : void
Enforce Telegram's media-group homogeneity rules against the existing items in `$this->media`:

Constants

MAX_MEDIA_GROUP_SIZE

Maximum number of items in a Telegram media group.

public int MAX_MEDIA_GROUP_SIZE = 10

Properties

$captionEntities read-only

private array<string|int, mixed>|null $captionEntities = null

Methods

__construct()

public __construct([string|null $caption = null ][, null|array<int, MessageEntity> $captionEntities = null ][, null|array<int, InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo> $media = null ]) : mixed
Parameters
$caption : string|null = null
$captionEntities : null|array<int, MessageEntity> = null
$media : null|array<int, InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo> = null

Optional list of media items to pre-populate the builder. Each item is appended via the same validation path as addPhoto/addVideo/etc. Mirrors upstream: def __init__(self, *, caption=None, caption_entities=None, media=None).

addAudio()

Add an audio file to the media group.

public addAudio(InputFile|string $media[, InputFile|null $thumbnail = null ][, string|null $caption = null ][, BotDefault|string|null $parseMode = new BotDefault('parse_mode') ][, null|array<int, MessageEntity> $captionEntities = null ][, int|null $duration = null ][, string|null $performer = null ][, string|null $title = null ]) : static
Parameters
$media : InputFile|string
$thumbnail : InputFile|null = null
$caption : string|null = null
$parseMode : BotDefault|string|null = new BotDefault('parse_mode')
$captionEntities : null|array<int, MessageEntity> = null
$duration : int|null = null
$performer : string|null = null
$title : string|null = null
Return values
static

addDocument()

Add a document to the media group.

public addDocument(InputFile|string $media[, InputFile|null $thumbnail = null ][, string|null $caption = null ][, BotDefault|string|null $parseMode = new BotDefault('parse_mode') ][, null|array<int, MessageEntity> $captionEntities = null ][, bool|null $disableContentTypeDetection = null ]) : static
Parameters
$media : InputFile|string
$thumbnail : InputFile|null = null
$caption : string|null = null
$parseMode : BotDefault|string|null = new BotDefault('parse_mode')
$captionEntities : null|array<int, MessageEntity> = null
$disableContentTypeDetection : bool|null = null
Return values
static

addPhoto()

Add a photo to the media group.

public addPhoto(InputFile|string $media[, string|null $caption = null ][, BotDefault|string|null $parseMode = new BotDefault('parse_mode') ][, null|array<int, MessageEntity> $captionEntities = null ][, bool|BotDefault|null $showCaptionAboveMedia = new BotDefault('show_caption_above_media') ][, bool|null $hasSpoiler = null ]) : static
Parameters
$media : InputFile|string
$caption : string|null = null
$parseMode : BotDefault|string|null = new BotDefault('parse_mode')
$captionEntities : null|array<int, MessageEntity> = null
$showCaptionAboveMedia : bool|BotDefault|null = new BotDefault('show_caption_above_media')
$hasSpoiler : bool|null = null
Return values
static

addVideo()

Add a video to the media group.

public addVideo(InputFile|string $media[, InputFile|null $thumbnail = null ][, string|null $caption = null ][, BotDefault|string|null $parseMode = new BotDefault('parse_mode') ][, null|array<int, MessageEntity> $captionEntities = null ][, bool|BotDefault|null $showCaptionAboveMedia = new BotDefault('show_caption_above_media') ][, int|null $width = null ][, int|null $height = null ][, int|null $duration = null ][, bool|null $supportsStreaming = null ][, bool|null $hasSpoiler = null ]) : static
Parameters
$media : InputFile|string
$thumbnail : InputFile|null = null
$caption : string|null = null
$parseMode : BotDefault|string|null = new BotDefault('parse_mode')
$captionEntities : null|array<int, MessageEntity> = null
$showCaptionAboveMedia : bool|BotDefault|null = new BotDefault('show_caption_above_media')
$width : int|null = null
$height : int|null = null
$duration : int|null = null
$supportsStreaming : bool|null = null
$hasSpoiler : bool|null = null
Return values
static

build()

Build and return the assembled media list.

public build() : array<int, InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo>

If the builder-level $caption is non-null, it is injected into the first item together with $captionEntities. When only $captionEntities is set but $caption is null, the first item's own caption is left untouched — matching upstream aiogram:

if self.caption is not None:
    media[0].caption = self.caption
    media[0].caption_entities = self.caption_entities

The returned list is independent from the builder's internal state (items are new instances), so the builder can be reused after a call to build().

Tags
throws
LogicException

if the media list is empty.

Return values
array<int, InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo>

append()

Append a media item to the internal list after validating homogeneity and group-size constraints.

private append(InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo $item) : static
Parameters
$item : InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo
Tags
throws
InvalidArgumentException

if the new item breaks the homogeneity rule for the current group.

InvalidArgumentException

if the group is already at MAX_MEDIA_GROUP_SIZE.

Return values
static

copyWithCaption()

Return a copy of an item with `caption`, `captionEntities`, and `parseMode` overridden. Used by `build()` to inject the builder-level caption into the first item.

private copyWithCaption(InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo $item, string|null $caption, null|array<int, MessageEntity> $captionEntities, BotDefault|string|null $parseMode) : InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo
Parameters
$item : InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo
$caption : string|null
$captionEntities : null|array<int, MessageEntity>
$parseMode : BotDefault|string|null
Return values
InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo

groupType()

Infer the "type class" of the current group from the first element.

private groupType() : string

Returns 'photo_video', 'audio', or 'document'.

Return values
string

validateHomogeneity()

Enforce Telegram's media-group homogeneity rules against the existing items in `$this->media`:

private validateHomogeneity(InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo $incoming) : void
  • Photo + Video may coexist.
  • Audio must not be mixed with any other type.
  • Document must not be mixed with any other type.
Parameters
$incoming : InputMediaAudio|InputMediaDocument|InputMediaPhoto|InputMediaVideo
Tags
throws
InvalidArgumentException

on a type conflict.

On this page

Search results