SoapClient::__construct

(PHP 5、PHP 7、PHP 8)

SoapClient::__construct — SoapClient 构造函数

描述

public SoapClient::__construct(?string $wsdl, array $options = [])

创建一个 SoapClient 对象以连接到 SOAP 服务。

参数

wsdl

描述服务的 WSDL 文件的 URI，用于自动配置客户端。如果没有提供，客户端将以非 WSDL 模式运行。

注意:
默认情况下，WSDL 文件将被缓存以提高性能。要禁用或配置此缓存，请参阅 SOAP 配置选项和 cache_wsdl 选项。

options

一个关联数组，指定 SOAP 客户端的附加选项。如果提供了 wsdl，则它是可选的；否则，至少必须提供 location 和 url。

location string

要发送请求的 SOAP 服务器的 URL。

如果未提供 wsdl 参数，则为必填。如果同时提供了 wsdl 参数和 location 选项，则 location 选项将覆盖 WSDL 文件中指定的任何位置。

uri string

SOAP 服务的目标命名空间。

如果未提供 wsdl 参数，则为必填；否则忽略。

style int

使用常量 SOAP_RPC 和 SOAP_DOCUMENT 指定此客户端要使用的绑定样式。SOAP_RPC 表示 RPC 样式绑定，其中 SOAP 请求主体包含对函数调用的标准编码。SOAP_DOCUMENT 表示文档样式绑定，其中 SOAP 请求主体包含一个具有服务定义含义的 XML 文档。

如果提供了 wsdl 参数，则忽略此选项，样式将从 WSDL 文件中读取。

如果既没有提供此选项，也没有提供 wsdl 参数，则使用 RPC 样式。

use int

使用常量 SOAP_ENCODED 或 SOAP_LITERAL 指定此客户端要使用的编码样式。SOAP_ENCODED 表示使用 SOAP 规范中定义的类型进行编码。SOAP_LITERAL 表示使用服务定义的模式进行编码。

如果提供了 wsdl 参数，则忽略此选项，编码将从 WSDL 文件中读取。

如果既没有提供此选项，也没有提供 wsdl 参数，则使用“编码”样式。

soap_version int

指定要使用的 SOAP 协议版本：SOAP_1_1 用于 SOAP 1.1，或 SOAP_1_2 用于 SOAP 1.2。

如果省略，则使用 SOAP 1.1。

authentication int

指定在请求中使用 HTTP 身份验证时的身份验证方法。该值可以是 SOAP_AUTHENTICATION_BASIC 或 SOAP_AUTHENTICATION_DIGEST。

如果省略，并且提供了 login 选项，则使用基本身份验证。

login string

与 HTTP 基本或摘要身份验证一起使用的用户名。

password string

与 HTTP 基本或摘要身份验证一起使用的密码。

不要与 passphrase 混淆，后者用于 HTTPS 客户端证书身份验证。

local_cert string

与 HTTPS 身份验证一起使用的客户端证书的路径。它必须是一个 PEM 编码文件，其中包含您的证书和私钥。

该文件还可以包含发行者链，它们必须位于客户端证书之后。

也可以通过 stream_context 设置，它还支持指定单独的私钥文件。

passphrase string

在 local_cert 选项中指定的客户端证书的密码。

不要与 password 混淆，后者用于基本或摘要身份验证。

也可以通过 stream_context 设置。

proxy_host string

用作 HTTP 请求代理服务器的主机名。

还必须指定 proxy_port 选项。

proxy_port int

连接到 proxy_host 中指定的代理服务器时要使用的 TCP 端口。

proxy_login string

使用 HTTP 基本身份验证，可选地对 proxy_host 中指定的代理服务器进行身份验证的用户名。

proxy_password string

使用 HTTP 基本身份验证，可选地对 proxy_host 中指定的代理服务器进行身份验证的密码。

compression int

启用 HTTP SOAP 请求和响应的压缩。

该值应是三个部分的按位或：可选的 SOAP_COMPRESSION_ACCEPT，用于发送“Accept-Encoding”标头；要么是 SOAP_COMPRESSION_GZIP，要么是 SOAP_COMPRESSION_DEFLATE，表示要使用的压缩算法；以及 1 到 9 之间的数字，表示在请求中要使用的压缩级别。例如，要启用使用最大压缩级别的双向 gzip 压缩，请使用 SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9。

encoding string

定义内部字符编码。请求始终以 UTF-8 发送，并在此编码之间进行转换。

trace bool

捕获请求和响应信息，然后可以使用方法 SoapClient::__getLastRequest()、SoapClient::__getLastRequestHeaders()、SoapClient::__getLastResponse() 和 SoapClient::__getLastResponseHeaders() 访问。

如果省略，默认为 false

classmap array

用于将 WSDL 中定义的类型映射到 PHP 类。它应指定为一个关联 array，其中 WSDL 中的类型名称作为键，PHP 类名作为值。请注意，元素的类型名称不一定与元素（标签）名称相同。

提供的类名应始终使用任何命名空间完整限定，并且绝不以引导 \ 开头。正确形式可以通过使用 ::class 生成。

请注意，在创建类时，不会调用构造函数，但会调用各个属性的魔术 __set() 和 __get() 方法。

typemap array

用于使用用户定义的回调函数定义类型映射。每个类型映射都应该是一个数组，包含以下键：type_name (string 指定 XML 元素类型)；type_ns (string 包含命名空间 URI)；from_xml (callable 接受一个字符串参数并返回一个对象) 和 to_xml (callable 接受一个对象参数并返回一个字符串)。

exceptions bool

定义是否将类型为 SoapFault 的错误抛出为异常。

默认为 true

connection_timeout int

定义连接到 SOAP 服务的超时时间（以秒为单位）。此选项不会定义对响应速度慢的服务的超时时间。若要限制等待调用完成的时间，可以使用 default_socket_timeout 配置选项。

cache_wsdl int

如果提供了 wsdl 参数，并且 soap.wsdl_cache_enabled 配置选项已启用，则此选项确定缓存类型。可以是以下值之一：WSDL_CACHE_NONE、WSDL_CACHE_DISK、WSDL_CACHE_MEMORY 或 WSDL_CACHE_BOTH。

有两种类型的缓存可用：内存缓存，它将 WSDL 缓存到当前进程的内存中；磁盘缓存，它将 WSDL 缓存到磁盘上的文件中，由所有进程共享。磁盘缓存使用的目录由 soap.wsdl_cache_dir 配置选项确定。两种缓存都使用相同的生命周期，由 soap.wsdl_cache_ttl 配置选项确定。内存缓存也有一个由 soap.wsdl_cache_limit 配置选项确定的最大条目数。

如果未指定，将使用 soap.wsdl_cache 配置选项。

user_agent string

在发出请求时，在 User-Agent HTTP 标头中使用的值。

也可以通过 stream_context 设置。

如果未指定，用户代理将是 "PHP-SOAP/" 后跟 PHP_VERSION 的值。

stream_context resource

由 stream_context_create() 创建的流上下文，它允许设置其他选项。

该上下文可能包含套接字上下文选项、SSL 上下文选项，以及选定的 HTTP 上下文选项：content_type、header、max_redirects、protocol_version 和 user_agent。

请注意，以下 HTTP 标头是自动生成的或由其他选项生成，如果在 'header' 上下文选项中指定，将被忽略：host、connection、user-agent、content-length、content-type、cookie、authorization 和 proxy-authorization

features int

一个位掩码，用于启用以下一项或多项功能

SOAP_SINGLE_ELEMENT_ARRAYS

解码对数组的响应时，默认行为是检测某个父元素中的元素名称在其中出现一次还是多次。对于只出现一次的元素，对象属性允许直接访问其内容；对于出现多次的元素，该属性包含一个数组，其中包含每个匹配元素的内容。

如果启用了 SOAP_SINGLE_ELEMENT_ARRAYS 功能，则只出现一次的元素将被放置在一个单元素数组中，以便对所有元素的访问一致。这仅在使用包含响应模式的 WSDL 时有效。有关说明，请参见示例部分。

SOAP_USE_XSI_ARRAY_TYPE

当 use 选项或 WSDL 属性设置为 encoded 时，强制数组使用 SOAP-ENC:Array 类型的，而不是模式特定的类型。

SOAP_WAIT_ONE_WAY_CALLS

即使 WSDL 指示这是一个单向请求，也要等待响应。

keep_alive bool

一个布尔值，用于定义是否发送 Connection: Keep-Alive 标头或 Connection: close。

默认为 true

ssl_method string

指定要与安全 HTTP 连接一起使用的 SSL 或 TLS 协议版本，而不是默认协商。指定 SOAP_SSL_METHOD_SSLv2 或 SOAP_SSL_METHOD_SSLv3 将分别强制使用 SSL 2 或 SSL 3。指定 SOAP_SSL_METHOD_SSLv23 无效；该常量仅出于向后兼容性而存在。从 PHP 7.2 开始，指定 SOAP_SSL_METHOD_TLS 也不起作用；在早期版本中，它强制使用 TLS 1.0。

请注意，SSL 版本 2 和 3 被认为是不安全的，并且可能不受已安装的 OpenSSL 库的支持。

从 PHP 8.1.0 开始，此选项已 **弃用**。一个更灵活的替代方案是使用 stream_context 选项以及 'crypto_method' 上下文参数，从而允许指定 TLS 的各个版本。

示例 #1 指定仅使用 TLS 1.3

<?php
$context = stream_context_create([
 'ssl' => [
 'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
 ]
]);
$client = new SoapClient("some.wsdl", ['context' => $context]);

错误/异常

如果在非 WSDL 模式下未提供 location 和 uri 选项，则 SoapClient::__construct() 将生成一个 E_ERROR 错误。

如果无法加载 wsdl URI，则将抛出 SoapFault 异常。

示例

示例 #2 SoapClient::__construct() 示例

<?php

$client = new SoapClient("some.wsdl");

$client = new SoapClient("some.wsdl", array('soap_version' => SOAP_1_2));

$client = new SoapClient("some.wsdl", array('login' => "some_name",
 'password' => "some_password"));

$client = new SoapClient("some.wsdl", array('proxy_host' => "localhost",
 'proxy_port' => 8080));

$client = new SoapClient("some.wsdl", array('proxy_host' => "localhost",
 'proxy_port' => 8080,
 'proxy_login' => "some_name",
 'proxy_password' => "some_password"));

$client = new SoapClient("some.wsdl", array('local_cert' => "cert_key.pem"));

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
 'uri' => "http://test-uri/"));

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
 'uri' => "http://test-uri/",
 'style' => SOAP_DOCUMENT,
 'use' => SOAP_LITERAL));

$client = new SoapClient("some.wsdl",
 array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9));

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

class MyBook {
 public $title;
 public $author;
}

$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));

?>

示例 #3 使用 **SOAP_SINGLE_ELEMENT_ARRAYS** 功能

/* 假设响应类似于以下内容，并且有一个相应的 WSDL
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:example">
<SOAP-ENV:Body>
<response>
<collection>
<item>Single</item>
</collection>
<collection>
<item>First</item>
<item>Second</item>
</collection>
</response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
*/

echo "默认:\n";

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

echo "\n使用 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 );

上面的例子将输出

Default:
string(6) "Single"
array(2) {
  [0] =>
  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"
}

改进此页面

了解如何改进此页面 • 提交拉取请求 • 报告错误

＋添加备注

用户贡献的备注 1 备注

踩

turabgarip at gmail dot com ¶

2 个月前

关于 steam_context 选项的两个备注

1- 在文档的示例中，它说

<?php
$client = new SoapClient("some.wsdl", ['context' => $context]);
?>

这是错误的。正如参数列表中所述，它必须是“stream_context”而不是“context”。

2- HTTP 上下文手册在此处：https://php.net/manual/en/context.http.php

它说标题可以是数组类型或字符串类型。这也是错误的。它不一定是可选的，因为它可能取决于 PHP 编译时配置。

如果你的实例是使用 --with-curlwrappers 选项编译的，你应该在 HTTP 上下文中使用数组类型作为标题，如果不是，你应该使用以换行符 (\n) 分隔的字符串作为标题。我不确定 SoapClient 是否尊重 curl_wrappers 选项，因为尽管它在我的实例中启用，尽管我使用数组作为标题来创建用于非 Soap 操作的 HTTP 上下文，但 SoapClient 要求我使用字符串。否则它会完全丢弃 stream_context。

因此，对于 SoapClient，你最好使用字符串作为 HTTP 标题，如下所示

<?php

$context = stream_context_create(array(
 'http' => array(
 'user_agent' => 'My App',
 'header' =>
 "Custom-Header: Value\n" .
 "Another Header: Surprise"
 )
));

$client = new SoapClient('some.wsdl', ['stream_context' => $context]);
?>