From 8a29bad1d48902d5ee49cf33668e2aeb1d142f47 Mon Sep 17 00:00:00 2001 From: Rowan Tommins Date: Mon, 19 Apr 2021 08:42:19 +0100 Subject: [PATCH] Rewrite SoapClient constructor documentation This constructor takes a large number of options, most of which were effectively undocumented, leading to a very high volume of User Notes. Some examples and caveats from these notes have been incorporated. The descriptions here are largely based on reverse-engineering the source code (which isn't particularly well commented) and experimenting locally, so may not be 100% accurate, or capture differences between versions. --- reference/soap/constants.xml | 153 ++++- reference/soap/soapclient/construct.xml | 785 ++++++++++++++++++++---- 2 files changed, 796 insertions(+), 142 deletions(-) diff --git a/reference/soap/constants.xml b/reference/soap/constants.xml index 36060d272162..baf9f2868f90 100644 --- a/reference/soap/constants.xml +++ b/reference/soap/constants.xml @@ -21,7 +21,11 @@ (int) 1 - + + Specifies use of SOAP 1.1 when passed as soap_version + option to SoapServer::__construct or + SoapClient::__construct. + @@ -29,7 +33,11 @@ (int) 2 - + + Specifies use of SOAP 1.2 when passed as soap_version + option to SoapServer::__construct or + SoapClient::__construct. + @@ -61,7 +69,10 @@ (int) 1 - + + Specifies use of SOAP Encoding when passed as use + option to SoapClient::__construct. + @@ -69,7 +80,10 @@ (int) 2 - + + Specifies use of service-specific encoding when passed as use + option to SoapClient::__construct. + @@ -77,7 +91,10 @@ (int) 1 - + + Specifies use of RPC-style binding when passed as style + option to SoapClient::__construct. + @@ -85,7 +102,10 @@ (int) 2 - + + Specifies use of document binding when passed as style + option to SoapClient::__construct. + @@ -117,7 +137,13 @@ (int) 32 - + + Specifies use of an "Accept-Encoding" header + when passed as part of + + the compression option + to SoapClient::__construct. + @@ -125,7 +151,13 @@ (int) 0 - + + Specifies use of gzip compression + when passed as part of + + the compression option + to SoapClient::__construct. + @@ -133,7 +165,13 @@ (int) 16 - + + Specifies use of deflate compression + when passed as part of + + the compression option + to SoapClient::__construct. + @@ -141,7 +179,11 @@ (int) 0 - + + Specifies use of HTTP Basic Authentication when passed as + authentication option to + SoapClient::__construct. + @@ -149,7 +191,11 @@ (int) 1 - + + Specifies use of HTTP Digest Authentication when passed as + authentication option to + SoapClient::__construct. + @@ -157,7 +203,12 @@ (int) 0 - + + Used with the deprecated + + ssl_method option + to SoapClient::__construct. + @@ -165,7 +216,12 @@ (int) 1 - + + Used with the deprecated + + ssl_method option + to SoapClient::__construct. + @@ -173,7 +229,12 @@ (int) 2 - + + Used with the deprecated + + ssl_method option + to SoapClient::__construct. + @@ -181,7 +242,12 @@ (int) 3 - + + Used with the deprecated + + ssl_method option + to SoapClient::__construct. + @@ -613,7 +679,12 @@ (int) 1 - + + Used with the + + features option + to SoapClient::__construct. + @@ -621,7 +692,12 @@ (int) 2 - + + Used with the + + features option + to SoapClient::__construct. + @@ -629,7 +705,12 @@ (int) 4 - + + Used with the + + features option + to SoapClient::__construct. + @@ -637,7 +718,14 @@ (int) 0 - + + Disables the WSDL cache when used in the + soap.wsdl_cache + configuration option or the + wsdl_cache option + to SoapClient::__construct + and SoapServer::__construct. + @@ -645,7 +733,14 @@ (int) 1 - + + Specifies use of the on-disk WSDL cache only when used in the + soap.wsdl_cache + configuration option or the + wsdl_cache option + to SoapClient::__construct + and SoapServer::__construct. + @@ -653,7 +748,14 @@ (int) 2 - + + Specifies use of the in-memory WSDL cache only when used in the + soap.wsdl_cache + configuration option or the + wsdl_cache option + to SoapClient::__construct + and SoapServer::__construct. + @@ -661,7 +763,14 @@ (int) 3 - + + Specifies use of both on-disk and in-memory WSDL caches when used in the + soap.wsdl_cache + configuration option or the + wsdl_cache option + to SoapClient::__construct + and SoapServer::__construct. + diff --git a/reference/soap/soapclient/construct.xml b/reference/soap/soapclient/construct.xml index 4b56a8148d63..80e5d46997e0 100644 --- a/reference/soap/soapclient/construct.xml +++ b/reference/soap/soapclient/construct.xml @@ -14,8 +14,7 @@ arrayoptions[] - This constructor creates SoapClient objects - in WSDL or non-WSDL mode. + Creates a SoapClient object to connect to a SOAP service. @@ -27,15 +26,17 @@ wsdl - URI of the WSDL file or &null; if working in - non-WSDL mode. + URI of a WSDL file describing the service, which is used to automatically + configure the client. If not provided, the client will operate in non-WSDL + mode. - During development, WSDL caching may be disabled by the - use of the soap.wsdl_cache_ttl &php.ini; setting - otherwise changes made to the WSDL file will have no effect until - soap.wsdl_cache_ttl is expired. + By default, the WSDL file will be cached for performance. To disable + or configure this caching, see + SOAP &ConfigureOptions; + and the + cache_wsdl option. @@ -44,116 +45,583 @@ options - An array of options. If working in WSDL mode, this parameter is optional. - If working in non-WSDL mode, the location and - uri options must be set, where location - is the URL of the SOAP server to send the request to, and uri - is the target namespace of the SOAP service. - - - The style and use options only work in - non-WSDL mode. In WSDL mode, they come from the WSDL file. - - - The soap_version option should be one of either - SOAP_1_1 or SOAP_1_2 to - select SOAP 1.1 or 1.2, respectively. If omitted, 1.1 is used. - - - For HTTP authentication, the login and - password options can be used to supply credentials. - For making an HTTP connection through - a proxy server, the options proxy_host, - proxy_port, proxy_login - and proxy_password are also available. - For HTTPS client certificate authentication use - local_cert and passphrase options. An - authentication may be supplied in the authentication - option. The authentication method may be either - SOAP_AUTHENTICATION_BASIC (default) or - SOAP_AUTHENTICATION_DIGEST. - - - The compression option allows to use compression - of HTTP SOAP requests and responses. - - - The encoding option defines internal character - encoding. This option does not change the encoding of SOAP requests (it is - always utf-8), but converts strings into it. - - - The trace option enables tracing of request so faults - can be backtraced. This defaults to &false; - - - The classmap option can be used to map some WSDL - types to PHP classes. This option must be an array with WSDL types - as keys and names of PHP classes as values. - - - Setting the boolean trace option enables use of the - methods - SoapClient->__getLastRequest, - - SoapClient->__getLastRequestHeaders, - - SoapClient->__getLastResponse and - - SoapClient->__getLastResponseHeaders. - - - The exceptions option is a boolean value defining whether - soap errors throw exceptions of type - SoapFault. - - - The connection_timeout option defines a timeout in seconds - for the connection to the SOAP service. This option does not define a timeout - for services with slow responses. To limit the time to wait for calls to finish the - default_socket_timeout setting - is available. - - - The typemap option is an array of type mappings. - Type mapping is an array with keys type_name, - type_ns (namespace URI), from_xml - (callback accepting one string parameter) and to_xml - (callback accepting one object parameter). - - - The cache_wsdl option is one of - WSDL_CACHE_NONE, - WSDL_CACHE_DISK, - WSDL_CACHE_MEMORY or - WSDL_CACHE_BOTH. - - - The user_agent option specifies string to use in - User-Agent header. - - - The stream_context option is a resource - for context. - - - The features option is a bitmask of - SOAP_SINGLE_ELEMENT_ARRAYS, - SOAP_USE_XSI_ARRAY_TYPE, - SOAP_WAIT_ONE_WAY_CALLS. - - - The keep_alive option is a boolean value defining whether - to send the Connection: Keep-Alive header or - Connection: close. - - - The ssl_method option is one of - SOAP_SSL_METHOD_TLS, - SOAP_SSL_METHOD_SSLv2, - SOAP_SSL_METHOD_SSLv3 or - SOAP_SSL_METHOD_SSLv23. + An associative array specifying additional options for the SOAP client. + If wsdl is provided, this is optional; otherwise, + at least location and url must be + provided. + + + + location + string + + + + The URL of the SOAP server to send the request to. + + + Required if the wsdl parameter is not provided. + If both a wsdl parameter and + location option are provided, the + location option will over-ride any location + specified in the WSDL file. + + + + + + uri + string + + + + The target namespace of the SOAP service. + + + Required if the wsdl parameter is not provided; + ignored otherwise. + + + + + + style + int + + + + Specifies the binding style to use for this client, using the constants + SOAP_RPC and SOAP_DOCUMENT. + SOAP_RPC indicates RPC-style binding, where the + SOAP request body contains a standard encoding of a function call. + SOAP_DOCUMENT indicates document-style binding, + where the SOAP request body contains an XML document with + service-defined meaning. + + + If the wsdl parameter is provided, this + option is ignored, and the style is read from the WSDL file. + + + If neither this option nor the wsdl parameter + is provided, RPC-style is used. + + + + + + use + int + + + + Specifies the encoding style to use for this client, using the + constants SOAP_ENCODED or SOAP_LITERAL. + SOAP_ENCODED indicates encoding using the types + defined in the SOAP specification. + SOAP_LITERAL indicates encoding using a schema + defined by the service. + + + If the wsdl parameter is provided, this + option is ignored, and the encoding is read from the WSDL file. + + + If neither this option nor the wsdl parameter + is provided, the "encoded" style is used. + + + + + + soap_version + int + + + + Specifies the version of the SOAP protocol to use: + SOAP_1_1 for SOAP 1.1, + or SOAP_1_2 for SOAP 1.2. + + + If omitted, SOAP 1.1 is used. + + + + + + authentication + int + + + + Specifies the authentication method when using HTTP authentication + in requests. The value may be either + SOAP_AUTHENTICATION_BASIC + or SOAP_AUTHENTICATION_DIGEST. + + + If omitted, and the login option is provided, + Basic Authentication is used. + + + + + + login + string + + + + Username to use with HTTP Basic or Digest Authentication. + + + + + + password + string + + + + Password to use with HTTP Basic or Digest Authentication. + + + Not to be confused with passphrase, + which is used with HTTPS Client Certificate authentication. + + + + + + local_cert + string + + + + Path to a client certificate for use with HTTPS authentication. + It must be a PEM encoded file which contains your certificate + and private key. + + + The file can also include a chain of issuers, which must come + after the client certificate. + + + Can also be set via + + stream_context, + which also supports specifying a separate private key file. + + + + + + passphrase + string + + + + Passphrase for the client certificate specified in the + local_cert option. + + + Not to be confused with password, + which is used for Basic or Digest Authentication. + + + Can also be set via + + stream_context. + + + + + + proxy_host + string + + + + Hostname to use as a proxy server for HTTP requests. + + + The proxy_port option must also be specified. + + + + + + proxy_port + int + + + + TCP port to use when connecting to the proxy server + specified in proxy_host. + + + + + + proxy_login + string + + + + Optional username to authenticate with the proxy server + specified in proxy_host, using HTTP + Basic Authentication. + + + + + + proxy_password + string + + + + Optional password to authenticate with the proxy server + specified in proxy_host, using HTTP + Basic Authentication. + + + + + + compression + int + + + + Enables compression of HTTP SOAP requests and responses. + + + The value should be the bitwise OR of three parts: + an optional SOAP_COMPRESSION_ACCEPT, + to send an "Accept-Encoding" header; either + SOAP_COMPRESSION_GZIP + or SOAP_COMPRESSION_DEFLATE to indicate + the compression algorithm to use; and a number between 1 and 9 + to indicate the level of compression to use in the request. + For example, to enable two-way gzip compression with the maximum + compression level, use + SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9. + + + + + + encoding + string + + + + Defines the internal character encoding. Requests are always sent + in UTF-8, and converted to and from this encoding. + + + + + + trace + bool + + + + Captures request and response information, which can then be + accessed with the methods + SoapClient::getLastRequest, + SoapClient::getLastRequestHeaders, + SoapClient::getLastResponse, + and SoapClient::getLastResponseHeaders. + + + If omitted, defaults to &false; + + + + + + classmap + array + + + + Used to map types defined in the WSDL to PHP classes. + It should be specified as an associative array with + type names from the WSDL as keys and names of PHP classes as values. + Note that the type names of an element is not necessarily the same as + the element (tag) name. + + + The provided class names should always be fully qualified with any + namespaces, and never + start with a leading \. The correct form can be + generated by using + ::class. + + + Note that when creating a class, the constructor will not be called, + but magic __set() and + __get() methods for individual + properties will be. + + + + + + typemap + array + + + + Used to define type mappings using user-defined callback functions. + Each type mapping should be an array with keys + type_name (string specifying the + XML element type); + type_ns (string containing namespace + URI); + from_xml (callable accepting one + string parameter and returning an object) and + to_xml (callable accepting one + object parameter and returning a string). + + + + + + exceptions + bool + + + + Defines whether errors throw exceptions of type + SoapFault. + + + Defaults to &true; + + + + + + connection_timeout + int + + + + Defines a timeout in seconds for the connection to the SOAP service. + This option does not define a timeout for services with slow responses. + To limit the time to wait for calls to finish the + default_socket_timeout + configuration option is available. + + + + + + cache_wsdl + int + + + + If the wsdl parameter is provided, and the + soap.wsdl_cache_enabled + configuration option is on, this option determines the type of caching. + One of WSDL_CACHE_NONE, + WSDL_CACHE_DISK, + WSDL_CACHE_MEMORY or + WSDL_CACHE_BOTH. + + + Two types of cache are available: in-memory caching, which caches the WSDL + in the memory of the current process; and disk caching, which caches the + WSDL in a file on disk, shared between all processes. + The directory to use for the disk cache is determined by the + soap.wsdl_cache_dir + configuration option. + Both caches use the same lifetime, determined by the + soap.wsdl_cache_ttl + configuration option. The in-memory cache also has a maximum number of entries + determined by the + soap.wsdl_cache_limit + configuration option. + + + If not specified, the + soap.wsdl_cache configuration option will be used. + + + + + + user_agent + string + + + + The value to use in the User-Agent HTTP header + when making requests. + + + Can also be set via + stream_context. + + + If not specified, the user agent will be "PHP-SOAP/" + followed by the value of PHP_VERSION. + + + + + + stream_context + resource + + + + A stream context created by + stream_context_create, which allows additional + options to be set. + + + The context may include socket context options, + SSL context options, + plus selected HTTP context options: + content_type, header, + max_redirects, protocol_version, + and user_agent. + + + Note that the following HTTP headers are generated automatically or from other + options, and will be ignored if specified in the 'header' + context option: host, connection, + user-agent, content-length, + content-type, cookie, + authorization, and proxy-authorization + + + + + + features + int + + + + A bitmask to enable one or more of the following features: + + + + SOAP_SINGLE_ELEMENT_ARRAYS + + + + When decoding a response to an array, the default behaviour is to detect whether + an element name appears once or multiple times in a particular parent element. + For elements which appear only once, an object property allows direct access to + the content; for elements which appear more than once, the property contains an + array with the content of each matching element. + + + If the SOAP_SINGLE_ELEMENT_ARRAYS feature is enabled, + elements which appear only once are placed in a single-element array, so that + access is consistent for all elements. This only has an effect when using a WSDL + containing a schema for the response. See Examples section for an illustration. + + + + + + SOAP_USE_XSI_ARRAY_TYPE + + + + When the use + option or WSDL property is set to encoded, + force arrays to use a type of SOAP-ENC:Array, rather than a + schema-specific type. + + + + + + SOAP_WAIT_ONE_WAY_CALLS + + + + Wait for a response even if the WSDL indicates a one-way request. + + + + + + + + + + keep_alive + bool + + + + a boolean value defining whether + to send the Connection: Keep-Alive header or + Connection: close. + + + Defaults to &true; + + + + + + ssl_method + string + + + + Specifies the SSL or TLS protocol version to use with secure HTTP + connections, instead of the default negotiation. + Specifying SOAP_SSL_METHOD_SSLv2 + or SOAP_SSL_METHOD_SSLv3 will force use of SSL 2 + or SSL 3, respectively. + Specifying SOAP_SSL_METHOD_SSLv23 has no effect; + the constant exists only for backwards compatibility. + As of PHP 7.2, specifying SOAP_SSL_METHOD_TLS + also has no effect; in earlier versions, it forced use of TLS 1.0. + + + Note that SSL versions 2 and 3 are considered insecure, and may not + be supported by the installed OpenSSL library. + + + This option is DEPRECATED as of PHP 8.1.0. + A more flexible alternative, which allows specifying + individual versions of TLS, is to use the + + stream_context option with + the 'crypto_method' context parameter. + + Specifying use of TLS 1.3 only + + [ + 'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT + ] +]; +$client = new SoapClient("some.wsdl", ['context' => $context]); +]]> + + + + + + @@ -178,7 +646,9 @@ &reftitle.examples; - <function>SoapClient::__construct</function> example + + <methodname>SoapClient::__construct</methodname> example + "http://localhost/soap.php", 'use' => SOAP_LITERAL)); $client = new SoapClient("some.wsdl", - array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP)); + array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9)); $client = new SoapClient("some.wsdl", array('encoding'=>'ISO-8859-1')); @@ -220,11 +690,86 @@ class MyBook { $client = new SoapClient("books.wsdl", array('classmap' => array('book' => "MyBook"))); +$typemap = array( + array("type_ns" => "http://schemas.example.com", + "type_name" => "book", + "from_xml" => "unserialize_book" + "to_xml" => "serialize_book") +); +$client = new SoapClient("books.wsdl", array('typemap' => $typemap)); + ?> ]]> + + + + Using the <constant>SOAP_SINGLE_ELEMENT_ARRAYS</constant> feature + + + + + + + Single + + + First + Second + + + + +*/ + +echo "Default:\n"; + +$client = new TestSoapClient(__DIR__ . '/temp.wsdl'); +$response = $client->exampleRequest(); +var_dump( $response->collection[0]->item ); +var_dump( $response->collection[1]->item ); + +echo "\nWith SOAP_SINGLE_ELEMENT_ARRAYS:\n"; + +$client = new TestSoapClient(__DIR__ . '/temp.wsdl', ['features' => SOAP_SINGLE_ELEMENT_ARRAYS]); +$response = $client->exampleRequest(); +var_dump( $response->collection[0]->item ); +var_dump( $response->collection[1]->item ); +]]> + + + &example.outputs; + + + + string(5) "First" + [1] => + string(6) "Second" +} + +With SOAP_SINGLE_ELEMENT_ARRAYS: +array(1) { + [0] => + string(6) "Single" +} +array(2) { + [0] => + string(5) "First" + [1] => + string(6) "Second" +} +]]> + + +