documentation/manual/en/module_specs/Zend_Soap_Wsdl.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.soap.wsdl">
   4     <title>WSDL Accessor</title>
   5
   6     <note>
   7         <para>
   8             <classname>Zend_Soap_Wsdl</classname> class is used by
   9             <classname>Zend_Soap_Server</classname> component internally to operate with WSDL
  10             documents. Nevertheless, you could also use functionality provided by this class for
  11             your own needs. The <classname>Zend_Soap_Wsdl</classname> package contains both a parser
  12             and a builder of WSDL documents.
  13         </para>
  14
  15         <para>
  16             If you don't plan to do this, you can skip this documentation section.
  17         </para>
  18     </note>
  19
  20     <sect2 id="zend.soap.wsdl.constructor">
  21         <title>Zend_Soap_Wsdl constructor</title>
  22
  23         <para>
  24             <classname>Zend_Soap_Wsdl</classname> constructor takes three parameters:
  25
  26             <orderedlist>
  27                 <listitem>
  28                     <simpara>
  29                         <varname>$name</varname> - name of the Web Service being described.
  30                     </simpara>
  31                 </listitem>
  32
  33                 <listitem>
  34                     <simpara>
  35                         <varname>$uri</varname> - <acronym>URI</acronym> where the WSDL will be
  36                         available (could also be a reference to the file in the filesystem.)
  37                     </simpara>
  38                 </listitem>
  39
  40                 <listitem>
  41                     <simpara>
  42                         <varname>$strategy</varname> - optional flag used to identify the strategy
  43                         for complex types (objects) detection. This was a boolean
  44                         <varname>$extractComplexTypes</varname> before version 1.7 and can still be
  45                         set as a boolean for backwards compatibility. By default the 1.6 detection
  46                         behaviour is set. To read more on complex type detection strategies go to
  47                         the section: <xref linkend="zend.soap.wsdl.types.add_complex" />.
  48                     </simpara>
  49                 </listitem>
  50             </orderedlist>
  51         </para>
  52     </sect2>
  53
  54     <sect2 id="zend.soap.wsdl.addmessage">
  55         <title>addMessage() method</title>
  56
  57         <para>
  58             <methodname>addMessage($name, $parts)</methodname> method adds new message description
  59             to the WSDL document (/definitions/message element).
  60         </para>
  61
  62         <para>
  63             Each message correspond to methods in terms of <classname>Zend_Soap_Server</classname>
  64             and <classname>Zend_Soap_Client</classname> functionality.
  65         </para>
  66
  67         <para>
  68            <varname>$name</varname> parameter represents message name.
  69         </para>
  70
  71         <para>
  72            <varname>$parts</varname> parameter is an array of message parts which describe
  73            <acronym>SOAP</acronym> call parameters. It's an associative array: 'part name' (SOAP
  74            call parameter name) =&gt; 'part type'.
  75         </para>
  76
  77         <para>
  78             Type mapping management is performed using <methodname>addTypes()</methodname>,
  79             <methodname>addTypes()</methodname> and <methodname>addComplexType()</methodname>
  80             methods (see below).
  81         </para>
  82
  83         <note>
  84             <para>
  85                 Messages parts can use either 'element' or 'type' attribute for typing
  86                 (see <ulink url="http://www.w3.org/TR/wsdl#_messages"/>).
  87             </para>
  88
  89             <para>
  90                 'element' attribute must refer to a corresponding element of data type definition.
  91                 'type' attribute refers to a corresponding complexType entry.
  92             </para>
  93
  94             <para>
  95                 All standard XSD types have both 'element' and 'complexType' definitions
  96                 (see <ulink url="http://schemas.xmlsoap.org/soap/encoding/"/>).
  97             </para>
  98
  99             <para>
 100                 All non-standard types, which may be added using
 101                 <methodname>Zend_Soap_Wsdl::addComplexType()</methodname> method, are described
 102                 using 'complexType' node of '/definitions/types/schema/' section of WSDL document.
 103             </para>
 104
 105             <para>
 106                 So <methodname>addMessage()</methodname> method always uses 'type' attribute to
 107                 describe types.
 108             </para>
 109         </note>
 110     </sect2>
 111
 112     <sect2 id="zend.soap.wsdl.add_port_type">
 113         <title>addPortType() method</title>
 114
 115         <para>
 116             <methodname>addPortType($name)</methodname> method adds new port type to the WSDL
 117             document (/definitions/portType) with the specified port type name.
 118         </para>
 119
 120         <para>
 121             It joins a set of Web Service methods defined in terms of
 122             <classname>Zend_Soap_Server</classname> implementation.
 123         </para>
 124
 125         <para>
 126             See <ulink url="http://www.w3.org/TR/wsdl#_porttypes"/> for the details.
 127         </para>
 128     </sect2>
 129
 130     <sect2 id="zend.soap.wsdl.add_port_operation">
 131         <title>addPortOperation() method</title>
 132
 133         <para>
 134             <methodname>addPortOperation($portType, $name, $input = false, $output = false, $fault
 135                 = false)</methodname> method adds new port operation to the specified port type of
 136             the WSDL document (/definitions/portType/operation).
 137         </para>
 138
 139         <para>
 140             Each port operation corresponds to a class method (if Web Service is based on a class)
 141             or function (if Web Service is based on a set of methods) in terms of
 142             <classname>Zend_Soap_Server</classname> implementation.
 143         </para>
 144
 145         <para>
 146             It also adds corresponding port operation messages depending on specified
 147             <varname>$input</varname>, <varname>$output</varname> and <varname>$fault</varname>
 148             parameters.
 149
 150             <note>
 151                 <para>
 152                     <classname>Zend_Soap_Server</classname> component generates two messages for
 153                     each port operation while describing service based on
 154                     <classname>Zend_Soap_Server</classname> class:
 155
 156                     <itemizedlist>
 157                         <listitem>
 158                             <para>
 159                                 input message with name <code>$methodName . 'Request'</code>.
 160                             </para>
 161                         </listitem>
 162
 163                         <listitem>
 164                             <para>
 165                                 output message with name <code>$methodName . 'Response'</code>.
 166                             </para>
 167                         </listitem>
 168                     </itemizedlist>
 169                 </para>
 170             </note>
 171         </para>
 172
 173         <para>
 174             See <ulink url="http://www.w3.org/TR/wsdl#_request-response"/> for the details.
 175         </para>
 176     </sect2>
 177
 178     <sect2 id="zend.soap.wsdl.add_binding">
 179         <title>addBinding() method</title>
 180
 181         <para>
 182             <methodname>addBinding($name, $portType)</methodname> method adds new binding to the
 183             WSDL document (/definitions/binding).
 184         </para>
 185
 186         <para>
 187             'binding' WSDL document node defines message format and protocol details for operations
 188             and messages defined by a particular portType (see <ulink
 189                 url="http://www.w3.org/TR/wsdl#_bindings"/>).
 190         </para>
 191
 192         <para>
 193             The method creates binding node and returns it. Then it may be used to fill with actual
 194             data.
 195         </para>
 196
 197         <para>
 198             <classname>Zend_Soap_Server</classname> implementation uses
 199             <code>$serviceName . 'Binding'</code> name for 'binding' element of WSDL document.
 200         </para>
 201     </sect2>
 202
 203     <sect2 id="zend.soap.wsdl.add_binding_operation">
 204         <title>addBindingOperation() method</title>
 205
 206         <para>
 207             <methodname>addBindingOperation($binding, $name, $input = false, $output = false, $fault
 208                 = false)</methodname> method adds an operation to a binding element
 209             (/definitions/binding/operation) with the specified name.
 210         </para>
 211
 212         <para>
 213             It takes <code>XML_Tree_Node</code> object returned by
 214             <methodname>addBinding()</methodname> as an input (<varname>$binding</varname>
 215             parameter) to add 'operation' element with input/output/false entries depending on
 216             specified parameters
 217         </para>
 218
 219         <para>
 220             <classname>Zend_Soap_Server</classname> implementation adds corresponding binding entry
 221             for each Web Service method with input and output entries defining 'soap:body' element
 222             as '&lt;soap:body use="encoded"
 223                 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
 224         </para>
 225
 226         <para>
 227             See <ulink url="http://www.w3.org/TR/wsdl#_bindings"/> for the details.
 228         </para>
 229     </sect2>
 230
 231     <sect2 id="zend.soap.wsdl.add_soap_binding">
 232         <title>addSoapBinding() method</title>
 233
 234         <para>
 235             <methodname>addSoapBinding($binding, $style = 'document', $transport =
 236                 'http://schemas.xmlsoap.org/soap/http')</methodname> method adds
 237             <acronym>SOAP</acronym> binding ('soap:binding') entry to the binding element (which is
 238             already linked to some port type) with the specified style and transport
 239             (Zend_Soap_Server implementation uses RPC style over <acronym>HTTP</acronym>).
 240         </para>
 241
 242         <para>
 243             '/definitions/binding/soap:binding' element is used to signify that the binding is bound
 244             to the <acronym>SOAP</acronym> protocol format.
 245         </para>
 246
 247         <para>
 248             See <ulink url="http://www.w3.org/TR/wsdl#_bindings"/> for the details.
 249         </para>
 250     </sect2>
 251
 252     <sect2 id="zend.soap.wsdl.add_soap_operation">
 253         <title>addSoapOperation() method</title>
 254
 255         <para>
 256             <methodname>addSoapOperation($binding, $soap_action)</methodname> method adds
 257             <acronym>SOAP</acronym> operation ('soap:operation') entry to the binding element with
 258             the specified action. 'style' attribute of the 'soap:operation' element is not used
 259             since programming model (RPC-oriented or document-oriented) may be using
 260             <methodname>addSoapBinding()</methodname> method
 261         </para>
 262
 263         <para>
 264             'soapAction' attribute of '/definitions/binding/soap:operation' element specifies the
 265             value of the <acronym>SOAP</acronym>Action header for this operation. This attribute is
 266             required for <acronym>SOAP</acronym> over <acronym>HTTP</acronym> and
 267             <emphasis>must not</emphasis> be specified for other transports.
 268         </para>
 269
 270         <para>
 271             <classname>Zend_Soap_Server</classname> implementation uses
 272             <code>$serviceUri . '#' . $methodName</code> for <acronym>SOAP</acronym> operation
 273             action name.
 274         </para>
 275
 276         <para>
 277             See <ulink url="http://www.w3.org/TR/wsdl#_soap:operation"/> for the details.
 278         </para>
 279     </sect2>
 280
 281     <sect2 id="zend.soap.wsdl.add_service">
 282         <title>addService() method</title>
 283
 284         <para>
 285             <methodname>addService($name, $port_name, $binding, $location)</methodname> method adds
 286             '/definitions/service' element to the WSDL document with the specified Wed Service name,
 287             port name, binding, and location.
 288         </para>
 289
 290         <para>
 291             WSDL 1.1 allows to have several port types (sets of operations) per service. This
 292             ability is not used by <classname>Zend_Soap_Server</classname> implementation and not
 293             supported by <classname>Zend_Soap_Wsdl</classname> class.
 294         </para>
 295
 296         <para>
 297             <classname>Zend_Soap_Server</classname> implementation uses:
 298
 299             <itemizedlist>
 300                 <listitem>
 301                     <para>
 302                         <code>$name . 'Service'</code> as a Web Service name,
 303                     </para>
 304                 </listitem>
 305
 306                 <listitem>
 307                     <para>
 308                         <code>$name . 'Port'</code> as a port type name,
 309                     </para>
 310                 </listitem>
 311
 312                 <listitem>
 313                     <para>
 314                         <code>'tns:' . $name . 'Binding'</code>
 315
 316                         <footnote>
 317                             <para>
 318                                 <code>'tns:' namespace</code> is defined as script
 319                                 <acronym>URI</acronym> (<code>'http://' .$_SERVER['HTTP_HOST']
 320                                     . $_SERVER['SCRIPT_NAME']</code>).
 321                             </para>
 322                         </footnote>
 323
 324                         as binding name,
 325                     </para>
 326                 </listitem>
 327
 328                 <listitem>
 329                     <para>
 330                         script <acronym>URI</acronym>
 331
 332                         <footnote>
 333                             <para>
 334                                 <code>'http://' .$_SERVER['HTTP_HOST'] .
 335                                     $_SERVER['SCRIPT_NAME']</code>
 336                             </para>
 337                         </footnote>
 338
 339                         as a service URI for Web Service definition using classes.
 340                     </para>
 341                 </listitem>
 342             </itemizedlist>
 343
 344             where <varname>$name</varname> is a class name for the Web Service definition mode using
 345             class and script name for the Web Service definition mode using set of functions.
 346         </para>
 347
 348         <para>
 349             See <ulink url="http://www.w3.org/TR/wsdl#_services"/> for the details.
 350         </para>
 351     </sect2>
 352
 353     <sect2 id="zend.soap.wsdl.types">
 354         <title>Type mapping</title>
 355
 356         <para>
 357             <classname>Zend_Soap</classname> WSDL accessor implementation uses the following type
 358             mapping between <acronym>PHP</acronym> and <acronym>SOAP</acronym> types:
 359
 360             <itemizedlist>
 361                 <listitem>
 362                     <para>PHP strings &lt;-&gt; <code>xsd:string</code>.</para>
 363                 </listitem>
 364
 365                 <listitem>
 366                     <para>PHP integers &lt;-&gt; <code>xsd:int</code>.</para>
 367                 </listitem>
 368
 369                 <listitem>
 370                     <para>PHP floats and doubles &lt;-&gt; <code>xsd:float</code>.</para>
 371                 </listitem>
 372
 373                 <listitem>
 374                     <para>PHP booleans &lt;-&gt; <code>xsd:boolean</code>.</para>
 375                 </listitem>
 376
 377                 <listitem>
 378                     <para>PHP arrays &lt;-&gt; <code>soap-enc:Array</code>.</para>
 379                 </listitem>
 380
 381                 <listitem>
 382                     <para>PHP object &lt;-&gt; <code>xsd:struct</code>.</para>
 383                 </listitem>
 384
 385                 <listitem>
 386                     <para>
 387                         <acronym>PHP</acronym> class &lt;-&gt; based on complex type strategy (See:
 388                         <xref linkend="zend.soap.wsdl.types.add_complex" />)
 389
 390                         <footnote>
 391                             <para>
 392                                 By default <classname>Zend_Soap_Wsdl</classname> will be created
 393                                 with the
 394                                 <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>
 395                                 class as detection algorithm for complex types. The first parameter
 396                                 of the AutoDiscover constructor takes any complex type strategy
 397                                 implementing
 398                                 <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> or a string
 399                                 with the name of the class. For backwards compatibility with
 400                                 <varname>$extractComplexType</varname> boolean variables are parsed
 401                                 the following way: If <constant>TRUE</constant>,
 402                                 <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>,
 403                                 if <constant>FALSE</constant>
 404                                 <classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>.
 405                             </para>
 406                         </footnote>.
 407                     </para>
 408                 </listitem>
 409
 410                 <listitem>
 411                     <para>PHP void &lt;-&gt; empty type.</para>
 412                 </listitem>
 413
 414                 <listitem>
 415                     <para>
 416                         If type is not matched to any of these types by some reason, then
 417                         <code>xsd:anyType</code> is used.
 418                     </para>
 419                 </listitem>
 420             </itemizedlist>
 421
 422             Where <code>xsd:</code> is "http://www.w3.org/2001/XMLSchema" namespace,
 423             <code>soap-enc:</code> is a "http://schemas.xmlsoap.org/soap/encoding/" namespace,
 424             <code>tns:</code> is a "target namespace" for a service.
 425         </para>
 426
 427         <sect3 id="zend.soap.wsdl.types.retrieve">
 428             <title>Retrieving type information</title>
 429
 430             <para>
 431                 <methodname>getType($type)</methodname> method may be used to get mapping for a
 432                 specified <acronym>PHP</acronym> type:
 433
 434                <programlisting language="php"><![CDATA[
 435 ...
 436 $wsdl = new Zend_Soap_Wsdl('My_Web_Service', $myWebServiceUri);
 437
 438 ...
 439 $soapIntType = $wsdl->getType('int');
 440
 441 ...
 442 class MyClass {
 443     ...
 444 }
 445 ...
 446 $soapMyClassType = $wsdl->getType('MyClass');
 447 ]]></programlisting>
 448             </para>
 449         </sect3>
 450
 451         <sect3 id="zend.soap.wsdl.types.add_complex">
 452             <title>Adding complex type information</title>
 453
 454             <para>
 455                 <methodname>addComplexType($type)</methodname> method is used to add complex types
 456                 (PHP classes) to a WSDL document.
 457             </para>
 458
 459             <para>
 460                 It's automatically used by <methodname>getType()</methodname> method to add
 461                 corresponding complex types of method parameters or return types.
 462             </para>
 463
 464             <para>
 465                 Its detection and building algorithm is based on the currently active detection
 466                 strategy for complex types. You can set the detection strategy either by specifying
 467                 the class name as string or instance of a
 468                 <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> implementation as the third
 469                 parameter of the constructor or using the
 470                 <methodname>setComplexTypeStrategy($strategy)</methodname> function of
 471                 <classname>Zend_Soap_Wsdl</classname>. The following detection strategies currently
 472                 exist:
 473             </para>
 474
 475             <itemizedlist>
 476                 <listitem>
 477                     <para>
 478                         Class <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>:
 479                         Enabled by default (when no third constructor parameter is set). Iterates
 480                         over the public attributes of a class type and registers them as subtypes of
 481                         the complex object type.
 482                     </para>
 483                 </listitem>
 484
 485                 <listitem>
 486                     <para>
 487                         Class <classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>: Casts all
 488                         complex types into the simple XSD type xsd:anyType. Be careful this shortcut
 489                         for complex type detection can probably only be handled successfully by
 490                         weakly typed languages such as <acronym>PHP</acronym>.
 491                     </para>
 492                 </listitem>
 493
 494                 <listitem>
 495                     <para>
 496                         Class <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence</classname>:
 497                         This strategy allows to specify return parameters of the type:
 498                         <code>int[]</code> or <code>string[]</code>. As of Zend Framework version
 499                         1.9 it can handle both simple <acronym>PHP</acronym> types such as int,
 500                         string, boolean, float aswell as objects and arrays of objects.
 501                     </para>
 502                 </listitem>
 503
 504                 <listitem>
 505                     <para>
 506                         Class <classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeComplex</classname>:
 507                         This strategy allows to detect very complex arrays of objects. Objects types
 508                         are detected based on the
 509                         <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> and an
 510                         array is wrapped around that definition.
 511                     </para>
 512                 </listitem>
 513
 514                 <listitem>
 515                     <para>
 516                         Class <classname>Zend_Soap_Wsdl_Strategy_Composite</classname>: This
 517                         strategy can combine all strategies by connecting <acronym>PHP</acronym>
 518                         Complex types (Classnames) to the desired strategy via the
 519                         <methodname>connectTypeToStrategy($type, $strategy)</methodname> method. A
 520                         complete typemap can be given to the constructor as an array with
 521                         <varname>$type</varname> -> <varname>$strategy</varname> pairs. The second
 522                         parameter specifies the default strategy that will be used if an unknown
 523                         type is requested for adding. This parameter defaults to the
 524                         <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname> strategy.
 525                     </para>
 526                 </listitem>
 527             </itemizedlist>
 528
 529             <para>
 530                 <methodname>addComplexType()</methodname> method creates
 531                 '/definitions/types/xsd:schema/xsd:complexType' element for
 532                 each described complex type with name of the specified <acronym>PHP</acronym> class.
 533             </para>
 534
 535             <para>
 536                 Class property <emphasis>MUST</emphasis> have docblock section with the described
 537                 <acronym>PHP</acronym> type to have property included into WSDL description.
 538             </para>
 539
 540             <para>
 541                 <methodname>addComplexType()</methodname> checks if type is already described within
 542                 types section of the WSDL document.
 543             </para>
 544
 545             <para>
 546                 It prevents duplications if this method is called two or more times and recursion in
 547                 the types definition section.
 548             </para>
 549
 550             <para>
 551                 See <ulink url="http://www.w3.org/TR/wsdl#_types"/> for the details.
 552             </para>
 553         </sect3>
 554     </sect2>
 555
 556     <sect2 id="zend.soap.wsdl.add_documentation">
 557         <title>addDocumentation() method</title>
 558
 559         <para>
 560             <methodname>addDocumentation($input_node, $documentation)</methodname> method adds human
 561             readable documentation using optional 'wsdl:document' element.
 562         </para>
 563
 564         <para>
 565             '/definitions/binding/soap:binding' element is used to signify that the binding is bound
 566             to the <acronym>SOAP</acronym> protocol format.
 567         </para>
 568
 569         <para>
 570             See <ulink url="http://www.w3.org/TR/wsdl#_documentation"/> for the details.
 571         </para>
 572     </sect2>
 573
 574     <sect2 id="zend.soap.wsdl.retrieve">
 575         <title>Get finalized WSDL document</title>
 576
 577         <para>
 578             <methodname>toXML()</methodname>, <methodname>toDomDocument()</methodname> and
 579             <methodname>dump($filename = false)</methodname> methods may be used to get WSDL
 580             document as an <acronym>XML</acronym>, DOM structure or a file.
 581         </para>
 582     </sect2>
 583 </sect1>