Entities property of SendMessageMethod misses important comment

[wakebit]

Detailed description

When I'm building a new message via SendMessageMethod I'm passing an entities list that cannot be normalized by BotApiNormalizer. It just ignores them and still appears as an array instead of encoded json.

$buttonA = new InlineKeyboardButtonType();
$buttonA->callbackData = 'a';
$buttonA->text = 'A';

$buttonB = new InlineKeyboardButtonType();
$buttonB->callbackData = 'b';
$buttonB->text = 'B';

$inlineKeyboard = new InlineKeyboardMarkupType();
$inlineKeyboard->inlineKeyboard = [
    [$buttonA, $buttonB],
];

$messageEntity = new MessageEntityType();
$messageEntity->type = MessageEntityType::TYPE_TEXT_LINK;
$messageEntity->offset = 58;
$messageEntity->length = 23;
$messageEntity->url = 'https://google.com';

$sendMessage = new SendMessageMethod();
$sendMessage->chatId = '111222333';
$sendMessage->text = 'some text';
$sendMessage->replyMarkup = $inlineKeyboard;
$sendMessage->entities = [$messageEntity];

$this->botApi->send($sendMessage);

$normalizer = new BotApiNormalizer();
$normalizedRequest = $normalizer->normalize($sendMessage); // entities are not normalized at this step

And this method cannot be sent by the api client:

[2022-04-23 17:33:43] app.ERROR: Array to string conversion in /.../tg-bot-api/bot-api-base/src/ApiClient.php:106

Your environment

Include as many relevant details about the environment you experienced the bug in and how to reproduce it.

• Version used: PHP 8.1

[wakebit]

That works:

$sendMessage->replyMarkup = $inlineKeyboard; // InlineKeyboardMarkupType object
$sendMessage->entities = json_encode([$messageEntity]); // manually encoded array of MessageEntityType objects

I didn't know that array of objects should be encoded manually. I found this in the similar methods accepts array of objects.

// TgBotApi\BotApiBase\Method\AnswerShippingQueryMethod.php

/**
 * Optional. Required if ok is True. A JSON-serialized array of available shipping options.
 *
 * @var ShippingOption[]|null
 */
public $shippingOptions;

A JSON-serialized array of available shipping options.

But documentation for the entities property misses this:

// TgBotApi\BotApiBase\Method\SendMessageMethod.php

/**
 * Optional. List of special entities that appear in message text, which can be specified instead of parse_mode.
 *
 * @var MessageEntityType[]|null
 */
public $entities;

Also, the type of property should be string if it accepts encoded string?

psalm: $sendMessage->entities with declared type 'array<array-key, TgBotApi\BotApiBase\Type\MessageEntityType>|null' cannot be assigned type 'false|string'

[greenplugin]

I think it's bug in normalizer set. Will try to check soon