SoapClient::__construct

(PHP 5, PHP 7, PHP 8)

SoapClient::__construct — Constructeur SoapClient

Description

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

Crée un objet SoapClient pour se connecter à un service SOAP.

Liste de paramètres

wsdl

URI du fichier WSDL décrivant le service, qui est utilisé pour automatiquement configurer le client. Si non fourni, le client sera en mode non-WSDL.

Note:
Par défaut, le fichier WSDL sera mis en cache pour des raisons de performance. Pour désactiver ou configurer cette mise en cache, consulter la section SOAP Options de configuration et l'option cache_wsdl

options

Un tableau associatif spécifiant des options supplémentaires pour le client SOAP. Si le paramètre wsdl est fourni, ceci est facultatif ; sinon, au moins les paramètres location et url doivent être fournis.

location string

L'URL du serveur SOAP auquel envoyer la requête.

Requis si le paramètre wsdl n'est pas fourni. Si à la fois un paramètre wsdl et l'option location sont fournis, l'option location remplacera toute location spécifiée dans le fichier WSDL.

uri string

L'espace de noms cible du service SOAP.

Requis si le paramètre wsdl n'est pas fourni; sinon ignoré.

style int

Spécifie le style de liaison à utiliser pour ce client, en utilisant les constantes SOAP_RPC et SOAP_DOCUMENT. SOAP_RPC indique une liaison de style RPC, où le corps de la requête SOAP contient un encodage standard d'un appel de fonction. SOAP_DOCUMENT indique une liaison de style document, où le corps de la requête SOAP contient un document XML avec une signification définie par le service.

Si le paramètre wsdl est fourni, cette option est ignorée et le style est lu à partir du fichier WSDL.

Si ni cette option ni le paramètre wsdl ne sont fournis, le style RPC est utilisé.

use int

Spécifie le style d'encodage à utiliser pour ce client, en utilisant les constantes SOAP_ENCODED ou SOAP_LITERAL. SOAP_ENCODED indique un encodage utilisant les types définis dans la spécification SOAP. SOAP_LITERAL indique un encodage utilisant un schéma défini.

Si le paramètre wsdl est fourni, cette option est ignorée et l'encodage est lu à partir du fichier WSDL.

Si cette option et le paramètre wsdl ne sont pas fournis, le style "encoded" est utilisé.

soap_version int

Spécifie la version du protocole SOAP à utiliser : SOAP_1_1 pour SOAP 1.1, ou SOAP_1_2 pour SOAP 1.2.

Si omis, SOAP 1.1 est utilisé.

authentication int

Spécifie la méthode d'authentification lors de l'utilisation de l'authentification HTTP dans les requêtes. La valeur peut être soit SOAP_AUTHENTICATION_BASIC ou SOAP_AUTHENTICATION_DIGEST.

Si omis et que l'option login est fournie, l'authentification HTTP Basic est utilisée.

login string

Nom d'utilisateur à utiliser avec l'authentification HTTP Basic ou HTTP Digest.

password string

Mot de passe à utiliser avec l'authentification HTTP Basic ou HTTP Digest.

À ne pas confondre avec passphrase, qui est utilisé avec l'authentification par certificat client HTTPS.

local_cert string

Chemin vers un certificat client à utiliser avec l'authentification HTTPS. Il doit s'agir d'un fichier encodé en PEM contenant le certificat et la clé privée.

Le fichier peut également inclure une chaîne d'émetteurs, qui doit venir après le certificat client.

Peut également être défini via stream_context, qui permet également de spécifier un fichier de clé privée distinct.

passphrase string

Passphrase pour le certificat client spécifié dans l'option local_cert.

À ne pas confondre avec password, qui est utilisé avec l'authentification HTTP Basic ou HTTP Digest.

Peut également être défini via stream_context.

proxy_host string

Nom d'hôte à utiliser comme serveur mandataire pour les requêtes HTTP.

L'option proxy_port doit également être spécifiée.

proxy_port int

Port TCP à utiliser lors de la connexion au serveur mandataire spécifié dans proxy_host.

proxy_login string

Nom d'utilisateur facultatif pour s'authentifier auprès du serveur mandataire spécifié dans proxy_host, en utilisant l'authentification HTTP Basic.

proxy_password string

Mot de passe facultatif pour s'authentifier auprès du serveur mandataire spécifié dans proxy_host, en utilisant l'authentification HTTP Basic.

compression int

Active la compression des requêtes et des réponses SOAP HTTP.

La valeur doit être le résultat de l'opération OR binaire de trois parties : un SOAP_COMPRESSION_ACCEPT optionnel, pour envoyer l'en-tête "Accept-Encoding" ; soit SOAP_COMPRESSION_GZIP ou SOAP_COMPRESSION_DEFLATE pour indiquer l'algorithme de compression à utiliser ; et un nombre entre 1 et 9 pour indiquer le niveau de compression à utiliser dans la requête. Par exemple, pour activer la compression gzip bidirectionnelle avec le niveau de compression maximal, utiliser SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9.

encoding string

Définit l'encodage de caractères interne. Les requêtes sont toujours envoyées en UTF-8 et converties depuis et vers cet encodage.

trace bool

Capture les informations de requête et de réponse, qui peuvent ensuite être consultées à l'aide des méthodes SoapClient::__getLastRequest(), SoapClient::__getLastRequestHeaders(), SoapClient::__getLastResponse(), et SoapClient::__getLastResponseHeaders().

Si omis, la valeur par défaut est false

classmap array

Utilisé pour associer les types définis dans le WSDL aux classes PHP. Il doit être spécifié sous la forme d'un tableau associatif avec les noms de types du WSDL en tant que clés et les noms de classes PHP en tant que valeurs. Il est à noter que le nom de type d'un élément ne correspond pas nécessairement au nom de l'élément (balise).

Les noms de classe fournis doivent toujours être entièrement qualifiés avec tous les espaces de noms, et ne jamais commencer par un \. La forme correcte peut être générée en utilisant ::class.

Il est à noter que lors de la création d'une classe, le constructeur ne sera pas appelé, mais les méthodes magiques __set() et __get() pour les propriétés individuelles le seront.

typemap array

Utilisé pour définir des correspondances de types à l'aide de fonctions de rappel définies par l'utilisateur. Chaque correspondance de type doit être un tableau avec les clés type_name (une string spécifiant le type d'élément XML), type_ns (une string contenant l'URI de l'espace de noms), from_xml (un callable acceptant un paramètre de type chaîne de caractères et renvoyant un objet) et to_xml (un callable acceptant un paramètre de type objet et renvoyant une chaîne de caractères).

exceptions bool

Définit si les erreurs génèrent des exceptions de type SoapFault.

Par défaut, c'est true

connection_timeout int

Définit un délai d'attente en secondes pour la connexion au service SOAP. Cette option ne définit pas un délai d'attente pour les services ayant une réponse lente. Pour limiter le temps d'attente des appels, l'option de configuration default_socket_timeout est disponible.

cache_wsdl int

Si le paramètre wsdl est spécifié et que l'option de configuration soap.wsdl_cache_enabled est activée, cette option détermine le type de mise en cache. L'une des constantes WSDL_CACHE_NONE, WSDL_CACHE_DISK, WSDL_CACHE_MEMORY ou WSDL_CACHE_BOTH.

Deux types de cache sont disponibles : le cache en mémoire, qui met en cache le WSDL dans la mémoire du processus en cours, et le cache sur disque, qui met en cache le WSDL dans un fichier sur le disque partagé entre tous les processus. Le répertoire à utiliser pour le cache sur disque est déterminé par l'option de configuration soap.wsdl_cache_dir. Les deux caches ont la même durée de vie, déterminée par l'option de configuration soap.wsdl_cache_ttl. Le cache en mémoire a également un nombre maximum d'entrées déterminé par l'option de configuration soap.wsdl_cache_limit.

Si non spécifié, l'option de configuration soap.wsdl_cache sera utilisée.

user_agent string

La valeur à utiliser dans l'en-tête HTTP User-Agent lors des requêtes.

Peut également être définie via stream_context.

Si non spécifié, l'agent utilisateur sera "PHP-SOAP/" suivi de la valeur de PHP_VERSION.

stream_context resource

Un contexte de flux créé par stream_context_create(), qui permet de définir des options supplémentaires.

Le contexte peut inclure des options de contexte socket, des options de contexte SSL, ainsi que certaines options de contexte HTTP sélectionnées : content_type, header, max_redirects, protocol_version, et user_agent.

Il est à noter que les en-têtes HTTP suivants sont générés automatiquement ou à partir d'autres options, et seront ignorés s'ils sont spécifiés dans l'option de contexte 'header' : host, connection, user-agent, content-length, content-type, cookie, authorization et proxy-authorization.

features int

Un masque de bits pour activer une ou plusieurs des fonctionnalités suivantes :

SOAP_SINGLE_ELEMENT_ARRAYS

Lors du décodage d'une réponse en tableau, le comportement par défaut consiste à détecter si un nom d'élément apparaît une seule fois ou plusieurs fois dans un élément parent particulier. Pour les éléments qui n'apparaissent qu'une fois, une propriété d'objet permet un accès direct au contenu ; pour les éléments qui apparaissent plus d'une fois, la propriété contient un tableau avec le contenu de chaque élément correspondant.

Si la fonctionnalité SOAP_SINGLE_ELEMENT_ARRAYS est activée, les éléments qui n'apparaissent qu'une seule fois sont placés dans un tableau à un seul élément, de sorte que l'accès soit cohérent pour tous les éléments. Cela n'a d'effet que lors de l'utilisation d'un WSDL contenant un schéma pour la réponse. Consulter la section des exemples pour une illustration.

SOAP_USE_XSI_ARRAY_TYPE

Lorsque l'option use option ou la propriété WSDL est définie sur encoded, force les tableaux à utiliser un type SOAP-ENC:Array, plutôt qu'un type spécifique au schéma.

SOAP_WAIT_ONE_WAY_CALLS

Attendre une réponse même si le WSDL indique une requête à sens unique.

keep_alive bool

une valeur booléenne définissant si envoyer l'en-tête Connection: Keep-Alive ou Connection: close.

Par défaut, c'est true

ssl_method string

Spécifie la version du protocole SSL ou TLS à utiliser avec les connexions HTTP sécurisées, au lieu de la négociation par défaut. Spécifier SOAP_SSL_METHOD_SSLv2 ou SOAP_SSL_METHOD_SSLv3 forcera l'utilisation de SSL 2 ou SSL 3, respectivement. Spécifier SOAP_SSL_METHOD_SSLv23 n'a aucun effet ; cette constante n'existe que pour des raisons de compatibilité ascendante. À partir de PHP 7.2.0, spécifier SOAP_SSL_METHOD_TLS n'a également aucun effet ; dans les versions antérieures, cela forçait l'utilisation de TLS 1.0.

Il est à noter que les versions SSL 2 et 3 sont considérées comme non sécurisées et peuvent ne pas être prises en charge par la bibliothèque OpenSSL installée.

Cette option est obsolète à partir de PHP 8.1.0. Une alternative plus flexible, qui permet de spécifier des versions individuelles de TLS, consiste à utiliser l'option stream_context avec le paramètre de contexte 'crypto_method'.

<?php
// Spécifier l'utilisation de TLS 1.3 uniquement
$context = stream_context_create([
    'ssl' => [
        'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
    ]
]);
$client = new SoapClient("some.wsdl", ['context' => $context]);

Erreurs / Exceptions

SoapClient::__construct() génèrera une erreur de type E_ERROR si les options location et uri ne sont pas fournies en mode non-WSDL.

Une exception de type SoapFault sera lancée si l'URI wsdl ne peut être chargée.

Exemples

Exemple #1 Exemple avec 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));

?>

Exemple #2 Utilisant la fonctionnalité SOAP_SINGLE_ELEMENT_ARRAYS

<?php
/* En supposant une réponse comme celle-ci, et un WSDL approprié:
<?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 "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 );

L'exemple ci-dessus va afficher :

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"
}