[WIP] Explanations for a couple more options

Author: IMSoP

reference/soap/soapclient/construct.xml

@@ -458,7 +458,17 @@
              </term>
              <listitem>
               <para>
-               TODO
+               When decoding a response to an array, the default behaviour is to detect whether
+               an element name appears once or multiple times in a particular parent element.
+               For elements which appear only once, an object property allows direct access to
+               the content; for elements which appear more than once, the property contains an
+               array with the content of each matching element.
+              </para>
+              <para>
+               If the <constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant> feature is enabled,
+               elements which appear only once are placed in a single-element array, so that
+               access is consistent for all elements. This only has an effect when using a WSDL
+               containing a schema for the response. See Examples sections for an illustration.
               </para>
              </listitem>
             </varlistentry>
@@ -468,7 +478,9 @@
              </term>
              <listitem>
               <para>
-               TODO
+               When the <parameter>use</parameter> option is set to <literal>encoded</literal>,
+               force arrays to use a type of <literal>SOAP-ENC:Array</literal>, rather than a
+               schema-specific type.
               </para>
              </listitem>
             </varlistentry>
@@ -574,8 +586,7 @@ $client = new SoapClient("some.wsdl", ['context' => $context]);
   <para>
    <example>
     <title>
-     <function>SoapClient::__construct</function>
-     example
+     <function>SoapClient::__construct</function> example
     </title>
     <programlisting role="php">
      <![CDATA[
@@ -623,6 +634,73 @@ $client = new SoapClient("books.wsdl", array('classmap' => array('book' => "MyBo
     </programlisting>
    </example>
   </para>
+
+  <para>
+   <example>
+    <title>Using the <constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant> feature</title>
+    <programlisting role="php">
+     <![CDATA[
+  /* Assuming a response like this, and an appropriate WSDL:
+  <?xml version="1.0" encoding="UTF-8"?>
+  <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:example">
+      <SOAP-ENV:Body>
+          <response>
+              <collection>
+                  <item>Single</item>
+              </collection>
+              <collection>
+                  <item>First</item>
+                  <item>Second</item>
+              </collection>
+          </response>
+      </SOAP-ENV:Body>
+  </SOAP-ENV:Envelope>
+  */
+
+  echo "Default:\n";
+
+  $client = new TestSoapClient(__DIR__ . '/temp.wsdl');
+  $response = $client->exampleRequest();
+  var_dump( $response->collection[0]->item );
+  var_dump( $response->collection[1]->item );
+
+  echo "\nWith SOAP_SINGLE_ELEMENT_ARRAYS:\n";
+
+  $client = new TestSoapClient(__DIR__ . '/temp.wsdl', ['features' => SOAP_SINGLE_ELEMENT_ARRAYS]);
+  $response = $client->exampleRequest();
+  var_dump( $response->collection[0]->item );
+  var_dump( $response->collection[1]->item );
+  ]]>
+    </programlisting>
+
+    &example.outputs;
+
+    <screen>
+     <![CDATA[
+  Default:
+  string(6) "Single"
+  array(2) {
+    [0] =>
+    string(5) "First"
+    [1] =>
+    string(6) "Second"
+  }
+
+  With SOAP_SINGLE_ELEMENT_ARRAYS:
+  array(1) {
+    [0] =>
+    string(6) "Single"
+  }
+  array(2) {
+    [0] =>
+    string(5) "First"
+    [1] =>
+    string(6) "Second"
+  }
+  ]]>
+    </screen>
+   </example>
+  </para>
  </refsect1>
 
 </refentry>