Mapping Flat Arrays to Nested SOAP Structures in PHP
When working with legacy web services, you often encounter scenarios where the data model expected by the server is fundamentally different from how you structure your application logic. The specific issue here involves a mismatch between a flat associative array and a nested XML structure required by a SOAP endpoint.
In the provided example, the PHP client constructs a request using SoapClient with a simple nested array:
$data = array('Acquirer' => array(
'Id' => 'MyId',
'UserId' => 'MyUserId',
'Password' => 'MyPassword'
));
However, the resulting SOAP envelope wraps these values inside a generic Map element with item/key/value pairs. This happens because the PHP SOAP engine defaults to an older encoding style (SOAP-ENC:encodingStyle) and attempts to serialize complex types based on loose heuristics when no strict WSDL definition is enforced or correctly interpreted.
To achieve the desired outputâwhere <Acquirer> directly contains <Id>, <UserId>, and <Password> tagsâyou must explicitly instruct the SoapClient to use a specific encoding style that supports nested element mapping rather than generic map serialization.
Using SOAP 1.2 Encoding Style
The primary culprit for the unwanted Map structure is the default behavior of PHP's SoapClient when interacting with services that do not strictly enforce WSDL validation or when using older XML namespaces. The solution lies in switching the encoding style to SOAP_1_2. This mode changes how the client serializes complex types, allowing it to map nested arrays directly into nested elements instead of flattening them into key-value maps.
Update your SoapClient instantiation as follows:
$client = new SoapClient(NULL, array(
'location' => 'https://example.com/ExampleWebServiceDL/services/ExampleHandler',
'uri' => 'http://example.com/wsdl',
'trace' => 1,
'encoding_style' => SOAP_ENC_LITERAL // Forces literal element mapping
));
Alternatively, and often more robustly for this specific transformation, setting the nscl (namespace cloning) option or explicitly defining the encoding style can help. However, the most direct fix for forcing nested elements over maps is ensuring the client doesn't default to the legacy SOAP-ENC header which triggers the map behavior.
If you inspect the generated XML again after this change, you should see the SOAP-ENV:encodingStyle attribute removed or changed, and the body should reflect the direct nesting of <Acquirer> children.
Handling WSDL and Namespace Mismatches
Sometimes, simply changing the encoding style isn't enough if the service expects a specific namespace for the request body. The generated XML in your desired output omits the SOAP-ENC attribute on the Envelope but keeps other namespaces. This suggests the service might be expecting standard SOAP 1.2 literal formatting without the legacy encoding header.
If the encoding_style parameter does not resolve the issue, you may need to inspect the WSDL file at the provided URI (http://example.com/wsdl). If the WSDL defines a specific message type for Echo, PHP's auto-generated stub will handle the mapping correctly if the data structure matches the WSDL schema exactly.
If no valid WSDL is available or the service is a "stubless" endpoint, you must rely on the encoding_style parameter to force the client to output literal tags. Ensure that your input array keys match the expected XML element names precisely (case-sensitive). In your example, 'Acquirer' maps to <Acquirer>. If the server expects <Acquirer> but receives <param0>, it indicates a schema mismatch that SoapClient is trying to resolve using its generic map logic.
Debugging with Trace Logging
The trace option set to 1 in your original code is excellent for debugging, but ensure you are capturing both the request sent and the response received. Sometimes the server accepts the Map format but returns an error because the internal schema requires the nested structure. By enabling tracing ($client->setWsdlCache(false) can also help if caching a bad WSDL), you can verify exactly what the server expects in the body.
If the service strictly rejects the map format, there is no programmatic workaround other than ensuring the client uses SOAP_1_2 with literal encoding. This forces the SOAP engine to treat your array keys as direct XML element names rather than dictionary entries within a generic container.
For complex integrations where standard SoapClient behavior remains unpredictable, consider using a raw cURL request to construct the XML body manually. This gives you full control over the namespaces and structure, bypassing PHP's serialization logic entirely. However, this requires parsing the WSDL to generate the correct XML tags before sending the request.
