Pass JSON-encoded strings to TransportInterface::postWithFiles() instead of scalars

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Telegram Bot API for PHP Change Log
 
+## 0.20 April 23, 2026
+
+- Chg #197: `$data` parameter type in `TransportInterface::postWithFiles()` changed from `array<string, scalar>`
+  to `array<string, string>`: non-string values are passed already JSON-encoded.
+
 ## 0.19 April 18, 2026
 
 - New #195: Add `InputFile::filename()` and `InputFile::extension()` methods.

src/Api.php

@@ -153,7 +153,7 @@ private function sendPostRequest(string $url, array $data): ApiResponse
         }
 
         $data = array_map(
-            static fn(mixed $value) => is_scalar($value) ? $value : json_encode($value, JSON_THROW_ON_ERROR),
+            static fn(mixed $value) => is_string($value) ? $value : json_encode($value, JSON_THROW_ON_ERROR),
             $data,
         );
 

src/Transport/NativeTransport.php

@@ -11,7 +11,6 @@
 
 use function file_get_contents;
 use function is_string;
-use function json_encode;
 
 /**
  * @see https://www.php.net/manual/function.file-get-contents.php
@@ -123,7 +122,7 @@ static function (int $errorNumber, string $errorString): bool {
     }
 
     /**
-     * @psalm-param array<string, mixed> $data
+     * @psalm-param array<string, string> $data
      * @psalm-param array<string, InputFile> $files
      */
     private function buildMultipartFormData(array $data, array $files, string $boundary): string
@@ -134,7 +133,7 @@ private function buildMultipartFormData(array $data, array $files, string $bound
             $result[] = "--$boundary";
             $result[] = "Content-Disposition: form-data; name=\"$key\"";
             $result[] = '';
-            $result[] = is_string($value) ? $value : json_encode($value, JSON_THROW_ON_ERROR);
+            $result[] = $value;
         }
 
         foreach ($files as $key => $file) {

src/Transport/TransportInterface.php

@@ -41,12 +41,13 @@ public function post(string $url, string $body, array $headers): ApiResponse;
      * Performs a POST request with file uploads.
      *
      * @param string $url The URL to request.
-     * @param (bool|string|int|float)[] $data The form data fields as an associative array (field name => field value).
+     * @param string[] $data The form data fields as an associative array (field name => field value). All values are
+     * strings: plain strings are passed as-is, non-string values (integers, booleans, arrays) are JSON-encoded.
      * @param InputFile[] $files The files to upload as an associative array (field name => `InputFile`).
      *
      * @return ApiResponse The API response.
      *
-     * @psalm-param array<string, scalar> $data
+     * @psalm-param array<string, string> $data
      * @psalm-param array<string, InputFile> $files
      */
     public function postWithFiles(string $url, array $data, array $files): ApiResponse;

tests/Transport/NativeTransport/NativeTransportTest.php

@@ -157,7 +157,7 @@ public function testPostWithFiles(): void
         $transport->postWithFiles(
             'http://url/method',
             [
-                'ages' => [23, 45],
+                'ages' => '[23,45]',
             ],
             [
                 'file1' => new InputFile(__DIR__ . '/test.txt'),