reference/soap/soapclient/construct.xml
497c40ac164d5873fd87f622dfdeb5206392b446
...
...
@@ -8,14 +8,13 @@
8
8

9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
-
<constructorsynopsis>
11
+
<constructorsynopsis role="SoapClient">
12
12
<modifier>public</modifier> <methodname>SoapClient::__construct</methodname>
13
13
<methodparam><type class="union"><type>string</type><type>null</type></type><parameter>wsdl</parameter></methodparam>
14
14
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
15
15
</constructorsynopsis>
16
16
<para>
17
-
This constructor creates <classname>SoapClient</classname> objects
18
-
in <literal>WSDL</literal> or <literal>non-WSDL</literal> mode.
17
+
Creates a <classname>SoapClient</classname> object to connect to a SOAP service.
19
18
</para>
20
19
</refsect1>
21
20

...
...
@@ -27,15 +26,17 @@
27
26
<term><parameter>wsdl</parameter></term>
28
27
<listitem>
29
28
<para>
30
-
URI of the <literal>WSDL</literal> file or &null; if working in
31
-
<literal>non-WSDL</literal> mode.
29
+
URI of a WSDL file describing the service, which is used to automatically
30
+
configure the client. If not provided, the client will operate in non-WSDL
31
+
mode.
32
32
</para>
33
33
<note>
34
34
<para>
35
-
During development, WSDL caching may be disabled by the
36
-
use of the <literal>soap.wsdl_cache_ttl</literal> &php.ini; setting
37
-
otherwise changes made to the WSDL file will have no effect until
38
-
<literal>soap.wsdl_cache_ttl</literal> is expired.
35
+
By default, the WSDL file will be cached for performance. To disable
36
+
or configure this caching, see
37
+
<link linkend="soap.configuration.list">SOAP &ConfigureOptions;</link>
38
+
and the <link linkend="soapclient.construct.options.cache-wsdl">
39
+
<literal>cache_wsdl</literal> option</link>.
39
40
</para>
40
41
</note>
41
42
</listitem>
...
...
@@ -44,116 +45,583 @@
44
45
<term><parameter>options</parameter></term>
45
46
<listitem>
46
47
<para>
47
-
An array of options. If working in WSDL mode, this parameter is optional.
48
-
If working in non-WSDL mode, the <literal>location</literal> and
49
-
<literal>uri</literal> options must be set, where <literal>location</literal>
50
-
is the URL of the SOAP server to send the request to, and <literal>uri</literal>
51
-
is the target namespace of the SOAP service.
52
-
</para>
53
-
<para>
54
-
The <literal>style</literal> and <literal>use</literal> options only work in
55
-
non-WSDL mode. In WSDL mode, they come from the WSDL file.
56
-
</para>
57
-
<para>
58
-
The <literal>soap_version</literal> option should be one of either
59
-
<constant>SOAP_1_1</constant> or <constant>SOAP_1_2</constant> to
60
-
select SOAP 1.1 or 1.2, respectively. If omitted, 1.1 is used.
61
-
</para>
62
-
<para>
63
-
For HTTP authentication, the <literal>login</literal> and
64
-
<literal>password</literal> options can be used to supply credentials.
65
-
For making an HTTP connection through
66
-
a proxy server, the options <literal>proxy_host</literal>,
67
-
<literal>proxy_port</literal>, <literal>proxy_login</literal>
68
-
and <literal>proxy_password</literal> are also available.
69
-
For HTTPS client certificate authentication use
70
-
<literal>local_cert</literal> and <literal>passphrase</literal> options. An
71
-
authentication may be supplied in the <literal>authentication</literal>
72
-
option. The authentication method may be either
73
-
<constant>SOAP_AUTHENTICATION_BASIC</constant> (default) or
74
-
<constant>SOAP_AUTHENTICATION_DIGEST</constant>.
75
-
</para>
76
-
<para>
77
-
The <literal>compression</literal> option allows to use compression
78
-
of HTTP SOAP requests and responses.
79
-
</para>
80
-
<para>
81
-
The <literal>encoding</literal> option defines internal character
82
-
encoding. This option does not change the encoding of SOAP requests (it is
83
-
always utf-8), but converts strings into it.
84
-
</para>
85
-
<para>
86
-
The <literal>trace</literal> option enables tracing of request so faults
87
-
can be backtraced. This defaults to &false;
88
-
</para>
89
-
<para>
90
-
The <literal>classmap</literal> option can be used to map some WSDL
91
-
types to PHP classes. This option must be an array with WSDL types
92
-
as keys and names of PHP classes as values.
93
-
</para>
94
-
<para>
95
-
Setting the boolean <literal>trace</literal> option enables use of the
96
-
methods <link linkend="soapclient.getlastrequest">
97
-
SoapClient->__getLastRequest</link>,
98
-
<link linkend="soapclient.getlastrequestheaders">
99
-
SoapClient->__getLastRequestHeaders</link>,
100
-
<link linkend="soapclient.getlastresponse">
101
-
SoapClient->__getLastResponse</link> and
102
-
<link linkend="soapclient.getlastresponseheaders">
103
-
SoapClient->__getLastResponseHeaders</link>.
104
-
</para>
105
-
<para>
106
-
The <literal>exceptions</literal> option is a boolean value defining whether
107
-
soap errors throw exceptions of type <link
108
-
linkend="soapfault.construct">
109
-
SoapFault</link>.
110
-
</para>
111
-
<para>
112
-
The <literal>connection_timeout</literal> option defines a timeout in seconds
113
-
for the connection to the SOAP service. This option does not define a timeout
114
-
for services with slow responses. To limit the time to wait for calls to finish the
115
-
<link linkend="ini.default-socket-timeout">default_socket_timeout</link> setting
116
-
is available.
117
-
</para>
118
-
<para>
119
-
The <literal>typemap</literal> option is an array of type mappings.
120
-
Type mapping is an array with keys <literal>type_name</literal>,
121
-
<literal>type_ns</literal> (namespace URI), <literal>from_xml</literal>
122
-
(callback accepting one string parameter) and <literal>to_xml</literal>
123
-
(callback accepting one object parameter).
124
-
</para>
125
-
<para>
126
-
The <literal>cache_wsdl</literal> option is one of
127
-
<constant>WSDL_CACHE_NONE</constant>,
128
-
<constant>WSDL_CACHE_DISK</constant>,
129
-
<constant>WSDL_CACHE_MEMORY</constant> or
130
-
<constant>WSDL_CACHE_BOTH</constant>.
131
-
</para>
132
-
<para>
133
-
The <literal>user_agent</literal> option specifies string to use in
134
-
<literal>User-Agent</literal> header.
135
-
</para>
136
-
<para>
137
-
The <literal>stream_context</literal> option is a <type>resource</type>
138
-
for <link linkend="context">context</link>.
139
-
</para>
140
-
<para>
141
-
The <literal>features</literal> option is a bitmask of
142
-
<constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant>,
143
-
<constant>SOAP_USE_XSI_ARRAY_TYPE</constant>,
144
-
<constant>SOAP_WAIT_ONE_WAY_CALLS</constant>.
145
-
</para>
146
-
<para>
147
-
The <literal>keep_alive</literal> option is a boolean value defining whether
148
-
to send the <literal>Connection: Keep-Alive</literal> header or
149
-
<literal>Connection: close</literal>.
150
-
</para>
151
-
<para>
152
-
The <literal>ssl_method</literal> option is one of
153
-
<constant>SOAP_SSL_METHOD_TLS</constant>,
154
-
<constant>SOAP_SSL_METHOD_SSLv2</constant>,
155
-
<constant>SOAP_SSL_METHOD_SSLv3</constant> or
156
-
<constant>SOAP_SSL_METHOD_SSLv23</constant>.
48
+
An associative array specifying additional options for the SOAP client.
49
+
If <parameter>wsdl</parameter> is provided, this is optional; otherwise,
50
+
at least <literal>location</literal> and <literal>url</literal> must be
51
+
provided.
52
+
<variablelist>
53
+
<varlistentry xml:id="soapclient.construct.options.location">
54
+
<term>
55
+
<parameter>location</parameter>
56
+
<type>string</type>
57
+
</term>
58
+
<listitem>
59
+
<para>
60
+
The URL of the SOAP server to send the request to.
61
+
</para>
62
+
<para>
63
+
Required if the <parameter>wsdl</parameter> parameter is not provided.
64
+
If both a <parameter>wsdl</parameter> parameter and
65
+
<literal>location</literal> option are provided, the
66
+
<literal>location</literal> option will over-ride any location
67
+
specified in the WSDL file.
68
+
</para>
69
+
</listitem>
70
+
</varlistentry>
71
+
<varlistentry xml:id="soapclient.construct.options.uri">
72
+
<term>
73
+
<parameter>uri</parameter>
74
+
<type>string</type>
75
+
</term>
76
+
<listitem>
77
+
<para>
78
+
The target namespace of the SOAP service.
79
+
</para>
80
+
<para>
81
+
Required if the <parameter>wsdl</parameter> parameter is not provided;
82
+
ignored otherwise.
83
+
</para>
84
+
</listitem>
85
+
</varlistentry>
86
+
<varlistentry xml:id="soapclient.construct.options.style">
87
+
<term>
88
+
<parameter>style</parameter>
89
+
<type>int</type>
90
+
</term>
91
+
<listitem>
92
+
<para>
93
+
Specifies the binding style to use for this client, using the constants
94
+
<constant>SOAP_RPC</constant> and <constant>SOAP_DOCUMENT</constant>.
95
+
<constant>SOAP_RPC</constant> indicates RPC-style binding, where the
96
+
SOAP request body contains a standard encoding of a function call.
97
+
<constant>SOAP_DOCUMENT</constant> indicates document-style binding,
98
+
where the SOAP request body contains an XML document with
99
+
service-defined meaning.
100
+
</para>
101
+
<para>
102
+
If the <parameter>wsdl</parameter> parameter is provided, this
103
+
option is ignored, and the style is read from the WSDL file.
104
+
</para>
105
+
<para>
106
+
If neither this option nor the <parameter>wsdl</parameter> parameter
107
+
is provided, RPC-style is used.
108
+
</para>
109
+
</listitem>
110
+
</varlistentry>
111
+
<varlistentry xml:id="soapclient.construct.options.use">
112
+
<term>
113
+
<parameter>use</parameter>
114
+
<type>int</type>
115
+
</term>
116
+
<listitem>
117
+
<para>
118
+
Specifies the encoding style to use for this client, using the
119
+
constants <constant>SOAP_ENCODED</constant> or <constant>SOAP_LITERAL</constant>.
120
+
<constant>SOAP_ENCODED</constant> indicates encoding using the types
121
+
defined in the SOAP specification.
122
+
<constant>SOAP_LITERAL</constant> indicates encoding using a schema
123
+
defined by the service.
124
+
</para>
125
+
<para>
126
+
If the <parameter>wsdl</parameter> parameter is provided, this
127
+
option is ignored, and the encoding is read from the WSDL file.
128
+
</para>
129
+
<para>
130
+
If neither this option nor the <parameter>wsdl</parameter> parameter
131
+
is provided, the "encoded" style is used.
132
+
</para>
133
+
</listitem>
134
+
</varlistentry>
135
+
<varlistentry xml:id="soapclient.construct.options.soap-version">
136
+
<term>
137
+
<parameter>soap_version</parameter>
138
+
<type>int</type>
139
+
</term>
140
+
<listitem>
141
+
<para>
142
+
Specifies the version of the SOAP protocol to use:
143
+
<constant>SOAP_1_1</constant> for SOAP 1.1,
144
+
or <constant>SOAP_1_2</constant> for SOAP 1.2.
145
+
</para>
146
+
<para>
147
+
If omitted, SOAP 1.1 is used.
148
+
</para>
149
+
</listitem>
150
+
</varlistentry>
151
+
<varlistentry xml:id="soapclient.construct.options.authentication">
152
+
<term>
153
+
<parameter>authentication</parameter>
154
+
<type>int</type>
155
+
</term>
156
+
<listitem>
157
+
<para>
158
+
Specifies the authentication method when using HTTP authentication
159
+
in requests. The value may be either
160
+
<constant>SOAP_AUTHENTICATION_BASIC</constant>
161
+
or <constant>SOAP_AUTHENTICATION_DIGEST</constant>.
162
+
</para>
163
+
<para>
164
+
If omitted, and the <literal>login</literal> option is provided,
165
+
Basic Authentication is used.
166
+
</para>
167
+
</listitem>
168
+
</varlistentry>
169
+
<varlistentry xml:id="soapclient.construct.options.login">
170
+
<term>
171
+
<parameter>login</parameter>
172
+
<type>string</type>
173
+
</term>
174
+
<listitem>
175
+
<para>
176
+
Username to use with HTTP Basic or Digest Authentication.
177
+
</para>
178
+
</listitem>
179
+
</varlistentry>
180
+
<varlistentry xml:id="soapclient.construct.options.password">
181
+
<term>
182
+
<parameter>password</parameter>
183
+
<type>string</type>
184
+
</term>
185
+
<listitem>
186
+
<para>
187
+
Password to use with HTTP Basic or Digest Authentication.
188
+
</para>
189
+
<para>
190
+
Not to be confused with <literal>passphrase</literal>,
191
+
which is used with HTTPS Client Certificate authentication.
192
+
</para>
193
+
</listitem>
194
+
</varlistentry>
195
+
<varlistentry xml:id="soapclient.construct.options.local-cert">
196
+
<term>
197
+
<parameter>local_cert</parameter>
198
+
<type>string</type>
199
+
</term>
200
+
<listitem>
201
+
<para>
202
+
Path to a client certificate for use with HTTPS authentication.
203
+
It must be a <acronym>PEM</acronym> encoded file which contains your certificate
204
+
and private key.
205
+
</para>
206
+
<para>
207
+
The file can also include a chain of issuers, which must come
208
+
after the client certificate.
209
+
</para>
210
+
<para>
211
+
Can also be set via
212
+
<link linkend="soapclient.construct.options.stream-context">
213
+
<parameter>stream_context</parameter></link>,
214
+
which also supports specifying a separate private key file.
215
+
</para>
216
+
</listitem>
217
+
</varlistentry>
218
+
<varlistentry xml:id="soapclient.construct.options.passphrase">
219
+
<term>
220
+
<parameter>passphrase</parameter>
221
+
<type>string</type>
222
+
</term>
223
+
<listitem>
224
+
<para>
225
+
Passphrase for the client certificate specified in the
226
+
<literal>local_cert</literal> option.
227
+
</para>
228
+
<para>
229
+
Not to be confused with <literal>password</literal>,
230
+
which is used for Basic or Digest Authentication.
231
+
</para>
232
+
<para>
233
+
Can also be set via
234
+
<link linkend="soapclient.construct.options.stream-context">
235
+
<parameter>stream_context</parameter></link>.
236
+
</para>
237
+
</listitem>
238
+
</varlistentry>
239
+
<varlistentry xml:id="soapclient.construct.options.proxy-host">
240
+
<term>
241
+
<parameter>proxy_host</parameter>
242
+
<type>string</type>
243
+
</term>
244
+
<listitem>
245
+
<para>
246
+
Hostname to use as a proxy server for HTTP requests.
247
+
</para>
248
+
<para>
249
+
The <literal>proxy_port</literal> option must also be specified.
250
+
</para>
251
+
</listitem>
252
+
</varlistentry>
253
+
<varlistentry xml:id="soapclient.construct.options.proxy-port">
254
+
<term>
255
+
<parameter>proxy_port</parameter>
256
+
<type>int</type>
257
+
</term>
258
+
<listitem>
259
+
<para>
260
+
TCP port to use when connecting to the proxy server
261
+
specified in <literal>proxy_host</literal>.
262
+
</para>
263
+
</listitem>
264
+
</varlistentry>
265
+
<varlistentry xml:id="soapclient.construct.options.proxy-login">
266
+
<term>
267
+
<parameter>proxy_login</parameter>
268
+
<type>string</type>
269
+
</term>
270
+
<listitem>
271
+
<para>
272
+
Optional username to authenticate with the proxy server
273
+
specified in <literal>proxy_host</literal>, using HTTP
274
+
Basic Authentication.
275
+
</para>
276
+
</listitem>
277
+
</varlistentry>
278
+
<varlistentry xml:id="soapclient.construct.options.proxy-password">
279
+
<term>
280
+
<parameter>proxy_password</parameter>
281
+
<type>string</type>
282
+
</term>
283
+
<listitem>
284
+
<para>
285
+
Optional password to authenticate with the proxy server
286
+
specified in <literal>proxy_host</literal>, using HTTP
287
+
Basic Authentication.
288
+
</para>
289
+
</listitem>
290
+
</varlistentry>
291
+
<varlistentry xml:id="soapclient.construct.options.compression">
292
+
<term>
293
+
<parameter>compression</parameter>
294
+
<type>int</type>
295
+
</term>
296
+
<listitem>
297
+
<para>
298
+
Enables compression of HTTP SOAP requests and responses.
299
+
</para>
300
+
<para>
301
+
The value should be the bitwise OR of three parts:
302
+
an optional <constant>SOAP_COMPRESSION_ACCEPT</constant>,
303
+
to send an "Accept-Encoding" header; either
304
+
<constant>SOAP_COMPRESSION_GZIP</constant>
305
+
or <constant>SOAP_COMPRESSION_DEFLATE</constant> to indicate
306
+
the compression algorithm to use; and a number between 1 and 9
307
+
to indicate the level of compression to use in the request.
308
+
For example, to enable two-way gzip compression with the maximum
309
+
compression level, use
310
+
<literal>SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9</literal>.
311
+
</para>
312
+
</listitem>
313
+
</varlistentry>
314
+
<varlistentry xml:id="soapclient.construct.options.encoding">
315
+
<term>
316
+
<parameter>encoding</parameter>
317
+
<type>string</type>
318
+
</term>
319
+
<listitem>
320
+
<para>
321
+
Defines the internal character encoding. Requests are always sent
322
+
in UTF-8, and converted to and from this encoding.
323
+
</para>
324
+
</listitem>
325
+
</varlistentry>
326
+
<varlistentry xml:id="soapclient.construct.options.trace">
327
+
<term>
328
+
<parameter>trace</parameter>
329
+
<type>bool</type>
330
+
</term>
331
+
<listitem>
332
+
<para>
333
+
Captures request and response information, which can then be
334
+
accessed with the methods
335
+
<methodname>SoapClient::__getLastRequest</methodname>,
336
+
<methodname>SoapClient::__getLastRequestHeaders</methodname>,
337
+
<methodname>SoapClient::__getLastResponse</methodname>,
338
+
and <methodname>SoapClient::__getLastResponseHeaders</methodname>.
339
+
</para>
340
+
<para>
341
+
If omitted, defaults to &false;
342
+
</para>
343
+
</listitem>
344
+
</varlistentry>
345
+
<varlistentry xml:id="soapclient.construct.options.classmap">
346
+
<term>
347
+
<parameter>classmap</parameter>
348
+
<type>array</type>
349
+
</term>
350
+
<listitem>
351
+
<para>
352
+
Used to map types defined in the WSDL to PHP classes.
353
+
It should be specified as an associative <type>array</type> with
354
+
type names from the WSDL as keys and names of PHP classes as values.
355
+
Note that the type names of an element is not necessarily the same as
356
+
the element (tag) name.
357
+
</para>
358
+
<para>
359
+
The provided class names should always be fully qualified with any
360
+
<link linkend="language.namespaces">namespaces</link>, and never
361
+
start with a leading <literal>\</literal>. The correct form can be
362
+
generated by using
363
+
<link linkend="language.oop5.basic.class.class">::class</link>.
364
+
</para>
365
+
<para>
366
+
Note that when creating a class, the constructor will not be called,
367
+
but magic <link linkend="object.set">__set()</link> and
368
+
<link linkend="object.get">__get()</link> methods for individual
369
+
properties will be.
370
+
</para>
371
+
</listitem>
372
+
</varlistentry>
373
+
<varlistentry xml:id="soapclient.construct.options.typemap">
374
+
<term>
375
+
<parameter>typemap</parameter>
376
+
<type>array</type>
377
+
</term>
378
+
<listitem>
379
+
<para>
380
+
Used to define type mappings using user-defined callback functions.
381
+
Each type mapping should be an array with keys
382
+
<literal>type_name</literal> (<type>string</type> specifying the
383
+
XML element type);
384
+
<literal>type_ns</literal> (<type>string</type> containing namespace
385
+
URI);
386
+
<literal>from_xml</literal> (<type>callable</type> accepting one
387
+
string parameter and returning an object) and
388
+
<literal>to_xml</literal> (<type>callable</type> accepting one
389
+
object parameter and returning a string).
390
+
</para>
391
+
</listitem>
392
+
</varlistentry>
393
+
<varlistentry xml:id="soapclient.construct.options.exceptions">
394
+
<term>
395
+
<parameter>exceptions</parameter>
396
+
<type>bool</type>
397
+
</term>
398
+
<listitem>
399
+
<para>
400
+
Defines whether errors throw exceptions of type
401
+
<classname>SoapFault</classname>.
402
+
</para>
403
+
<para>
404
+
Defaults to &true;
405
+
</para>
406
+
</listitem>
407
+
</varlistentry>
408
+
<varlistentry xml:id="soapclient.construct.options.connection-timeout">
409
+
<term>
410
+
<parameter>connection_timeout</parameter>
411
+
<type>int</type>
412
+
</term>
413
+
<listitem>
414
+
<para>
415
+
Defines a timeout in seconds for the connection to the SOAP service.
416
+
This option does not define a timeout for services with slow responses.
417
+
To limit the time to wait for calls to finish the
418
+
<link linkend="ini.default-socket-timeout">default_socket_timeout</link>
419
+
configuration option is available.
420
+
</para>
421
+
</listitem>
422
+
</varlistentry>
423
+
<varlistentry xml:id="soapclient.construct.options.cache-wsdl">
424
+
<term>
425
+
<parameter>cache_wsdl</parameter>
426
+
<type>int</type>
427
+
</term>
428
+
<listitem>
429
+
<para>
430
+
If the <parameter>wsdl</parameter> parameter is provided, and the
431
+
<link linkend="ini.soap.wsdl-cache-enabled">soap.wsdl_cache_enabled</link>
432
+
configuration option is on, this option determines the type of caching.
433
+
One of <constant>WSDL_CACHE_NONE</constant>,
434
+
<constant>WSDL_CACHE_DISK</constant>,
435
+
<constant>WSDL_CACHE_MEMORY</constant> or
436
+
<constant>WSDL_CACHE_BOTH</constant>.
437
+
</para>
438
+
<para>
439
+
Two types of cache are available: in-memory caching, which caches the WSDL
440
+
in the memory of the current process; and disk caching, which caches the
441
+
WSDL in a file on disk, shared between all processes.
442
+
The directory to use for the disk cache is determined by the
443
+
<link linkend="ini.soap.wsdl-cache-dir">soap.wsdl_cache_dir</link>
444
+
configuration option.
445
+
Both caches use the same lifetime, determined by the
446
+
<link linkend="ini.soap.wsdl-cache-ttl">soap.wsdl_cache_ttl</link>
447
+
configuration option. The in-memory cache also has a maximum number of entries
448
+
determined by the
449
+
<link linkend="ini.soap.wsdl-cache-limit">soap.wsdl_cache_limit</link>
450
+
configuration option.
451
+
</para>
452
+
<para>
453
+
If not specified, the <link linkend="ini.soap.wsdl-cache">
454
+
soap.wsdl_cache</link> configuration option will be used.
455
+
</para>
456
+
</listitem>
457
+
</varlistentry>
458
+
<varlistentry xml:id="soapclient.construct.options.user-agent">
459
+
<term>
460
+
<parameter>user_agent</parameter>
461
+
<type>string</type>
462
+
</term>
463
+
<listitem>
464
+
<para>
465
+
The value to use in the <literal>User-Agent</literal> HTTP header
466
+
when making requests.
467
+
</para>
468
+
<para>
469
+
Can also be set via <link linkend="soapclient.construct.options.stream-context">
470
+
<parameter>stream_context</parameter></link>.
471
+
</para>
472
+
<para>
473
+
If not specified, the user agent will be <literal>"PHP-SOAP/"</literal>
474
+
followed by the value of <constant>PHP_VERSION</constant>.
475
+
</para>
476
+
</listitem>
477
+
</varlistentry>
478
+
<varlistentry xml:id="soapclient.construct.options.stream-context">
479
+
<term>
480
+
<parameter>stream_context</parameter>
481
+
<type>resource</type>
482
+
</term>
483
+
<listitem>
484
+
<para>
485
+
A <link linkend="context">stream context</link> created by
486
+
<function>stream_context_create</function>, which allows additional
487
+
options to be set.
488
+
</para>
489
+
<para>
490
+
The context may include <link linkend="context.socket">socket context options</link>,
491
+
<link linkend="context.ssl">SSL context options</link>,
492
+
plus selected <link linkend="context.http">HTTP context options</link>:
493
+
<literal>content_type</literal>, <literal>header</literal>,
494
+
<literal>max_redirects</literal>, <literal>protocol_version</literal>,
495
+
and <literal>user_agent</literal>.
496
+
</para>
497
+
<para>
498
+
Note that the following HTTP headers are generated automatically or from other
499
+
options, and will be ignored if specified in the <literal>'header'</literal>
500
+
context option: <literal>host</literal>, <literal>connection</literal>,
501
+
<literal>user-agent</literal>, <literal>content-length</literal>,
502
+
<literal>content-type</literal>, <literal>cookie</literal>,
503
+
<literal>authorization</literal>, and <literal>proxy-authorization</literal>
504
+
</para>
505
+
</listitem>
506
+
</varlistentry>
507
+
<varlistentry xml:id="soapclient.construct.options.features">
508
+
<term>
509
+
<parameter>features</parameter>
510
+
<type>int</type>
511
+
</term>
512
+
<listitem>
513
+
<para>
514
+
A bitmask to enable one or more of the following features:
515
+
<variablelist>
516
+
<varlistentry>
517
+
<term>
518
+
<constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant>
519
+
</term>
520
+
<listitem>
521
+
<para>
522
+
When decoding a response to an array, the default behaviour is to detect whether
523
+
an element name appears once or multiple times in a particular parent element.
524
+
For elements which appear only once, an object property allows direct access to
525
+
the content; for elements which appear more than once, the property contains an
526
+
array with the content of each matching element.
527
+
</para>
528
+
<para>
529
+
If the <constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant> feature is enabled,
530
+
elements which appear only once are placed in a single-element array, so that
531
+
access is consistent for all elements. This only has an effect when using a WSDL
532
+
containing a schema for the response. See Examples section for an illustration.
533
+
</para>
534
+
</listitem>
535
+
</varlistentry>
536
+
<varlistentry>
537
+
<term>
538
+
<constant>SOAP_USE_XSI_ARRAY_TYPE</constant>
539
+
</term>
540
+
<listitem>
541
+
<para>
542
+
When the <link linkend="soapclient.construct.options.use"><literal>use</literal>
543
+
option</link> or WSDL property is set to <literal>encoded</literal>,
544
+
force arrays to use a type of <literal>SOAP-ENC:Array</literal>, rather than a
545
+
schema-specific type.
546
+
</para>
547
+
</listitem>
548
+
</varlistentry>
549
+
<varlistentry>
550
+
<term>
551
+
<constant>SOAP_WAIT_ONE_WAY_CALLS</constant>
552
+
</term>
553
+
<listitem>
554
+
<para>
555
+
Wait for a response even if the WSDL indicates a one-way request.
556
+
</para>
557
+
</listitem>
558
+
</varlistentry>
559
+
</variablelist>
560
+
</para>
561
+
</listitem>
562
+
</varlistentry>
563
+
<varlistentry xml:id="soapclient.construct.options.keep-alive">
564
+
<term>
565
+
<parameter>keep_alive</parameter>
566
+
<type>bool</type>
567
+
</term>
568
+
<listitem>
569
+
<para>
570
+
a boolean value defining whether
571
+
to send the <literal>Connection: Keep-Alive</literal> header or
572
+
<literal>Connection: close</literal>.
573
+
</para>
574
+
<para>
575
+
Defaults to &true;
576
+
</para>
577
+
</listitem>
578
+
</varlistentry>
579
+
<varlistentry xml:id="soapclient.construct.options.ssl-method">
580
+
<term>
581
+
<parameter>ssl_method</parameter>
582
+
<type>string</type>
583
+
</term>
584
+
<listitem>
585
+
<para>
586
+
Specifies the SSL or TLS protocol version to use with secure HTTP
587
+
connections, instead of the default negotiation.
588
+
Specifying <constant>SOAP_SSL_METHOD_SSLv2</constant>
589
+
or <constant>SOAP_SSL_METHOD_SSLv3</constant> will force use of SSL 2
590
+
or SSL 3, respectively.
591
+
Specifying <constant>SOAP_SSL_METHOD_SSLv23</constant> has no effect;
592
+
the constant exists only for backwards compatibility.
593
+
As of PHP 7.2, specifying <constant>SOAP_SSL_METHOD_TLS</constant>
594
+
also has no effect; in earlier versions, it forced use of TLS 1.0.
595
+
</para>
596
+
<para>
597
+
Note that SSL versions 2 and 3 are considered insecure, and may not
598
+
be supported by the installed OpenSSL library.
599
+
</para>
600
+
<para>
601
+
This option is <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
602
+
A more flexible alternative, which allows specifying
603
+
individual versions of TLS, is to use the
604
+
<link linkend="soapclient.construct.options.stream-context">
605
+
<parameter>stream_context</parameter></link> option with
606
+
the 'crypto_method' context parameter.
607
+
<example>
608
+
<title>Specifying use of TLS 1.3 only</title>
609
+
<programlisting role="php">
610
+
<![CDATA[
611
+
<?php
612
+
$context = stream_context_create([
613
+
'ssl' => [
614
+
'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
615
+
]
616
+
]);
617
+
$client = new SoapClient("some.wsdl", ['context' => $context]);
618
+
]]>
619
+
</programlisting>
620
+
</example>
621
+
</para>
622
+
</listitem>
623
+
</varlistentry>
624
+
</variablelist>
157
625
</para>
158
626
</listitem>
159
627
</varlistentry>
...
...
@@ -178,7 +646,9 @@
178
646
&reftitle.examples;
179
647
<para>
180
648
<example>
181
-
<title><function>SoapClient::__construct</function> example</title>
649
+
<title>
650
+
<methodname>SoapClient::__construct</methodname> example
651
+
</title>
182
652
<programlisting role="php">
183
653
<![CDATA[
184
654
<?php
...
...
@@ -209,7 +679,7 @@ $client = new SoapClient(null, array('location' => "http://localhost/soap.php",
209
679
'use' => SOAP_LITERAL));
210
680

211
681
$client = new SoapClient("some.wsdl",
212
-
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP));
682
+
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9));
213
683

214
684
$client = new SoapClient("some.wsdl", array('encoding'=>'ISO-8859-1'));
215
685

...
...
@@ -220,15 +690,89 @@ class MyBook {
220
690

221
691
$client = new SoapClient("books.wsdl", array('classmap' => array('book' => "MyBook")));
222
692

693
+
$typemap = array(
694
+
array("type_ns" => "http://schemas.example.com",
695
+
"type_name" => "book",
696
+
"from_xml" => "unserialize_book",
697
+
"to_xml" => "serialize_book")
698
+
);
699
+
$client = new SoapClient("books.wsdl", array('typemap' => $typemap));
700
+

223
701
?>
224
702
]]>
225
703
</programlisting>
226
704
</example>
227
705
</para>
706
+

707
+
<para>
708
+
<example>
709
+
<title>Using the <constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant> feature</title>
710
+
<programlisting role="php">
711
+
<![CDATA[
712
+
/* Assuming a response like this, and an appropriate WSDL:
713
+
<?xml version="1.0" encoding="UTF-8"?>
714
+
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:example">
715
+
<SOAP-ENV:Body>
716
+
<response>
717
+
<collection>
718
+
<item>Single</item>
719
+
</collection>
720
+
<collection>
721
+
<item>First</item>
722
+
<item>Second</item>
723
+
</collection>
724
+
</response>
725
+
</SOAP-ENV:Body>
726
+
</SOAP-ENV:Envelope>
727
+
*/
728
+

729
+
echo "Default:\n";
730
+

731
+
$client = new TestSoapClient(__DIR__ . '/temp.wsdl');
732
+
$response = $client->exampleRequest();
733
+
var_dump( $response->collection[0]->item );
734
+
var_dump( $response->collection[1]->item );
735
+

736
+
echo "\nWith SOAP_SINGLE_ELEMENT_ARRAYS:\n";
737
+

738
+
$client = new TestSoapClient(__DIR__ . '/temp.wsdl', ['features' => SOAP_SINGLE_ELEMENT_ARRAYS]);
739
+
$response = $client->exampleRequest();
740
+
var_dump( $response->collection[0]->item );
741
+
var_dump( $response->collection[1]->item );
742
+
]]>
743
+
</programlisting>
744
+

745
+
&example.outputs;
746
+

747
+
<screen>
748
+
<![CDATA[
749
+
Default:
750
+
string(6) "Single"
751
+
array(2) {
752
+
[0] =>
753
+
string(5) "First"
754
+
[1] =>
755
+
string(6) "Second"
756
+
}
757
+

758
+
With SOAP_SINGLE_ELEMENT_ARRAYS:
759
+
array(1) {
760
+
[0] =>
761
+
string(6) "Single"
762
+
}
763
+
array(2) {
764
+
[0] =>
765
+
string(5) "First"
766
+
[1] =>
767
+
string(6) "Second"
768
+
}
769
+
]]>
770
+
</screen>
771
+
</example>
772
+
</para>
228
773
</refsect1>
229
774

230
775
</refentry>
231
-

232
776
<!-- Keep this comment at the end of the file
233
777
Local variables:
234
778
mode: sgml
235
779