(PHP 5, PHP 7, PHP 8)
SoapClient::__construct — Конструктор класса SoapClient
Создаёт объект SoapClient для подключения к службе SOAP.
wsdl
URI WSDL-файла, описывающего сервис, который используется для автоматической настройки клиента. Если он не указан, клиент будет работать в режиме без WSDL. mode.
Замечание:
По умолчанию WSDL-файл будет кешироваться для повышения производительности. Чтобы отключить или настроить кеширование, смотрите раздел Опции настройки SOAP и параметр
cache_wsdl
.
options
Ассоциативный массив, определяющий дополнительные параметры для клиента SOAP. Если указан параметр wsdl
, это необязательно, в противном случае, по крайней мере параметры location
и url
должны быть указаны.
location
stringURL-адрес сервера SOAP для отправки запроса.
Обязателен, если параметр 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
не указаны, используется стиль "encoded".
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
, используется Basic Authentication.
login
stringИмя пользователя для использования при аутентификации HTTP Basic или Digest.
password
stringПароль для использования при аутентификации HTTP Basic или Digest.
Не следует путать с параметром passphrase
, который используется при аутентификации сертификата клиента HTTPS.
local_cert
stringПуть к клиентскому сертификату для использования с аутентификацией HTTPS. Должен быть файл в кодировке PEM, содержащий сертификат и закрытый ключ.
Файл также может включать цепочку эмитентов, которая должна идти после сертификата клиента.
Также может быть задан с помощью параметра stream_context
, который также поддерживает указание отдельного файла закрытого ключа.
passphrase
string Ключевая фраза для клиентского сертификата, указанного в параметре local_cert
.
Не следует путать с параметром password
, который используется для аутентификации Basic или Digest.
Можно также установить с помощью параметра stream_context
.
proxy_host
stringИмя хоста для использования в качестве прокси-сервера для HTTP-запросов.
Также должен быть указан параметр proxy_port
.
proxy_port
int TCP-порт для использования при подключении к прокси-серверу, указанному в параметре proxy_host
.
proxy_login
string Необязательное имя пользователя для аутентификации на прокси-сервере, указанном в параметре proxy_host
, используя HTTP Basic Authentication.
proxy_password
string Необязательный пароль для аутентификации на прокси-сервере, указанном в параметре proxy_host
, используя HTTP Basic Authentication.
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 Используется для определения сопоставлений типов с помощью определяемых пользователем callback-функций. Каждое сопоставление типов должно представлять собой массив с ключами 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 Значение для использования в HTTP-заголовке User-Agent
при выполнении запросов.
Можно также установить с помощью параметра stream_context
.
Если не указано, User-Agent будет "PHP-SOAP/"
за которым следует значение PHP_VERSION
.
stream_context
resourceКонтекст stream context, созданный с помощью функции 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 Определяет версию протокола SSL или TLS для использования в защищённых HTTP-соединениях вместо согласования по умолчанию. Указание 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. Более гибкой альтернативой, позволяющей указывать отдельные версии TLS, можно использовать параметр stream_context
с параметром контекста 'crypto_method'.
Пример #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]);
Метод SoapClient::__construct() выводит ошибку уровня E_ERROR
, если параметры location
и uri
не указаны в режиме не-WSDL.
Выбрасывается исключение SoapFault, если параметр wsdl
URI не может быть загружен.
Пример #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
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 );
Результат выполнения приведённого примера:
По умолчанию: string(6) "Single" array(2) { [0] => string(5) "First" [1] => string(6) "Second" } С помощью SOAP_SINGLE_ELEMENT_ARRAYS: array(1) { [0] => string(6) "Single" } array(2) { [0] => string(5) "First" [1] => string(6) "Second" }