It is not a bug. The style document/literal is for sending messages with document data. It is not a remote procedure call. For that we have rpc/literal. So if you look at it that way it is completely understandable that only one method should be around to handle one specific type of message (document).

It is also completely correct behaviour according to the specification WS-I Basic Profile.

“In the case of rpc-literal binding, the operation name is used as a wrapper for the part accessors. In the document-literal case, since a wrapper with the operation name is not present, the message signatures must be correctly designed so that they meet this requirement.“

As document/literal is the preferred style, and some implementations obviously have a tendency to dislike rpc/literal, a lot of people is going down the document/literal route without understanding the implications and what the real difference really is.

I don’t think this should stop ext/soap in PHP to use the soapAction header for routing when necessary. According to WSDL 1.1 the soapAction attribute is mandatory when HTTP protocol binding is used. Whether rpc/literal or dcoument/literal style is used is of no difference. So is this information just garbage for document style messages?

Anyways, PHP bug 46169 is to my understanding not really a bug. But it is a reasonable feature request.

So after loads of googling I came to realise that even though 2010 is just around the corner there are still very few quality articles on PHP and web services/SOAP available. Most of the stuff I find is rubbish where people who don’t know nothing explain things they don’t understand.

So even though these articles below are old, they will give most people a very good grasp on how, and why, to create a SOAP web service using PHP that will work. (And a very short advice; use document/literal style for better interoperability with for example .NET and don’t use preserved words like “ref” as parameter (message parts) names for better interoperability with for example .NET).

1. Which style of WSDL should I use?
2. PHP SOAP Extension

A comment about the second article is in place though. I generally tend to favour mapping WSDL defined operations to methods in a class. So instead of using PHP methods like $server->addFunction(), use $server->setClass(). More on setClass() in the manual.

As an example I have the below complex types, message and operation defined in the WSDL file. (The example is not complete of course.)

    <complexType name="KeyValueData">
      <sequence>
        <element minOccurs="1" maxOccurs="1" name="id" type="string"/>
        <element minOccurs="1" maxOccurs="1" name="name" type="string"/>
        <element minOccurs="1" maxOccurs="1" name="data" type="string"/>
      </sequence>
    </complexType>

    <complexType name="ArrayOfKeyValueData">
      <sequence>
        <element minOccurs="0" maxOccurs="unbounded"
                 name="keyval" type="tns:KeyValueData"/>
      </sequence>
    </complexType>
      ...
    <message name="StatisticsListOutput">
      <part name="data" element="tns:ArrayOfKeyValueData"/>
    </message>
      ...
    <operation name="getStatistics">
      <input message="tns:StatisticsListInput"/>
      <output message="tns:StatisticsListOutput"/>
    </operation>

Sending this from the client is an absolute no brainer. It is a simple array containg associative arrays in every slot. When receiving this structure on the client side the original array (the member variable Map in the example) with one element turns into

Class Object
(
    [Map] => stdClass Object
        (
            [item] => Array
                (
                    [0] => stdClass Object
                        (
                            [key] => id
                            [value] => value
                        )

                    [1] => stdClass Object
                        (
                            [key] => name
                            [value] => value
                        )

where an array with multiple elements turn into

stdClass Object
(
    [Map] => Array
        (
            [0] => stdClass Object
                (
                    [item] => Array
                        (
                            [0] => stdClass Object
                                (
                                    [key] => id
                                    [value] => value
                                )

                            [1] => stdClass Object
                                (
                                    [key] => name
                                    [value] => value
                                )

This is annoying. Just imagine the situation when you have multiple arrays in arrays… Which actually does happen every once in a while when sending compounds of various elements declared as ComplexTypes in the WSDL.

Is it a feature, quirk or anti social behaviour? I don’t know. If there is another way I’d like to hear about it.

I recently encountered a problem in the ext/soap extension in PHP5 (version 5.0.2). I’ve been using the extension in development only so far and it has proved to be quite stable.

The PHP soap server I’ve written run on Tru64 and exposes a weird C API that I wrapped in a custom extension. So this soap server is going to be used as a wrapper for this legacy proprietary system. It all seemed to work great until a system written in a.NET environment wanted to hook up a client to the server…

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:tns="http://spock/kunta/kunta"
 xmlns:types="http://spock/kunta/kunta/encodedTypes"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <q1:bassCall xmlns:q1="http://spock/bass/types/kunta">
  <system xsi:type="xsd:string">XXX</system>
  <function xsi:type="xsd:string">TASKTEST</function>
  <parameter href="#id1" />
 </q1:bassCall>

 <soapenc:Array id="id1" soapenc:arrayType="tns:Item[1]">
  <Item href="#id2" />
 </soapenc:Array>

 <tns:Item id="id2" xsi:type="tns:Item">
  <key xsi:type="xsd:string">ABCabc123</key>
  <val xsi:type="xsd:string">123456</val>
 </tns:Item>

</soap:Body>
</soap:Envelope>