documentation/manual/en/module_specs/Zend_Soap_Server.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.soap.server">
   4     <title>Zend_Soap_Server</title>
   5
   6     <para>
   7         <classname>Zend_Soap_Server</classname> class is intended to simplify Web Services server
   8         part development for <acronym>PHP</acronym> programmers.
   9     </para>
  10
  11     <para>
  12         It may be used in WSDL or non-WSDL mode, and using classes or functions to define Web
  13         Service <acronym>API</acronym>.
  14     </para>
  15
  16     <para>
  17         When <classname>Zend_Soap_Server</classname> component works in the WSDL mode, it uses
  18         already prepared WSDL document to define server object behavior and transport layer options.
  19     </para>
  20
  21     <para>
  22         WSDL document may be auto-generated with functionality provided by <link
  23             linkend="zend.soap.autodiscovery.introduction">Zend_Soap_AutoDiscovery component</link>
  24         or should be constructed manually using <link
  25             linkend="zend.soap.wsdl"><classname>Zend_Soap_Wsdl</classname> class</link> or any other
  26         <acronym>XML</acronym> generating tool.
  27     </para>
  28
  29     <para>
  30         If the non-WSDL mode is used, then all protocol options have to be set using options
  31         mechanism.
  32     </para>
  33
  34     <sect2 id="zend.soap.server.constructor">
  35         <title>Zend_Soap_Server constructor</title>
  36
  37         <para>
  38             <classname>Zend_Soap_Server</classname> constructor should be used a bit differently for
  39             WSDL and non-WSDL modes.
  40         </para>
  41
  42         <sect3 id="zend.soap.server.constructor.wsdl_mode">
  43             <title>Zend_Soap_Server constructor for the WSDL mode</title>
  44
  45             <para>
  46                 <classname>Zend_Soap_Server</classname> constructor takes two optional parameters
  47                 when it works in WSDL mode:
  48
  49                 <orderedlist>
  50                     <listitem>
  51                         <para>
  52                             <varname>$wsdl</varname>, which is an <acronym>URI</acronym> of a WSDL
  53                             file
  54
  55                             <footnote>
  56                                 <para>
  57                                     May be set later using <methodname>setWsdl($wsdl)</methodname>
  58                                     method.
  59                                 </para>
  60                             </footnote>.
  61                         </para>
  62                     </listitem>
  63
  64                     <listitem>
  65                         <para>
  66                             <varname>$options</varname> - options to create <acronym>SOAP</acronym>
  67                             server object
  68
  69                             <footnote>
  70                                 <para>
  71                                     Options may be set later using
  72                                     <methodname>setOptions($options)</methodname> method.
  73                                 </para>
  74                             </footnote>.
  75                         </para>
  76
  77                         <para>
  78                             The following options are recognized in the WSDL mode:
  79
  80                             <itemizedlist>
  81                                 <listitem>
  82                                     <para>
  83                                         'soap_version' ('soapVersion') - soap version to use
  84                                         (SOAP_1_1 or <acronym>SOAP</acronym>_1_2).
  85                                     </para>
  86                                 </listitem>
  87
  88                                 <listitem>
  89                                     <para>
  90                                         'actor' - the actor <acronym>URI</acronym> for the server.
  91                                     </para>
  92                                 </listitem>
  93
  94                                 <listitem>
  95                                     <para>
  96                                         'classmap' ('classMap') which can be used to map some WSDL
  97                                         types to <acronym>PHP</acronym> classes.
  98                                     </para>
  99
 100                                     <para>
 101                                         The option must be an array with WSDL types as keys and
 102                                         names of <acronym>PHP</acronym> classes as values.
 103                                     </para>
 104                                 </listitem>
 105
 106                                 <listitem>
 107                                     <para>
 108                                         'encoding' - internal character encoding (UTF-8 is always
 109                                         used as an external encoding).
 110                                     </para>
 111                                 </listitem>
 112
 113                                 <listitem>
 114                                     <para>
 115                                         'wsdl' which is equivalent to
 116                                         <methodname>setWsdl($wsdlValue)</methodname> call.
 117                                     </para>
 118                                 </listitem>
 119                             </itemizedlist>
 120                         </para>
 121                     </listitem>
 122                 </orderedlist>
 123             </para>
 124         </sect3>
 125
 126         <sect3 id="zend.soap.server.wsdl_mode">
 127             <title>Zend_Soap_Server constructor for the non-WSDL mode</title>
 128
 129             <para>
 130                 The first constructor parameter <emphasis>must</emphasis> be set to
 131                 <constant>NULL</constant> if you plan to use <classname>Zend_Soap_Server</classname>
 132                 functionality in non-WSDL mode.
 133             </para>
 134
 135             <para>
 136                 You also have to set 'uri' option in this case (see below).
 137             </para>
 138
 139             <para>
 140                 The second constructor parameter (<varname>$options</varname>) is an array with
 141                 options to create <acronym>SOAP</acronym> server object
 142
 143                 <footnote>
 144                     <para>
 145                         Options may be set later using <methodname>setOptions($options)</methodname>
 146                         method.
 147                     </para>
 148                 </footnote>.
 149             </para>
 150
 151             <para>
 152                 The following options are recognized in the non-WSDL mode:
 153
 154                 <itemizedlist>
 155                     <listitem>
 156                         <para>
 157                             'soap_version' ('soapVersion') - soap version to use (SOAP_1_1 or
 158                             <acronym>SOAP</acronym>_1_2).
 159                         </para>
 160                     </listitem>
 161
 162                     <listitem>
 163                         <para>
 164                             'actor' - the actor <acronym>URI</acronym> for the server.
 165                         </para>
 166                     </listitem>
 167
 168                     <listitem>
 169                         <para>
 170                             'classmap' ('classMap') which can be used to map some WSDL types to
 171                             <acronym>PHP</acronym> classes.
 172                         </para>
 173
 174                         <para>
 175                             The option must be an array with WSDL types as keys and names of
 176                             <acronym>PHP</acronym> classes as values.
 177                         </para>
 178                     </listitem>
 179
 180                     <listitem>
 181                         <para>
 182                             'encoding' - internal character encoding (UTF-8 is always used as an
 183                             external encoding).
 184                         </para>
 185                     </listitem>
 186
 187                     <listitem>
 188                         <para>
 189                             'uri' (required) - <acronym>URI</acronym> namespace for
 190                             <acronym>SOAP</acronym> server.
 191                         </para>
 192                     </listitem>
 193                 </itemizedlist>
 194             </para>
 195         </sect3>
 196     </sect2>
 197
 198     <sect2 id="zend.soap.server.api_define_methods">
 199         <title>Methods to define Web Service API</title>
 200
 201         <para>
 202             There are two ways to define Web Service <acronym>API</acronym> when your want to give
 203             access to your <acronym>PHP</acronym> code through <acronym>SOAP</acronym>.
 204         </para>
 205
 206         <para>
 207             The first one is to attach some class to the <classname>Zend_Soap_Server</classname>
 208             object which has to completely describe Web Service <acronym>API</acronym>:
 209         </para>
 210
 211         <programlisting language="php"><![CDATA[
 212 ...
 213 class MyClass {
 214     /**
 215      * This method takes ...
 216      *
 217      * @param integer $inputParam
 218      * @return string
 219      */
 220     public function method1($inputParam) {
 221         ...
 222     }
 223
 224     /**
 225      * This method takes ...
 226      *
 227      * @param integer $inputParam1
 228      * @param string  $inputParam2
 229      * @return float
 230      */
 231     public function method2($inputParam1, $inputParam2) {
 232         ...
 233     }
 234
 235     ...
 236 }
 237 ...
 238 $server = new Zend_Soap_Server(null, $options);
 239 // Bind Class to Soap Server
 240 $server->setClass('MyClass');
 241 // Bind already initialized object to Soap Server
 242 $server->setObject(new MyClass());
 243 ...
 244 $server->handle();
 245 ]]></programlisting>
 246
 247         <note>
 248             <title>Important!</title>
 249
 250             <para>
 251                 You should completely describe each method using method docblock if you plan to
 252                 use autodiscover functionality to prepare corresponding Web Service WSDL.
 253             </para>
 254         </note>
 255
 256         <para>
 257             The second method of defining Web Service <acronym>API</acronym> is using set of
 258             functions and <methodname>addFunction()</methodname> or
 259             <methodname>loadFunctions()</methodname> methods:
 260         </para>
 261
 262         <programlisting language="php"><![CDATA[
 263 ...
 264 /**
 265  * This function ...
 266  *
 267  * @param integer $inputParam
 268  * @return string
 269  */
 270 function function1($inputParam) {
 271     ...
 272 }
 273
 274 /**
 275  * This function ...
 276  *
 277  * @param integer $inputParam1
 278  * @param string  $inputParam2
 279  * @return float
 280  */
 281 function function2($inputParam1, $inputParam2) {
 282     ...
 283 }
 284 ...
 285 $server = new Zend_Soap_Server(null, $options);
 286 $server->addFunction('function1');
 287 $server->addFunction('function2');
 288 ...
 289 $server->handle();
 290 ]]></programlisting>
 291     </sect2>
 292
 293     <sect2 id="zend.soap.server.request_response">
 294         <title>Request and response objects handling</title>
 295
 296         <note>
 297             <title>Advanced</title>
 298
 299             <para>
 300                 This section describes advanced request/response processing options and may be
 301                 skipped.
 302             </para>
 303         </note>
 304
 305         <para>
 306             <classname>Zend_Soap_Server</classname> component performs request/response processing
 307             automatically, but allows to catch it and do some pre- and post-processing.
 308         </para>
 309
 310         <sect3 id="zend.soap.server.request_response.request">
 311             <title>Request processing</title>
 312
 313             <para>
 314                 <methodname>Zend_Soap_Server::handle()</methodname> method takes request from the
 315                 standard input stream ('php://input'). It may be overridden either by supplying
 316                 optional parameter to the <methodname>handle()</methodname> method or by setting
 317                 request using <methodname>setRequest()</methodname> method:
 318             </para>
 319
 320             <programlisting language="php"><![CDATA[
 321 ...
 322 $server = new Zend_Soap_Server(...);
 323 ...
 324 // Set request using optional $request parameter
 325 $server->handle($request);
 326 ...
 327 // Set request using setRequest() method
 328 $server->setRequest();
 329 $server->handle();
 330 ]]></programlisting>
 331
 332             <para>
 333                 Request object may be represented using any of the following:
 334
 335                 <itemizedlist>
 336                     <listitem>
 337                         <para>
 338                             DOMDocument (casted to <acronym>XML</acronym>)
 339                         </para>
 340                     </listitem>
 341
 342                     <listitem>
 343                         <para>
 344                             DOMNode (owner document is grabbed and casted to <acronym>XML</acronym>)
 345                         </para>
 346                     </listitem>
 347
 348                     <listitem>
 349                         <para>
 350                             SimpleXMLElement (casted to <acronym>XML</acronym>)
 351                         </para>
 352                     </listitem>
 353
 354                     <listitem>
 355                         <para>
 356                             stdClass (__toString() is called and verified to be valid
 357                             <acronym>XML</acronym>)
 358                         </para>
 359                     </listitem>
 360
 361                     <listitem>
 362                         <para>
 363                             string (verified to be valid <acronym>XML</acronym>)
 364                         </para>
 365                     </listitem>
 366                 </itemizedlist>
 367             </para>
 368
 369             <para>
 370                 Last processed request may be retrieved using
 371                 <methodname>getLastRequest()</methodname> method as an <acronym>XML</acronym>
 372                 string:
 373             </para>
 374
 375             <programlisting language="php"><![CDATA[
 376 ...
 377 $server = new Zend_Soap_Server(...);
 378 ...
 379 $server->handle();
 380 $request = $server->getLastRequest();
 381 ]]></programlisting>
 382         </sect3>
 383
 384         <sect3 id="zend.soap.server.request_response.response">
 385             <title>Response pre-processing</title>
 386
 387             <para>
 388                 <methodname>Zend_Soap_Server::handle()</methodname> method automatically emits
 389                 generated response to the output stream. It may be blocked using
 390                 <methodname>setReturnResponse()</methodname> with <constant>TRUE</constant> or
 391                 <constant>FALSE</constant> as a parameter
 392
 393                 <footnote>
 394                     <para>
 395                         Current state of the Return Response flag may be requested with
 396                         <methodname>setReturnResponse()</methodname> method.
 397                     </para>
 398                 </footnote>.
 399
 400                 Generated response is returned by <methodname>handle()</methodname> method in this
 401                 case.
 402             </para>
 403
 404             <programlisting language="php"><![CDATA[
 405 ...
 406 $server = new Zend_Soap_Server(...);
 407 ...
 408 // Get a response as a return value of handle() method
 409 // instead of emitting it to the standard output
 410 $server->setReturnResponse(true);
 411 ...
 412 $response = $server->handle();
 413 ...
 414 ]]></programlisting>
 415
 416             <para>
 417                 Last response may be also retrieved by <methodname>getLastResponse()</methodname>
 418                 method for some post-processing:
 419             </para>
 420
 421             <programlisting language="php"><![CDATA[
 422 ...
 423 $server = new Zend_Soap_Server(...);
 424 ...
 425 $server->handle();
 426 $response = $server->getLastResponse();
 427 ...
 428 ]]></programlisting>
 429         </sect3>
 430     </sect2>
 431 </sect1>