Bot API 7.3

README.md

@@ -1,6 +1,6 @@
 # PHP Wrapper for Telegram Bot API
 
-[![Bot Api 7.2](https://img.shields.io/badge/Bot%20API-7.2-0088cc.svg?style=flat)](https://core.telegram.org/bots/api-changelog#march-31-2024)
+[![Bot Api 7.3](https://img.shields.io/badge/Bot%20API-7.3-0088cc.svg?style=flat)](https://core.telegram.org/bots/api-changelog#may-6-2024)
 [![PHP >=8.2](https://img.shields.io/badge/PHP->=8.2-777bb3.svg?style=flat)](https://www.php.net/releases/8.2/en.php)
 [![Tests Status](https://img.shields.io/github/actions/workflow/status/luzrain/telegram-bot-api/tests.yaml?branch=master)](../../actions/workflows/tests.yaml)
 

src/Method/EditMessageLiveLocation.php

@@ -48,6 +48,15 @@ public function __construct(
          */
         protected string|null $inlineMessageId = null,
 
+        /**
+         * New period in seconds during which the location can be updated, starting from the message send date.
+         * If 0x7FFFFFFF is specified, then the location can be updated forever.
+         * Otherwise, the new value must not exceed the current live_period by more than a day,
+         * and the live location expiration date must remain within the next 90 days.
+         * If not specified, then live_period remains unchanged
+         */
+        protected int|null $livePeriod = null,
+
         /**
          * The radius of uncertainty for the location, measured in meters; 0-1500
          */

src/Method/GetChat.php

@@ -5,19 +5,18 @@
 namespace Luzrain\TelegramBotApi\Method;
 
 use Luzrain\TelegramBotApi\Method;
-use Luzrain\TelegramBotApi\Type\Chat;
+use Luzrain\TelegramBotApi\Type\ChatFullInfo;
 
 /**
- * Use this method to get up to date information about the chat (current name of the user for one-on-one conversations,
- * current username of a user, group or channel, etc.).
- * Returns a Chat object on success.
+ * Use this method to get up-to-date information about the chat.
+ * Returns a ChatFullInfo object on success.
  *
- * @extends Method<Chat>
+ * @extends Method<ChatFullInfo>
  */
 final class GetChat extends Method
 {
     protected static string $methodName = 'getChat';
-    protected static string $responseClass = Chat::class;
+    protected static string $responseClass = ChatFullInfo::class;
 
     public function __construct(
         /**

src/Method/SendPoll.php

@@ -7,6 +7,7 @@
 use Luzrain\TelegramBotApi\Method;
 use Luzrain\TelegramBotApi\Type\ForceReply;
 use Luzrain\TelegramBotApi\Type\InlineKeyboardMarkup;
+use Luzrain\TelegramBotApi\Type\InputPollOption;
 use Luzrain\TelegramBotApi\Type\Message;
 use Luzrain\TelegramBotApi\Type\MessageEntity;
 use Luzrain\TelegramBotApi\Type\ReplyKeyboardMarkup;
@@ -38,11 +39,26 @@ public function __construct(
         protected string $question,
 
         /**
-         * A JSON-serialized list of answer options, 2-10 strings 1-100 characters each
-         * Array of String
+         * A JSON-serialized list of 2-10 answer options
+         *
+         * @var list<InputPollOption>
          */
         protected array $options,
 
+        /**
+         * Mode for parsing entities in the question. See formatting options for more details. Currently, only custom emoji entities are allowed
+         *
+         * @see https://core.telegram.org/bots/api#formatting-options
+         */
+        protected string|null $questionParseMode = null,
+
+        /**
+         * A JSON-serialized list of special entities that appear in the poll question. It can be specified instead of question_parse_mode
+         *
+         * @var list<MessageEntity>|null
+         */
+        protected array|null $questionEntities = null,
+
         /**
          * Unique identifier of the business connection on behalf of which the message will be sent
          */

src/Method/SendVoice.php

@@ -15,8 +15,9 @@
 
 /**
  * Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message.
- * For this to work, your audio must be in an .OGG file encoded with OPUS (other formats may be sent as Audio or Document).
- * On success, the sent Message is returned. Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the future.
+ * For this to work, your audio must be in an .OGG file encoded with OPUS, or in .MP3 format, or in .M4A format
+ * (other formats may be sent as Audio or Document). On success, the sent Message is returned.
+ * Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the future.
  *
  * @extends Method<Message>
  */

src/Type/BackgroundFill.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+use Luzrain\TelegramBotApi\Type;
+
+/**
+ * This object describes the way a background is filled based on the selected colors. Currently, it can be one of
+ *
+ * @see BackgroundFillSolid
+ * @see BackgroundFillGradient
+ * @see BackgroundFillFreeformGradient
+ */
+readonly class BackgroundFill extends Type
+{
+    protected function __construct(
+        /**
+         * Type of the background
+         */
+        public string $type,
+    ) {
+    }
+
+    /**
+     * @psalm-suppress LessSpecificReturnStatement
+     * @psalm-suppress MoreSpecificReturnType
+     */
+    public static function fromArray(array $data): static
+    {
+        /** @var self $instance */
+        $instance = parent::fromArray($data);
+
+        return self::class !== static::class ? $instance : match ($instance->type) {
+            BackgroundFillSolid::TYPE => BackgroundFillSolid::fromArray($data),
+            BackgroundFillGradient::TYPE => BackgroundFillGradient::fromArray($data),
+            BackgroundFillFreeformGradient::TYPE => BackgroundFillFreeformGradient::fromArray($data),
+        };
+    }
+}

src/Type/BackgroundFillFreeformGradient.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+/**
+ * The background is a freeform gradient that rotates after every message in the chat.
+ */
+final readonly class BackgroundFillFreeformGradient extends BackgroundFill
+{
+    public const TYPE = 'freeform_gradient';
+
+    public function __construct(
+        /**
+         * A list of the 3 or 4 base colors that are used to generate the freeform gradient in the RGB24 format
+         *
+         * @var list<int>
+         */
+        public array $colors,
+    ) {
+        parent::__construct(self::TYPE);
+    }
+}

src/Type/BackgroundFillGradient.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+/**
+ * The background is a gradient fill.
+ */
+final readonly class BackgroundFillGradient extends BackgroundFill
+{
+    public const TYPE = 'gradient';
+
+    public function __construct(
+        /**
+         * Top color of the gradient in the RGB24 format
+         */
+        public int $topColor,
+
+        /**
+         * Bottom color of the gradient in the RGB24 format
+         */
+        public int $bottomColor,
+
+        /**
+         * Clockwise rotation angle of the background fill in degrees; 0-359
+         */
+        public int $rotationAngle,
+    ) {
+        parent::__construct(self::TYPE);
+    }
+}

src/Type/BackgroundFillSolid.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+/**
+ * The background is filled using the selected color.
+ */
+final readonly class BackgroundFillSolid extends BackgroundFill
+{
+    public const TYPE = 'solid';
+
+    public function __construct(
+        /**
+         * The color of the background fill in the RGB24 format
+         */
+        public int $color,
+    ) {
+        parent::__construct(self::TYPE);
+    }
+}

src/Type/BackgroundType.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+use Luzrain\TelegramBotApi\Type;
+
+/**
+ * This object describes the type of a background. Currently, it can be one of
+ *
+ * @see BackgroundTypeFill
+ * @see BackgroundTypeWallpaper
+ * @see BackgroundTypePattern
+ * @see BackgroundTypeChatTheme
+ */
+readonly class BackgroundType extends Type
+{
+    protected function __construct(
+        /**
+         * Type of the background
+         */
+        public string $type,
+    ) {
+    }
+
+    /**
+     * @psalm-suppress LessSpecificReturnStatement
+     * @psalm-suppress MoreSpecificReturnType
+     */
+    public static function fromArray(array $data): static
+    {
+        /** @var self $instance */
+        $instance = parent::fromArray($data);
+
+        return self::class !== static::class ? $instance : match ($instance->type) {
+            BackgroundTypeFill::TYPE => BackgroundTypeFill::fromArray($data),
+            BackgroundTypeWallpaper::TYPE => BackgroundTypeWallpaper::fromArray($data),
+            BackgroundTypePattern::TYPE => BackgroundTypePattern::fromArray($data),
+            BackgroundTypeChatTheme::TYPE => BackgroundTypeChatTheme::fromArray($data),
+        };
+    }
+}

src/Type/BackgroundTypeChatTheme.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+/**
+ * The background is taken directly from a built-in chat theme.
+ */
+final readonly class BackgroundTypeChatTheme extends BackgroundType
+{
+    public const TYPE = 'chat_theme';
+
+    public function __construct(
+        /**
+         * Document with the pattern
+         */
+        public Document $document,
+
+        /**
+         * Name of the chat theme, which is usually an emoji
+         */
+        public string $themeName,
+    ) {
+        parent::__construct(self::TYPE);
+    }
+}

src/Type/BackgroundTypeFill.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+/**
+ * The background is automatically filled based on the selected colors.
+ */
+final readonly class BackgroundTypeFill extends BackgroundType
+{
+    public const TYPE = 'fill';
+
+    public function __construct(
+        /**
+         * The background fill
+         */
+        public BackgroundFill $fill,
+
+        /**
+         * Dimming of the background in dark themes, as a percentage; 0-100
+         */
+        public int $darkThemeDimming,
+    ) {
+        parent::__construct(self::TYPE);
+    }
+}

src/Type/BackgroundTypePattern.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Luzrain\TelegramBotApi\Type;
+
+/**
+ * The background is a PNG or TGV (gzipped subset of SVG with MIME type "application/x-tgwallpattern")
+ * pattern to be combined with the background fill chosen by the user.
+ */
+final readonly class BackgroundTypePattern extends BackgroundType
+{
+    public const TYPE = 'pattern';
+
+    public function __construct(
+        /**
+         * Document with the pattern
+         */
+        public Document $document,
+
+        /**
+         * The background fill that is combined with the pattern
+         */
+        public BackgroundFill $fill,
+
+        /**
+         * Intensity of the pattern when it is shown above the filled background; 0-100
+         */
+        public int $intensity,
+
+        /**
+         * Optional. True, if the background fill must be applied only to the pattern itself.
+         * All other pixels are black in this case. For dark themes only
+         */
+        public true|null $isInverted = null,
+
+        /**
+         * Optional. True, if the background moves slightly when the device is tilted
+         */
+        public true|null $isMoving = null,
+    ) {
+        parent::__construct(self::TYPE);
+    }
+}