chargebee · cb-alish · Jan 20, 2026 · Jan 19, 2026 · Jan 19, 2026 · Jan 20, 2026
diff --git a/.github/workflows/phpunit.yml b/.github/workflows/phpunit.yml
@@ -0,0 +1,40 @@
+name: PHPUnit
+
+on:
+  pull_request:
+    branches: ["**"]
+  push:
+    branches: ["master"]
+
+permissions:
+  contents: read
+
+jobs:
+  phpunit:
+    name: Run PHPUnit
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.4"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer
+          coverage: none
+
+      - name: Validate composer.json
+        run: composer validate --no-interaction
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist
+
+      - name: Run tests
+        run: vendor/bin/phpunit
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,13 @@
+### v4.15.1 (2026-01-19)
+* * * 
+
+### Regression Bug Fixes:
+* Fix list fields to accept JSON objects with explicit numeric keys. [Reference](https://github.com/chargebee/chargebee-php/pull/116#issuecomment-3715071348).
+
+### Tests:
+* Added `PHPUnit` test case coverage workflow on pull request.
+* Added tests suits for `JsonParamEncoder`.
+
 ### v4.15.0 (2026-01-16)
 * * * 
 

diff --git a/src/ValueObjects/Encoders/JsonParamEncoder.php b/src/ValueObjects/Encoders/JsonParamEncoder.php
@@ -14,7 +14,9 @@ class JsonParamEncoder implements ParamEncoderInterface
 
     public static function encode(array $params, array $jsonKeys = []): string
     {
-        return json_encode(self::formatJsonKeysAsSnakeCase($params), JSON_FORCE_OBJECT);
+        $params = self::formatJsonKeysAsSnakeCase($params);
+        $params = self::convertEmptyArraysToObjects($params);
+        return json_encode($params);
     }
 
     public static function formatJsonKeysAsSnakeCase($value, $maxDepth = 1000, $currentDepth = 0): array
@@ -40,4 +42,17 @@ public static function formatJsonKeysAsSnakeCase($value, $maxDepth = 1000, $curr
         return $serialized;
     }
 
+    private static function convertEmptyArraysToObjects($data)
+    {
+        if (!is_array($data)) {
+            return $data;
+        }
+
+        if ($data === []) {
+            return new \stdClass();
+        }
+
+        return array_map(fn($v) => is_array($v) ? self::convertEmptyArraysToObjects($v) : $v, $data);
+    }
+
 }
diff --git a/src/ValueObjects/Encoders/URLFormEncoder.php b/src/ValueObjects/Encoders/URLFormEncoder.php
@@ -32,7 +32,7 @@ private static function serialize($value, $prefix = null, $idx = null, $jsonKeys
                 $key = (!is_null($prefix) ? $prefix : '') .
                     (!is_null($prefix) ? '[' . $usK . ']' : $usK) .
                     (!is_null($idx) ? '[' . $idx . ']' : '');
-                $serialized[$key] = is_string($v)?$v:json_encode($v, JSON_FORCE_OBJECT);
+                $serialized[$key] = is_string($v) ? $v : json_encode((is_array($v) && $v === []) ? (object)[] : $v);
             } else if (is_array($v) && !is_int($k)) {
                 $tempPrefix = (!is_null($prefix)) ? $prefix . '[' . Util::toUnderscoreFromCamelCase($k) . ']' : Util::toUnderscoreFromCamelCase($k);
                 $serialized = array_merge($serialized, self::serialize($v, $tempPrefix, null, $jsonKeys, $level + 1));

diff --git a/src/Version.php b/src/Version.php
@@ -4,7 +4,7 @@
 
 final class Version
 {
-	const VERSION = '4.15.0';
+	const VERSION = '4.15.1';
 }
 
 ?>
diff --git a/tests/ValueObjects/Encoder/JsonParamEncoderTest.php b/tests/ValueObjects/Encoder/JsonParamEncoderTest.php
@@ -0,0 +1,248 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\ValueObjects\Encoders;
+
+use Chargebee\ValueObjects\Encoders\JsonParamEncoder;
+use PHPUnit\Framework\TestCase;
+
+final class JsonParamEncoderTest extends TestCase
+{
+    /** Should convert params to JSON string */
+    /** {"first_name":"John","last_name":"Doe","email":"john@test.com","locale":"fr-CA"} */
+    public function testEncodeParamsWithSimpleAttributes(): void
+    {
+        $params = [
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'email' => 'john@test.com',
+            'locale' => 'fr-CA',
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+    /** Should convert params to JSON string */
+    /** {"first_name":"John","last_name":"Doe","coupons":["FIFTYOFF","TENOFF"]} */
+    public function testEncodeParamsWithAttributeAsArrayOfPrimitives(): void
+    {
+        $params = [
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'coupons' => ['FIFTYOFF', 'TENOFF'],
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string */
+    /** {"first_name":"John","last_name":"Doe","billing_address":{"city":"Walnut","state":"California"}} */
+    public function testEncodeParamsWithAttributeAsSubResourceAttributes(): void
+    {
+        $params = [
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'billing_address' => [
+                'city' => 'Walnut',
+                'state' => 'California',
+            ],
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string */
+    /** {"subscription_items":[{"item_price_id":"day-pass-USD","unit_price":100},{"item_price_id":"basic-USD","billing_cycles":2,"quantity":1}],"billing_cycle":1} */
+    public function testEncodeParamsWithAttributeAsArrayOfSubResources(): void
+    {
+        $params = [
+            'subscription_items' => [
+                [
+                    'item_price_id' => 'day-pass-USD',
+                    'unit_price' => 100,
+                ],
+                [
+                    'item_price_id' => 'basic-USD',
+                    'billing_cycles' => 2,
+                    'quantity' => 1,
+                ],
+            ],
+            'billing_cycle' => 1,
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Convert params to JSON encoding. Transform empty arrays into empty object {} instead of [] */
+    /** {} */
+    public function testEncodeParamsWithEmptyArrayAsEmptyObject(): void
+    {
+        $params = [];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertStringContainsString('{}', $encoded);
+    }
+
+    /** Should convert params to JSON string */
+    /** {"id":"foo","name":"foo","discount_percentage":10,"apply_on":"each_specified_item","item_constraints":[{"constraint":"specific","item_type":"plan","item_price_ids":["some_price_id_one","some_price_id_two"]}]} */
+    public function testEncodeParamsWithComplexNestedStructure(): void
+    {
+        $params = [
+            'id' => 'foo',
+            'name' => 'foo',
+            'discount_percentage' => 10.0,
+            'apply_on' => 'each_specified_item',
+            'item_constraints' => [
+                [
+                    'constraint' => 'specific',
+                    'item_type' => 'plan',
+                    'item_price_ids' => [
+                        'some_price_id_one',
+                        'some_price_id_two',
+                    ],
+                ],
+            ],
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string with numeric values */
+    /** {"integer_value":42,"float_value":10.5,"zero_value":0,"negative_value":-15} */
+    public function testEncodeParamsWithNumericValues(): void
+    {
+        $params = [
+            'integer_value' => 42,
+            'float_value' => 10.5,
+            'zero_value' => 0,
+            'negative_value' => -15,
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string with null values */
+    /** {"first_name":"John","middle_name":null,"last_name":"Doe"} */
+    public function testEncodeParamsWithNullValues(): void
+    {
+        $params = [
+            'first_name' => 'John',
+            'middle_name' => null,
+            'last_name' => 'Doe',
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string with special characters */
+    /** {"email":"john@test.com","url":"https://example.com/path?query=value","description":"Line 1\nLine 2\tTabbed","quotes":"He said \"hello\""} */
+    public function testEncodeParamsWithSpecialCharacters(): void
+    {
+        $params = [
+            'email' => 'john@test.com',
+            'url' => 'https://example.com/path?query=value',
+            'description' => "Line 1\nLine 2\tTabbed",
+            'quotes' => 'He said "hello"',
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string with deeply nested structure */
+    /** {"level1":{"level2":{"level3":{"level4":{"value":"deep"}}}}} */
+    public function testEncodeParamsWithDeeplyNestedStructure(): void
+    {
+        $params = [
+            'level1' => [
+                'level2' => [
+                    'level3' => [
+                        'level4' => [
+                            'value' => 'deep',
+                        ],
+                    ],
+                ],
+            ],
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should convert params to JSON string with mixed types */
+    /** {"string":"value","integer":123,"float":45.67,"boolean":true,"null":null,"array":[1,2,3],"object":{"key":"value"}} */
+    public function testEncodeParamsWithMixedTypes(): void
+    {
+        $params = [
+            'string' => 'value',
+            'integer' => 123,
+            'float' => 45.67,
+            'boolean' => true,
+            'null' => null,
+            'array' => [1, 2, 3],
+            'object' => ['key' => 'value'],
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+
+    /** Should Convert empty array attribute to object & array to json array while converting to JSON */
+    /** {"first_name":"John","last_name":"Doe","email":"john@test.com","locale":"fr-CA","meta_data":{},"coupons":["FIFTY_OFF","EXTRA_CARD_OFFER"]}  */
+    public function testEncodeParamsWithSimpleAttributesOne(): void
+    {
+        $params = [
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'email' => 'john@test.com',
+            'locale' => 'fr-CA',
+            'meta_data' => [],
+            'coupons' => ["FIFTY_OFF", "EXTRA_CARD_OFFER"]
+        ];
+
+        $encoded = JsonParamEncoder::encode($params);
+        $this->assertIsString($encoded);
+        $this->assertJson($encoded);
+        $this->assertEquals($params, json_decode($encoded, true));
+    }
+}
diff --git a/tests/ValueObjects/Encoder/URLFormEncoderTest.php b/tests/ValueObjects/Encoder/URLFormEncoderTest.php
@@ -189,4 +189,32 @@ public function testEncodeParamsWithAEmptyJsonAttribute(): void {
         $this->assertIsString($encoded);
         $this->assertSame("first_name=John&last_name=Doe&meta_data=%7B%7D", $encoded);
     }
+
+    /** Convert params to URL-form encoding. Do not transform json arrays to array based indexing. it should not ItemPriceId { "0" => "some_price_id"}  */
+    /** id=foo&name=foo&discount_percentage=10&apply_on=each_specified_item&item_constraints[constraint][0]=specific&item_constraints[item_type][0]=plan&item_constraints[item_price_ids][0]=["some_price_id"] */
+    public function testEncodeParamsShouldNotUseArrayBasedIndexingForJsonArray(): void
+    {
+        $params = [
+            'id' => 'foo',
+            'name' => 'foo',
+            'discount_percentage' => 10.0,
+            'apply_on' => 'each_specified_item',
+            'item_constraints' => [
+                [
+                    'constraint' => 'specific',
+                    'item_type' => 'plan',
+                    'item_price_ids' => [
+                        'some_price_id',
+                    ],
+                ],
+            ],
+        ];
+
+        $json_keys = [
+            "itemPriceIds" => 1
+        ];
+        $encoded = URLFormEncoder::encode($params, $json_keys);
+        $this->assertIsString($encoded);
+        $this->assertSame("id=foo&name=foo&discount_percentage=10&apply_on=each_specified_item&item_constraints%5Bconstraint%5D%5B0%5D=specific&item_constraints%5Bitem_type%5D%5B0%5D=plan&item_constraints%5Bitem_price_ids%5D%5B0%5D=%5B%22some_price_id%22%5D", $encoded);
+    }
 }