documentation/manual/en/module_specs/Zend_Soap_Client.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.soap.client">
   4     <title>Zend_Soap_Client</title>
   5
   6     <para>
   7         The <classname>Zend_Soap_Client</classname> class simplifies <acronym>SOAP</acronym> client
   8         development for <acronym>PHP</acronym> programmers.
   9     </para>
  10
  11     <para>
  12         It may be used in WSDL or non-WSDL mode.
  13     </para>
  14
  15     <para>
  16         Under the WSDL mode, the <classname>Zend_Soap_Client</classname> component uses a WSDL
  17         document to define transport layer options.
  18     </para>
  19
  20     <para>
  21         The WSDL description is usually provided by the web service the client will access. If the
  22         WSDL description is not made available, you may want to use
  23         <classname>Zend_Soap_Client</classname> in non-WSDL mode. Under this mode, all
  24         <acronym>SOAP</acronym> protocol options have to be set explicitly on the
  25         <classname>Zend_Soap_Client</classname> class.
  26     </para>
  27
  28     <sect2 id="zend.soap.client.constructor">
  29         <title>Zend_Soap_Client Constructor</title>
  30
  31         <para>
  32             The <classname>Zend_Soap_Client</classname> constructor takes two parameters:
  33
  34             <itemizedlist>
  35                 <listitem>
  36                     <para>
  37                         <varname>$wsdl</varname> - the <acronym>URI</acronym> of a WSDL file.
  38                     </para>
  39                 </listitem>
  40
  41                 <listitem>
  42                     <para>
  43                         <varname>$options</varname> - options to create <acronym>SOAP</acronym>
  44                         client object.
  45                     </para>
  46                 </listitem>
  47             </itemizedlist>
  48
  49             Both of these parameters may be set later using <methodname>setWsdl($wsdl)</methodname>
  50             and <methodname>setOptions($options)</methodname> methods respectively.
  51         </para>
  52
  53         <note>
  54             <title>Important!</title>
  55
  56             <para>
  57                 If you use <classname>Zend_Soap_Client</classname> component in non-WSDL mode, you
  58                 <emphasis>must</emphasis> set the 'location' and 'uri' options.
  59             </para>
  60         </note>
  61
  62         <para>
  63             The following options are recognized:
  64
  65             <itemizedlist>
  66                 <listitem>
  67                     <para>
  68                         'soap_version' ('soapVersion') - soap version to use (SOAP_1_1 or
  69                         <acronym>SOAP</acronym>_1_2).
  70                     </para>
  71                 </listitem>
  72
  73                 <listitem>
  74                     <para>
  75                         'classmap' ('classMap') - can be used to map some WSDL types to
  76                         <acronym>PHP</acronym> classes.
  77                     </para>
  78
  79                     <para>
  80                         The option must be an array with WSDL types as keys and names of
  81                         <acronym>PHP</acronym> classes as values.
  82                     </para>
  83                 </listitem>
  84
  85                 <listitem>
  86                     <para>
  87                         'encoding' - internal character encoding (UTF-8 is always used as an
  88                         external encoding).
  89                     </para>
  90                 </listitem>
  91
  92                 <listitem>
  93                     <para>
  94                         'wsdl' which is equivalent to <methodname>setWsdl($wsdlValue)</methodname>
  95                         call.
  96                     </para>
  97
  98                     <para>
  99                         Changing this option may switch <classname>Zend_Soap_Client</classname>
 100                         object to or from WSDL mode.
 101                     </para>
 102                 </listitem>
 103
 104                 <listitem>
 105                     <para>
 106                         'uri' - target namespace for the <acronym>SOAP</acronym> service (required
 107                         for non-WSDL-mode, doesn't work for WSDL mode).
 108                     </para>
 109                 </listitem>
 110
 111                 <listitem>
 112                     <para>
 113                         'location' - the <acronym>URL</acronym> to request (required for
 114                         non-WSDL-mode, doesn't work for WSDL mode).
 115                     </para>
 116                 </listitem>
 117
 118                 <listitem>
 119                     <para>
 120                         'style' - request style (doesn't work for WSDL mode):
 121                         <constant>SOAP_RPC</constant> or <constant>SOAP_DOCUMENT</constant>.
 122                     </para>
 123                 </listitem>
 124
 125                 <listitem>
 126                     <para>
 127                         'use' - method to encode messages (doesn't work for WSDL mode):
 128                         <constant>SOAP_ENCODED</constant> or <constant>SOAP_LITERAL</constant>.
 129                     </para>
 130                 </listitem>
 131
 132                 <listitem>
 133                     <para>
 134                         'login' and 'password' - login and password for an <acronym>HTTP</acronym>
 135                         authentication.
 136                     </para>
 137                 </listitem>
 138
 139                 <listitem>
 140                     <para>
 141                         'proxy_host', 'proxy_port', 'proxy_login', and 'proxy_password' - an
 142                         <acronym>HTTP</acronym> connection through a proxy server.
 143                     </para>
 144                 </listitem>
 145
 146                 <listitem>
 147                     <para>
 148                         'local_cert' and 'passphrase' - <acronym>HTTPS</acronym> client certificate
 149                         authentication options.
 150                     </para>
 151                 </listitem>
 152
 153                 <listitem>
 154                     <para>
 155                         'compression' - compression options; it's a combination of
 156                         <constant>SOAP_COMPRESSION_ACCEPT</constant>,
 157                         <constant>SOAP_COMPRESSION_GZIP</constant> and
 158                         <constant>SOAP_COMPRESSION_DEFLATE</constant> options which may be used like
 159                         this:
 160                     </para>
 161
 162                     <programlisting language="php"><![CDATA[
 163 // Accept response compression
 164 $client = new Zend_Soap_Client("some.wsdl",
 165   array('compression' => SOAP_COMPRESSION_ACCEPT));
 166 ...
 167
 168 // Compress requests using gzip with compression level 5
 169 $client = new Zend_Soap_Client("some.wsdl",
 170   array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5));
 171 ...
 172
 173 // Compress requests using deflate compression
 174 $client = new Zend_Soap_Client("some.wsdl",
 175   array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_DEFLATE));
 176 ]]></programlisting>
 177                 </listitem>
 178             </itemizedlist>
 179         </para>
 180     </sect2>
 181
 182     <sect2 id="zend.soap.client.calls">
 183         <title>Performing SOAP Requests</title>
 184
 185         <para>
 186             After we've created a <classname>Zend_Soap_Client</classname> object we are ready to
 187             perform <acronym>SOAP</acronym> requests.
 188         </para>
 189
 190         <para>
 191             Each web service method is mapped to the virtual <classname>Zend_Soap_Client</classname>
 192             object method which takes parameters with common <acronym>PHP</acronym> types.
 193         </para>
 194
 195         <para>
 196             Use it like in the following example:
 197         </para>
 198
 199         <programlisting language="php"><![CDATA[
 200 //****************************************************************
 201 //                Server code
 202 //****************************************************************
 203 // class MyClass {
 204 //     /**
 205 //      * This method takes ...
 206 //      *
 207 //      * @param integer $inputParam
 208 //      * @return string
 209 //      */
 210 //     public function method1($inputParam) {
 211 //         ...
 212 //     }
 213 //
 214 //     /**
 215 //      * This method takes ...
 216 //      *
 217 //      * @param integer $inputParam1
 218 //      * @param string  $inputParam2
 219 //      * @return float
 220 //      */
 221 //     public function method2($inputParam1, $inputParam2) {
 222 //         ...
 223 //     }
 224 //
 225 //     ...
 226 // }
 227 // ...
 228 // $server = new Zend_Soap_Server(null, $options);
 229 // $server->setClass('MyClass');
 230 // ...
 231 // $server->handle();
 232 //
 233 //****************************************************************
 234 //                End of server code
 235 //****************************************************************
 236
 237 $client = new Zend_Soap_Client("MyService.wsdl");
 238 ...
 239
 240 // $result1 is a string
 241 $result1 = $client->method1(10);
 242 ...
 243
 244 // $result2 is a float
 245 $result2 = $client->method2(22, 'some string');
 246 ]]></programlisting>
 247     </sect2>
 248 </sect1>