Preserve null values in v2 JSON request bodies

[jar-stripe]

Why?

v2 APIs use JSON-encoded POST bodies where null has semantic meaning — it signals the intent to clear/unset a field. Two issues prevented this from working:

1. AbstractService::formatParams() converted all null values to empty strings, which is correct for v1 but strips null semantics for v2
2. Util::objectsToIds() stripped null values from params entirely before they could reach the JSON encoder

This was identified as part of an audit across all 7 Stripe language SDKs (DEVSDK-2926) to verify explicit null handling. PHP was one of four languages where v2 null serialization was not working correctly.

What?

• Modified AbstractService::formatParams() to accept a required $apiMode parameter — for v2, null values are preserved; for v1, nulls are converted to empty strings for form encoding
• Modified Util::objectsToIds() to accept a required $serializeEmpty parameter — when true (v2 POST), null values in associative arrays are preserved instead of stripped
• CurlClient::constructUrlAndBody() passes $serializeEmpty = true for v2 POST requests
• Fixed edge case where an associative array with all values stripped would json_encode as [] instead of {} — cast to stdClass to preserve the object type
• Updated all callers to derive API mode from the request path and pass it explicitly
• Added 14 new tests covering null preservation, null stripping, nested nulls, metadata key deletion, and end-to-end request integration for both API modes

Changelog

• The SDK now preserves and sends null when set in V2 API metadata and params, enabling you to clear metadata entries and some unsettable properties for V2 APIs.
• ⚠️ The Util::objectsToIds() method now has a required $serializeNull parameter to indicate if null values set in the object should be output in the resulting hash. This is relevant for V2 POST APIs to let callers clear emptyable values.

See Also

• DEVSDK-2926: Cross-SDK emptyable field support audit

[Copilot]

Pull request overview

Updates Stripe PHP’s service-layer param formatting so null values keep their semantic meaning for v2 JSON request bodies (clear/unset), while preserving existing v1 form-encoding behavior.

Changes:

• Extend AbstractService::formatParams() with an apiMode argument to preserve null for v2 and convert null -> '' for v1.
• Update service request helpers (request, requestStream, requestCollection, requestSearchResult) to derive API mode from the path and pass it through.
• Add tests validating v1/v2 null handling, including nested nulls and request integration behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
lib/Service/AbstractService.php	Adds API-mode-aware param formatting and threads mode through request helper methods.
tests/Stripe/Service/AbstractServiceTest.php	Adds coverage for v1 null stringification vs v2 null preservation and request-level assertions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.