documentation/manual/en/module_specs/Zend_Soap_AutoDiscovery.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.soap.autodiscovery">
   4     <title>AutoDiscovery</title>
   5
   6     <sect2 id="zend.soap.autodiscovery.introduction">
   7         <title>AutoDiscovery Introduction</title>
   8
   9         <para>
  10             <acronym>SOAP</acronym> functionality implemented within Zend Framework is intended to
  11             make all steps required for <acronym>SOAP</acronym> communications more simple.
  12         </para>
  13
  14         <para>
  15             <acronym>SOAP</acronym> is language independent protocol. So it may be used not only for
  16             <acronym>PHP</acronym>-to-PHP communications.
  17         </para>
  18
  19         <para>
  20             There are three configurations for <acronym>SOAP</acronym> applications where Zend
  21             Framework may be utilized:
  22
  23             <orderedlist>
  24                 <listitem>
  25                     <simpara>
  26                         SOAP server <acronym>PHP</acronym> application &lt;---&gt;
  27                         <acronym>SOAP</acronym> client <acronym>PHP</acronym> application
  28                     </simpara>
  29                 </listitem>
  30
  31                 <listitem>
  32                     <simpara>
  33                         SOAP server non-PHP application &lt;---&gt; <acronym>SOAP</acronym>
  34                         client <acronym>PHP</acronym> application
  35                     </simpara>
  36                 </listitem>
  37
  38                 <listitem>
  39                     <simpara>
  40                         SOAP server <acronym>PHP</acronym> application &lt;---&gt;
  41                         <acronym>SOAP</acronym> client non-PHP application
  42                     </simpara>
  43                 </listitem>
  44             </orderedlist>
  45         </para>
  46
  47         <para>
  48             We always have to know, which functionality is provided by <acronym>SOAP</acronym>
  49             server to operate with it. <ulink url="http://www.w3.org/TR/wsdl">WSDL</ulink> is used
  50             to describe network service <acronym>API</acronym> in details.
  51         </para>
  52
  53         <para>
  54             WSDL language is complex enough (see <ulink
  55                 url="http://www.w3.org/TR/wsdl">http://www.w3.org/TR/wsdl</ulink>
  56             for the details). So it's difficult to prepare correct WSDL description.
  57         </para>
  58
  59         <para>
  60             Another problem is synchronizing changes in network service <acronym>API</acronym> with
  61             already existing WSDL.
  62         </para>
  63
  64         <para>
  65             Both these problem may be solved by WSDL autogeneration. A prerequisite for this is a
  66             <acronym>SOAP</acronym> server autodiscovery. It constructs object similar to object
  67             used in <acronym>SOAP</acronym> server application, extracts necessary information and
  68             generates correct WSDL using this information.
  69         </para>
  70
  71         <para>
  72             There are two ways for using Zend Framework for <acronym>SOAP</acronym> server
  73             application:
  74
  75             <itemizedlist>
  76                 <listitem>
  77                     <para>Use separated class.</para>
  78                 </listitem>
  79
  80                 <listitem>
  81                     <para>Use set of functions</para>
  82                 </listitem>
  83             </itemizedlist>
  84         </para>
  85
  86         <para>
  87             Both methods are supported by Zend Framework Autodiscovery functionality.
  88         </para>
  89
  90         <para>
  91             The<classname>Zend_Soap_AutoDiscover</classname> class also supports datatypes mapping
  92             from <acronym>PHP</acronym> to <ulink
  93                 url="http://www.w3.org/TR/xmlschema-2/">XSD types</ulink>.
  94         </para>
  95
  96         <para>
  97             Here is an example of common usage of the autodiscovery functionality. The
  98             <methodname>handle()</methodname> function generates the WSDL file and posts it to the
  99             browser.
 100
 101             <programlisting language="php"><![CDATA[
 102 class My_SoapServer_Class {
 103 ...
 104 }
 105
 106 $autodiscover = new Zend_Soap_AutoDiscover();
 107 $autodiscover->setClass('My_SoapServer_Class');
 108 $autodiscover->handle();
 109 ]]></programlisting>
 110         </para>
 111
 112         <para>
 113             If you need access to the generated WSDL file either to save it to a file or as an
 114             <acronym>XML</acronym> string you can use the <methodname>dump($filename)</methodname>
 115             or <methodname>toXml()</methodname> functions the AutoDiscover class provides.
 116         </para>
 117
 118         <note id="zend.soap.autodiscovery.introduction.noserver">
 119             <title>Zend_Soap_Autodiscover is not a Soap Server</title>
 120
 121             <para>
 122                 It is very important to note, that the class
 123                 <classname>Zend_Soap_AutoDiscover</classname> does not act as a
 124                 <acronym>SOAP</acronym> Server on its own. It only generates the WSDL and serves it
 125                 to anyone accessing the url it is listening on.
 126             </para>
 127
 128             <para>
 129                 As the <acronym>SOAP</acronym> Endpoint Uri is uses the default
 130                 <code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code>, but this
 131                 can be changed with the <methodname>setUri()</methodname> function or the
 132                 Constructor parameter of <classname>Zend_Soap_AutoDiscover</classname> class. The
 133                 endpoint has to provide a <classname>Zend_Soap_Server</classname> that listens to
 134                 requests.
 135             </para>
 136
 137             <para>
 138                 <programlisting language="php"><![CDATA[
 139 if(isset($_GET['wsdl'])) {
 140     $autodiscover = new Zend_Soap_AutoDiscover();
 141     $autodiscover->setClass('HelloWorldService');
 142     $autodiscover->handle();
 143 } else {
 144     // pointing to the current file here
 145     $soap = new Zend_Soap_Server("http://example.com/soap.php?wsdl");
 146     $soap->setClass('HelloWorldService');
 147     $soap->handle();
 148 }
 149 ]]></programlisting>
 150             </para>
 151         </note>
 152     </sect2>
 153
 154     <sect2 id="zend.soap.autodiscovery.class">
 155         <title>Class autodiscovering</title>
 156
 157         <para>
 158             If class is used to provide SOAP server functionality, then the same class should be
 159             provided to <classname>Zend_Soap_AutoDiscover</classname> for WSDL generation:
 160
 161             <programlisting language="php"><![CDATA[
 162 $autodiscover = new Zend_Soap_AutoDiscover();
 163 $autodiscover->setClass('My_SoapServer_Class');
 164 $autodiscover->handle();
 165 ]]></programlisting>
 166         </para>
 167
 168         <para>
 169             The following rules are used while WSDL generation:
 170
 171             <itemizedlist>
 172                 <listitem>
 173                     <para>Generated WSDL describes an RPC style Web Service.</para>
 174                 </listitem>
 175
 176                 <listitem>
 177                     <para>Class name is used as a name of the Web Service being described.</para>
 178                 </listitem>
 179
 180                 <listitem>
 181                     <para>
 182                         <code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code> is
 183                         used as an <acronym>URI</acronym> where the WSDL is available by default but
 184                         can be overwritten via <methodname>setUri()</methodname> method.
 185                     </para>
 186
 187                     <para>
 188                          It's also used as a target namespace for all service related names
 189                          (including described complex types).
 190                     </para>
 191                 </listitem>
 192
 193                 <listitem>
 194                     <para>
 195                         Class methods are joined into one <ulink
 196                             url="http://www.w3.org/TR/wsdl#_porttypes">Port Type</ulink>.
 197                     </para>
 198
 199                     <para>
 200                         <code>$className . 'Port'</code> is used as Port Type name.
 201                     </para>
 202                 </listitem>
 203
 204                 <listitem>
 205                     <para>Each class method is registered as a corresponding port operation.</para>
 206                 </listitem>
 207
 208                 <listitem>
 209                     <para>
 210                         Each method prototype generates corresponding Request/Response messages.
 211                     </para>
 212
 213                     <para>
 214                         Method may have several prototypes if some method parameters are optional.
 215                     </para>
 216                 </listitem>
 217             </itemizedlist>
 218         </para>
 219
 220         <note>
 221             <title>Important!</title>
 222
 223             <para>
 224                 WSDL autodiscovery utilizes the <acronym>PHP</acronym> docblocks provided by the
 225                 developer to determine the parameter and return types. In fact, for scalar types,
 226                 this is the only way to determine the parameter types, and for return types, this is
 227                 the only way to determine them.
 228             </para>
 229
 230             <para>
 231                 That means, providing correct and fully detailed docblocks is not only best
 232                 practice, but is required for discovered class.
 233             </para>
 234         </note>
 235     </sect2>
 236
 237     <sect2 id="zend.soap.autodiscovery.functions">
 238         <title>Functions autodiscovering</title>
 239
 240         <para>
 241             If set of functions are used to provide SOAP server functionality, then the same set
 242             should be provided to <classname>Zend_Soap_AutoDiscovery</classname> for WSDL
 243             generation:
 244
 245             <programlisting language="php"><![CDATA[
 246 $autodiscover = new Zend_Soap_AutoDiscover();
 247 $autodiscover->addFunction('function1');
 248 $autodiscover->addFunction('function2');
 249 $autodiscover->addFunction('function3');
 250 ...
 251 $autodiscover->handle();
 252 ]]></programlisting>
 253         </para>
 254
 255         <para>
 256             The following rules are used while WSDL generation:
 257
 258             <itemizedlist>
 259                 <listitem>
 260                     <para>Generated WSDL describes an RPC style Web Service.</para>
 261                 </listitem>
 262
 263                 <listitem>
 264                     <para>
 265                         Current script name is used as a name of the Web Service being described.
 266                     </para>
 267                 </listitem>
 268
 269                 <listitem>
 270                     <para>
 271                         <code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code> is
 272                         used as an <acronym>URI</acronym> where the WSDL is available.
 273                     </para>
 274
 275                     <para>
 276                          It's also used as a target namespace for all service related names
 277                          (including described complex types).
 278                     </para>
 279                 </listitem>
 280
 281                 <listitem>
 282                     <para>
 283                         Functions are joined into one <ulink
 284                             url="http://www.w3.org/TR/wsdl#_porttypes">Port Type</ulink>.
 285                     </para>
 286
 287                     <para>
 288                         <code>$functionName . 'Port'</code> is used as Port Type name.
 289                     </para>
 290                 </listitem>
 291
 292                 <listitem>
 293                     <para>Each function is registered as a corresponding port operation.</para>
 294                 </listitem>
 295
 296                 <listitem>
 297                     <para>
 298                         Each function prototype generates corresponding Request/Response messages.
 299                     </para>
 300
 301                     <para>
 302                         Function may have several prototypes if some method parameters are optional.
 303                     </para>
 304                 </listitem>
 305             </itemizedlist>
 306         </para>
 307
 308         <note>
 309             <title>Important!</title>
 310
 311             <para>
 312                 WSDL autodiscovery utilizes the <acronym>PHP</acronym> docblocks provided by the
 313                 developer to determine the parameter and return types. In fact, for scalar types,
 314                 this is the only way to determine the parameter types, and for return types, this is
 315                 the only way to determine them.
 316             </para>
 317
 318             <para>
 319                 That means, providing correct and fully detailed docblocks is not only best
 320                 practice, but is required for discovered class.
 321             </para>
 322         </note>
 323     </sect2>
 324
 325     <sect2 id="zend.soap.autodiscovery.datatypes">
 326         <title>Autodiscovering Datatypes</title>
 327
 328         <para>
 329             Input/output datatypes are converted into network service types using the following
 330             mapping:
 331
 332             <itemizedlist>
 333                 <listitem>
 334                     <para>PHP strings &lt;-&gt; <code>xsd:string</code>.</para>
 335                 </listitem>
 336
 337                 <listitem>
 338                     <para>PHP integers &lt;-&gt; <code>xsd:int</code>.</para>
 339                 </listitem>
 340
 341                 <listitem>
 342                     <para>PHP floats and doubles &lt;-&gt; <code>xsd:float</code>.</para>
 343                 </listitem>
 344
 345                 <listitem>
 346                     <para>PHP booleans &lt;-&gt; <code>xsd:boolean</code>.</para>
 347                 </listitem>
 348
 349                 <listitem>
 350                     <para>PHP arrays &lt;-&gt; <code>soap-enc:Array</code>.</para>
 351                 </listitem>
 352
 353                 <listitem>
 354                     <para>PHP object &lt;-&gt; <code>xsd:struct</code>.</para>
 355                 </listitem>
 356
 357                 <listitem>
 358                     <para>
 359                         <acronym>PHP</acronym> class &lt;-&gt; based on complex type strategy (See:
 360                         <xref linkend="zend.soap.wsdl.types.add_complex" />)
 361
 362                         <footnote>
 363                             <para>
 364                                 <classname>Zend_Soap_AutoDiscover</classname> will be created with
 365                                 the
 366                                 <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>
 367                                 class as detection algorithm for complex types. The first parameter
 368                                 of the AutoDiscover constructor takes any complex type strategy
 369                                 implementing
 370                                 <classname>Zend_Soap_Wsdl_Strategy_Interface</classname> or a string
 371                                 with the name of the class. For backwards compatibility with
 372                                 <varname>$extractComplexType</varname> boolean variables are parsed
 373                                 exactly like in <classname>Zend_Soap_Wsdl</classname>. See the
 374                                 <link
 375                                     linkend="zend.soap.wsdl.types.add_complex"><classname>Zend_Soap_Wsdl</classname>
 376                                     manual on adding complex</link> types for more information.
 377                             </para>
 378                         </footnote>.
 379                     </para>
 380                 </listitem>
 381
 382                 <listitem>
 383                     <para>
 384                         type[] or object[] (ie. int[]) &lt;-&gt; based on complex type strategy
 385                     </para>
 386                 </listitem>
 387
 388                 <listitem>
 389                     <para>PHP void &lt;-&gt; empty type.</para>
 390                 </listitem>
 391
 392                 <listitem>
 393                     <para>
 394                         If type is not matched to any of these types by some reason, then
 395                         <code>xsd:anyType</code> is used.
 396                     </para>
 397                 </listitem>
 398             </itemizedlist>
 399
 400             Where <code>xsd:</code> is "http://www.w3.org/2001/XMLSchema" namespace,
 401             <code>soap-enc:</code> is a "http://schemas.xmlsoap.org/soap/encoding/" namespace,
 402             <code>tns:</code> is a "target namespace" for a service.
 403         </para>
 404     </sect2>
 405
 406     <sect2 id="zend.soap.autodiscovery.wsdlstyles">
 407         <title>WSDL Binding Styles</title>
 408
 409         <para>
 410             WSDL offers different transport mechanisms and styles. This affects the
 411             <code>soap:binding</code> and <code>soap:body</code> tags within the Binding
 412             section of WSDL. Different clients have different requirements as to what options
 413             really work. Therefore you can set the styles before you call any <code>setClass</code>
 414             or <code>addFunction</code> method on the AutoDiscover class.
 415         </para>
 416
 417         <para>
 418             <programlisting language="php"><![CDATA[
 419 $autodiscover = new Zend_Soap_AutoDiscover();
 420 // Default is 'use' => 'encoded' and
 421 // 'encodingStyle' => 'http://schemas.xmlsoap.org/soap/encoding/'
 422 $autodiscover->setOperationBodyStyle(
 423                     array('use' => 'literal',
 424                           'namespace' => 'http://framework.zend.com')
 425                 );
 426
 427 // Default is 'style' => 'rpc' and
 428 // 'transport' => 'http://schemas.xmlsoap.org/soap/http'
 429 $autodiscover->setBindingStyle(
 430                     array('style' => 'document',
 431                           'transport' => 'http://framework.zend.com')
 432                 );
 433 ...
 434 $autodiscover->addFunction('myfunc1');
 435 $autodiscover->handle();
 436 ]]></programlisting>
 437         </para>
 438     </sect2>
 439 </sect1>