SoapClient::__construct

(PHP 5, PHP 7, PHP 8)

SoapClient::__construct — Конструктор класса SoapClient

Описание

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

Создаёт объект SoapClient для подключения к службе SOAP.

Список параметров

wsdl

URI WSDL-файла, описывающего сервис, который используется для автоматической настройки клиента. Если он не указан, клиент будет работать в режиме без WSDL. mode.

Замечание:
По умолчанию WSDL-файл будет кешироваться для повышения производительности. Чтобы отключить или настроить кеширование, смотрите раздел Опции настройки SOAP и параметр cache_wsdl.

options

Ассоциативный массив, определяющий дополнительные параметры для клиента SOAP. Если указан параметр wsdl, это необязательно, в противном случае, по крайней мере параметры location и url должны быть указаны.

location string

URL-адрес сервера 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

/* Предполагая, что ответ, подобный этому, и соответствующий 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 );

Результат выполнения приведённого примера:

По умолчанию:
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"
}

Нашли ошибку?

Инструкция • Исправление • Сообщение об ошибке

＋Добавить

Примечания пользователей 1 note

down

turabgarip at gmail dot com ¶

6 months ago

Two notes about the steam_context option:

1- In the example of the documentation, it says:

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

This is wrong. As it is stated in the parameters list, it must be "stream_context" and NOT "context".

2- The HTTP Context manual here: https://www.php.net/manual/en/context.http.php

It says header can either be of type array or string. This is also wrong. It may not necessarily be optional because it might depend on your PHP compile time configuration.

If your instance is compiled --with-curlwrappers option, you should use array type for header in the HTTP context and if not; you should use a string separated by new line (\n) for the header. I am not sure if SoapClient respects curl_wrappers option because although it is enabled in my instance and although I am using arrays for the headers to create HTTP context for non-Soap operations; SoapClient required me to use a string. It otherwise just dropped the stream_context altogether.

So with SoapClient, you better use a string for the HTTP header like:

<?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]);
?>

＋Добавить