PHP多维数组到复杂XML结构的SOAP序列化实践

日期：2025-11-10 00:00 / 作者：心靈之曲

本文旨在解决php多维数组向复杂soap xml结构序列化时遇到的“无法序列化结果”问题。通过深入理解soap xml的结构要求，包括命名空间和类型属性，文章将指导您如何构建符合特定xml schema的php关联数组。我们将利用`spatie/array-to-xml`库，详细演示其安装与使用方法，确保php数据能够准确无误地转换为soap兼容的xml，从而实现可靠的web服务通信。

在现代Web服务通信中，尤其是在使用SOAP协议时，将PHP中的复杂多维数组准确地序列化为符合特定XML Schema的XML结构是一项常见的挑战。直接的递归转换方法往往难以处理SOAP XML中对命名空间、属性（如xsi:type）和复杂类型数组的严格要求，从而导致“unable to serialize result”等错误。本文将详细介绍如何通过构建符合目标XML结构的PHP数组，并结合高效的第三方库，实现PHP多维数组到SOAP XML的无缝序列化。

1. 理解SOAP XML的结构要求

SOAP（Simple Object Access Protocol）消息的XML结构通常比普通的XML更为复杂，它严格遵循WSDL（Web Services Description Language）中定义的Schema。一个典型的SOAP XML结构会包含：

命名空间（Namespaces）: 通过xmlns:前缀定义，用于区分不同Schema中的元素。
元素类型（Element Types）: 通过xsi:type属性指定，明确元素的数据类型或复杂类型。
属性（Attributes）: 元素的附加信息，例如SOAP-ENV:encodingStyle。
复杂类型数组: 例如，SOAP-ENC:Array 类型，需要特殊的结构来表示数组中的每个项及其类型。

例如，对于一个包含人员信息和物品列表的SOAP请求，其期望的XML结构可能如下所示：

要生成这样的XML，传统的递归转换函数需要进行大量修改以支持属性和命名空间，并且对于SOAP数组类型可能力不从心。

2. 构建符合SOAP规范的PHP数组结构

为了精确控制生成的XML，我们需要将PHP数组组织成一种能够明确表达XML元素名称、值、属性和命名空间的特定格式。spatie/array-to-xml等库通常采用一种约定，通过特殊的键名来区分这些XML组件。

假设我们有以下原始PHP数据：

$originalData = [
    "name" => "John Doe",
    "date" => "2025-11-30 00:00:00.000",
    "job" => "developer",
    "where_from" => "france",
    "address" => [
        "country" => "france",
        "city" => "paris",
        "vat_number" => "123456"
    ],
    "items" => [
        [
            "cook" => "spoon",
            "clean" => "vacuum"
        ]
    ]
];

为了将其转换为上述SOAP XML结构，我们需要将$originalData转换为以下特殊结构的PHP数组。请注意，这里的转换不仅仅是简单的键值映射，更是对数据进行重塑以匹配XML Schema。例如，originalData['items'][0]['cook']被映射为items下的第一个item的name字段。

$soapFormattedData = [
    'SOAP-ENV:Body' => [
        'ns1:Person' => [
            'info' => [ // 对应XML中的  标签，这里为了清晰，使用了 'info'，实际可能需要与XML标签名一致
                "name" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "John Doe"],
                // 假设 'surname' 也是需要的字段，从原始数据中获取或补充
                "surname" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "Doe"],
                "job" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "developer"],
                "from" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "france"],
                "address" => [
                    "country" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "france"],
                    "city" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "paris"],
                    "post_code" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "123456"], // 原始数据是vat_number
                    '_attributes' => ['xsi:type' => 'tns:getAddress'] // address 标签的属性
                ],
                "items" => [
                    // 对于数组中的每个元素，使用 '__custom:标签名:索引' 来创建同名标签
                    // 原始数据中的 "cook" 和 "clean" 被映射到 "name" 和 "material"
                    '__custom:item:1' => [
                        "name" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "spoon"],
                        "material" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "vacuum"],
                    ],
                    // 如果有多个item，可以继续添加 '__custom:item:2' 等
                    '_attributes' => ['xsi:type' => 'tns:getItems'] // items 标签的属性
                ],
                '_attributes' => ['xsi:type' => 'tns:getPersonInfo'] // data/info 标签的属性
            ],
            '_attributes' => ['xmlns:ns1' => 'https://ex.pt/webservices'] // Person 标签的属性
        ]
    ]
];

关键约定解释：

_attributes: 用于存储当前元素的所有XML属性，其值是一个关联数组，键为属性名，值为属性值。
_value: 用于存储当前元素的文本内容。
__custom:标签名:索引: 当需要在一个父元素下创建多个同名子元素时，可以使用此约定。例如，__custom:item:1和__custom:item:2会生成两个标签。这里的索引可以是任意唯一标识符。

3. 使用 spatie/array-to-xml 进行序列化

spatie/array-to-xml是一个功能强大且易于使用的PHP库，专门用于将PHP数组转换为XML字符串。它很好地支持了上述特殊数组结构。

3.1 安装

通过Composer安装此库：

composer require spatie/array-to-xml

3.2 序列化代码

安装完成后，您可以使用以下代码将构建好的PHP数组转换为SOAP XML：

 [
        'ns1:Person' => [
            'data' => [ // 对应XML中的  标签
                "name" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "John Doe"],
                "surname" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "Doe"],
                "job" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "developer"],
                "from" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "france"],
                "address" => [
                    "country" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "france"],
                    "city" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "paris"],
                    "post_code" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "123456"],
                    '_attributes' => ['xsi:type' => 'tns:getAddress']
                ],
                "items" => [
                    '__custom:item:1' => [
                        "name" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "spoon"],
                        "material" => ['_attributes' => ['xsi:type' => 'xsd:string'], '_value' => "vacuum"],
                    ],
                    '_attributes' => ['xsi:type' => 'tns:getItems']
                ],
                '_attributes' => ['xsi:type' => 'tns:getPersonInfo']
            ],
            '_attributes' => ['xmlns:ns1' => 'https://ex.pt/webservices']
        ]
    ]
];

// 定义SOAP Envelope的根元素和其属性
$response = ArrayToXml::convert($soapFormattedData, [
    'rootElementName' => 'SOAP-ENV:Envelope',
    '_attributes' => [
        'SOAP-ENV:encodingStyle' => 'http://schemas.xmlsoap.org/soap/encoding/',
        'xmlns:SOAP-ENV' => 'http://schemas.xmlsoap.org/soap/envelope/',
        'xmlns:xsd' => 'http://www.w3.org/2001/XMLSchema',
        'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
        'xmlns:SOAP-ENC' => 'http://schemas.xmlsoap.org/soap/encoding/',
        'xmlns:tns' => 'http://ex.pt/soap/WebServices'
    ],
], true, 'UTF-8');

echo $response;

在ArrayToXml::convert()方法中：

第一个参数是待转换的PHP数组。
第二个参数是一个配置数组，其中：
- rootElementName 指定了XML的根元素名称，这里是SOAP-ENV:Envelope。
- _attributes 定义了根元素的所有属性，包括SOAP所需的各种命名空间和编码样式。
第三个参数true表示是否格式化输出，使其更具可读性。
第四个参数'UTF-8'指定了XML的编码。

执行上述代码将输出符合SOAP规范的XML字符串，该字符串可以用于SOAP请求的Body部分。

4. 注意事项与最佳实践

严格遵循XML Schema: 成功的SOAP序列化关键在于PHP数组结构与目标XML Schema的精确匹配。任何标签名、属性或数据类型的不匹配都可能导致序列化失败或Web服务拒绝请求。
数据映射: 原始PHP数组中的数据可能需要进行转换或重命名，以适应XML Schema中定义的字段名和类型。例如，原始数组中的vat_number可能需要映射到XML中的post_code。
命名空间管理: SOAP XML对命名空间有严格要求。确保所有命名空间（如xmlns:ns1、xmlns:tns等）都在适当的元素上正确定义。
调试技巧: 如果遇到序列化错误，首先检查生成的XML字符串是否符合预期。可以使用在线XML验证工具或SOAP调试工具（如SoapUI）来验证XML的结构和有效性。
错误处理: 在实际应用中，应包含健壮的错误处理机制，例如捕获序列化过程中可能抛出的异常。
性能考量: 对于非常大的数组，序列化过程可能会消耗较多的内存和CPU。在性能敏感的场景下，可以考虑分批处理或优化数组结构。

总结

将PHP多维数组序列化为复杂的SOAP XML结构，尤其是当XML中包含命名空间、xsi:type属性和嵌套数组时，需要一种比简单递归转换更精细的方法。通过理解SOAP XML的严格要求，并采用spatie/array-to-xml库提供的特殊数组结构约定（如_attributes、_value和__custom:标签名:索引），开发者可以精确地控制生成的XML，确保其符合SOAP规范，从而实现与Web服务的成功交互。关键在于将原始PHP数据映射并重塑为与目标XML Schema完全一致的中间数组结构。