(PHP 5, PHP 7, PHP 8)
SoapClient::__construct — Constructeur SoapClient
Crée un objet SoapClient pour se connecter à un service SOAP.
wsdl
URI du fichier WSDL
ou null
s'il travaille 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, consultez 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 votre certificat et votre 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, utilisez
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. Notez que les noms de types d'un élément ne correspondent 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.
Notez 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 chaîne de caractères spécifiant le
type d'élément XML),
type_ns
(une chaîne de caractères contenant
l'URI de l'espace de noms),
from_xml
(un appelable acceptant un paramètre
de type chaîne de caractères et renvoyant un objet) et
to_xml
(un appelable 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
.
Notez 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. Consultez la section des examples 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, 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 contexte_de_flux
avec le paramètre de contexte 'crypto_method'.
Exemple #1 Spécifier l'utilisation de TLS 1.3 uniquement
<?php
$context = stream_context_create([
'ssl' => [
'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
]
]);
$client = new SoapClient("some.wsdl", ['context' => $context]);
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.
Exemple #2 Example 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 #3 Utilisant la fonctionnalité SOAP_SINGLE_ELEMENT_ARRAYS
/* Assuming a response like this, and an appropriate 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 "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" }