SoapClient::__construct

(PHP 5, PHP 7, PHP 8)

SoapClient::__construct — SoapClient-Konstruktor

Beschreibung

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

Erstellt ein SoapClient-Objekt, um eine Verbindung zu einem SOAP-Dienst herzustellen.

Parameter-Liste

wsdl

Der URI einer WSDL-Datei, die den Dienst beschreibt, der verwendet wird, um den Client automatisch zu konfigurieren. Wenn er nicht angegeben wird, arbeitet der Client im non-WSDL-Modus.

Hinweis:
Standardmäßig wird die WSDL-Datei aus Performance-Gründen zwischengespeichert. Um diese Zwischenspeicherung zu deaktivieren oder zu konfigurieren, siehe die SOAP-Konfigurationsoptionen und die Option cache_wsdl.

options

Ein assoziatives Array, das zusätzliche Optionen für den SOAP-Client angibt. Wenn wsdl angegeben wird, ist es optional, andernfalls müssen mindestens location und url angegeben werden.

location string

Die URL des SOAP-Servers, an den die Anfrage gesendet werden soll.

Wird benötigt, wenn der Parameter wsdl nicht angegeben wird. Wenn sowohl der Parameter wsdl als auch die Option location angegeben werden, überschreibt die Option location alle in der WSDL-Datei angegeben Orte.

uri string

Der Ziel-Namensraum des SOAP-Dienstes.

Wird benötigt, wenn der Parameter wsdl nicht angegeben wird, andernfalls wird er ignoriert.

style int

Mit den Konstanten SOAP_RPC und SOAP_DOCUMENT kann der Bindungsstil angegeben werden, der für diesen Client verwendet werden soll. SOAP_RPC gibt an, dass die Bindung im RPC-Stil verwendet werden soll, bei der der Body der SOAP-Anfrage die Standardkodierung des Funktionsaufrufs enthält. SOAP_DOCUMENT gibt an, dass die Bindung im Dokumentenstil verwendet werden soll, wobei der Body der SOAP-Anfrage ein XML-Dokument mit einer durch den Dienst definierten Bedeutung enthält.

Wenn der Parameter wsdl angegeben wird, wird diese Option ignoriert und der Stil wird aus der WSDL-Datei gelesen.

Wenn weder diese Option noch der Parameter wsdl angegeben wird, wird der RPC-Stil verwendet.

use int

Mit den Konstanten SOAP_ENCODED und SOAP_LITERAL kann der Kodierungsstil angegeben werden, der für diesem Client verwendet werden soll. SOAP_ENCODED gibt an, dass ein in der SOAP-Spezifikation definierter Kodierungstyp verwendet werden soll. SOAP_LITERAL gibt an, dass das vom Dienst definierte Schema für die Kodierung verwendet werden soll.

Wenn der Parameter wsdl angegeben wird, wird diese Option ignoriert und die Kodierung wird aus der WSDL-Datei gelesen.

Wenn weder diese Option noch der Parameter wsdl angegeben wird, wird der Stil "encoded" verwendet.

soap_version int

Gibt die Version des SOAP-Protokolls an, die verwendet werden soll: SOAP_1_1 für SOAP 1.1 oder SOAP_1_2 für SOAP 1.2.

Wenn diese Option weggelassen wird, wird SOAP 1.1 verwendet.

authentication int

Wenn für Anfragen die HTTP-Authentifizierung verwendet wird, bestimmt diese Option die Authentifizierungsmethode. Als Wert kann SOAP_AUTHENTICATION_BASIC oder SOAP_AUTHENTICATION_DIGEST angegeben werden.

Wenn diese Option weggelassen wird und die Option login vorhanden ist, wird die Basic Authentication verwendet.

login string

Der Benutzername, der für die Basic oder Digest Authentication verwendet wird.

password string

Das Passwort, das für die Basic oder Digest Authentication verwendet wird.

Nicht zu verwechseln mit passphrase, das für die Authentifizierung mit HTTPS-Client-Zertifikat verwendet wird.

local_cert string

Der Pfad zu einem Client-Zertifikat für die Verwendung mit der HTTPS-Authentifizierung. Es muss sich um eine PEM-kodierte Datei handeln, die das Zertifikat und den privaten Schlüssel enthält.

Die Datei kann auch eine Kette von Zertifikatsausstellern enthalten, die hinter dem Client-Zertifikat angehängt sein muss.

Kann auch mittels stream_context gesetzt werden, das auch die Angabe einer separaten privaten Schlüsseldatei unterstützt.

passphrase string

Die Passphrase für das Client-Zertifikat, das in der Option local_cert angegeben ist.

Nicht zu verwechseln mit password, das für die Basic oder Digest Authentication verwendet wird.

Kann auch mittels stream_context gesetzt werden.

proxy_host string

Der Hostname, der als Proxy-Server für HTTP-Anfragen verwendet werden soll.

Die Option proxy_port muss ebenfalls angegeben werden.

proxy_port int

Der TCP-Port, der bei der Verbindung mit dem in proxy_host angegebenen Proxy-Server verwendet werden soll.

proxy_login string

Optionaler Benutzername zur Authentifizierung bei dem in proxy_host angegebenen Proxyserver, unter Verwendung der HTTP Basic Authentication.

proxy_password string

Optionales Passwort zur Authentifizierung bei dem in proxy_host angegebenen Proxyserver, unter Verwendung der HTTP Basic Authentication.

compression int

Aktiviert die Komprimierung von HTTP-SOAP-Anfragen und -Antworten.

Der Wert ist ein bitweises OR aus drei Teilen: das optionale SOAP_COMPRESSION_ACCEPT, um einen "Accept-Encoding"-Header zu senden, entweder SOAP_COMPRESSION_GZIP oder SOAP_COMPRESSION_DEFLATE, um den zu verwendenden Komprimierungsalgorithmus anzugeben, und eine Zahl zwischen 1 und 9, um die Komprimierungsstufe anzugeben, die in der Anfrage verwendet werden soll. Um zum Beispiel eine bidirektionale Gzip-Kompression mit der maximalen Komprimierungsstufe zu aktivieren, wird SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9 verwendet.

encoding string

Gibt die interne Zeichenkodierung an. Anfragen werden immer von der hier angegebenen Kodierung in UTF-8 umgewandelt und Antworten werden in diese Kodierung umgewandelt.

trace bool

Erfasst Anfrage- und Antwortinformationen, auf die dann mit den Methoden SoapClient::__getLastRequest(), SoapClient::__getLastRequestHeaders(), SoapClient::__getLastResponse() und SoapClient::__getLastResponseHeaders() zugegriffen werden kann.

Falls nicht angegeben, ist der Standardwert false.

classmap array

Wird verwendet, um in der WSDL definierte Typen auf PHP-Klassen abzubilden. Diese Option benötigt ein assoziatives Array mit den Typnamen aus der WSDL als Schlüssel und den Namen von PHP-Klassen als Werte. Es ist zu beachten, dass der Typname eines Elements nicht notwendigerweise derselbe ist wie der (Tag-)Name des Elements.

Die angegebenen Klassennamen müssen immer voll qualifiziert sein mit allen Namensräumen und dürfen nicht mit einem \ beginnen. Die korrekte Form kann mit ::class erzeugt werden.

Zu beachten ist auch, dass beim Erstellen einer Klasse nicht der Konstruktor aufgerufen wird, sondern die Methoden __set() und __get() für die einzelnen Eigenschaften aufgerufen werden.

typemap array

Wird verwendet, um Typzuordnungen mit Hilfe benutzerdefinierter Callback-Funktionen zu definieren. Jede Typzuordnung ist ein Array mit den Schlüsseln type_name (eine Zeichenkette, die den Typ des XML-Elements angibt), type_ns (eine Zeichenkette mit dem Namesraum-URI), from_xml (ein Callable, das eine Zeichenkette als Parameter akzeptiert und ein Objekt zurückgibt) und to_xml (ein Callable, das ein Objekt als Parameter akzeptiert und eine Zeichenkette zurückgibt).

exceptions bool

Legt fest, ob Fehler Exceptions des Typs SoapFault auslösen.

Der Standardwert ist true

connection_timeout int

Legt das Zeitlimit für die Verbindung mit dem SOAP-Dienst fest (in Sekunden). Mit dieser Option wird kein Zeitlimit für Dienste mit langsamen Antworten festgelegt. Um die Zeit zu begrenzen, die auf den Abschluss von Aufrufen gewartet wird, steht die Konfigurationsoption default_socket_timeout zur Verfügung.

cache_wsdl int

Wenn der Parameter wsdl angegeben wird, und die Konfigurationsoption soap.wsdl_cache_enabled aktiviert ist, bestimmt diese Option die Art der Zwischenspeicherung. Es kann einer der Werte WSDL_CACHE_NONE, WSDL_CACHE_DISK, WSDL_CACHE_MEMORY oder WSDL_CACHE_BOTH sein.

Es stehen zwei Arten von Caches zur Verfügung: In-Memory-Caching, bei dem die WSDL im Speicher des aktuellen Prozesses zwischenspeichert wird, und Festplatten-Caching, bei dem die WSDL auf der Festplatte in einer Datei zwischenspeichert wird, die von allen Prozessen gemeinsam genutzt werden kann. Das Verzeichnis, das für den Festplatten-Cache verwendet wird, kann durch die Konfigurationsoption soap.wsdl_cache_dir angegeben werden. Beide Caches verwenden die gleiche Lebensdauer, die durch die Konfigurationsoption soap.wsdl_cache_ttl festgelegt ist. Für den In-Memory-Cache kann die maximale Anzahl von Einträgen mit der Konfigurationsoption soap.wsdl_cache_limit festgelegt werden.

Falls nicht angegeben, wird die Konfigurationsoption soap.wsdl_cache verwendet.

user_agent string

Der Wert, der im HTTP-Header User-Agent bei Anfragen zu verwenden ist.

Dieser Wert kann auch über stream_context gesetzt werden.

Falls nicht angegeben, ist der User-Agent "PHP-SOAP/", gefolgt vom Wert der Konstante PHP_VERSION.

stream_context resource

Ein Stream-Kontext, der mit der Funktion stream_context_create() erstellt werden kann und es ermöglicht, zusätzliche Optionen zu setzen.

Der Kontext kann Socket-Kontextoptionen, SSL-Kontextoptionen, sowie ausgewählte HTTP-Kontextoptionen enthalten: content_type, header, max_redirects, protocol_version und user_agent.

Es ist zu beachten, dass die folgenden HTTP-Header automatisch oder aus anderen Optionen generiert werden, und dass sie ignoriert werden, wenn sie in der Kontextoption 'header' angegeben werden: host, connection, user-agent, content-length, content-type, cookie, authorization und proxy-authorization.

features int

Eine Bitmaske zur Aktivierung einer oder mehrerer der folgenden Funktionen:

SOAP_SINGLE_ELEMENT_ARRAYS

Beim Dekodieren einer Antwort in ein Array wird standardmäßig automatisch erkannt, ob der Name eines Elements einmal oder mehrmals in einem bestimmten übergeordneten Element vorkommt. Bei Elementen, die nur einmal vorkommen, kann der Inhalt direkt über die Eigenschaften des Objekts abgerufen werden. Bei Elementen, die mehrfach vorkommen, enthält die Eigenschaft ein Array mit dem Inhalt der entsprechenden Elemente.

Wenn das Feature SOAP_SINGLE_ELEMENT_ARRAYS aktiviert ist, werden die Elemente, die nur einmal vorkommen, in einem Array mit einem einzigen Element abgelegt, sodass der Zugriff für alle Elemente konsistent ist. Dies hat nur eine Auswirkung, wenn eine WSDL verwendet wird, die ein Schema für die Antwort enthält. Im Abschnitt Beispiele wird dies anschaulich dargestellt.

SOAP_USE_XSI_ARRAY_TYPE

Wenn die Option use oder die WSDL-Eigenschaft auf encoded gesetzt ist, verwenden Arrays statt eines schemaspezifischen Typs den Typ SOAP-ENC:Array.

SOAP_WAIT_ONE_WAY_CALLS

Auf eine Antwort warten, auch wenn die WSDL eine einseitige Anfrage angibt.

keep_alive bool

Ein boolescher Wert, der definiert, ob der Header Connection: Keep-Alive oder der Header Connection: close gesendet wird.

Der Standardwert ist true

ssl_method string

Gibt die SSL- oder TLS-Protokollversion an, die für sichere HTTP-Verbindungen anstelle der Standardvereinbarung (default negotiation) verwendet werden soll. Die Angabe von SOAP_SSL_METHOD_SSLv2 oder SOAP_SSL_METHOD_SSLv3 erzwingt die Verwendung von SSL 2 bzw. SSL 3. Die Angabe von SOAP_SSL_METHOD_SSLv23 hat keine Auswirkung; Diese Konstante existiert nur aus Gründen der Abwärtskompatibilität. Seit PHP 7.2 hat auch die Angabe von SOAP_SSL_METHOD_TLS keine Auswirkung mehr; in früheren Versionen erzwang sie die Verwendung von TLS 1.0.

Es ist zu beachten, dass die SSL-Versionen 2 und 3 als unsicher gelten und von der installierten OpenSSL-Bibliothek möglicherweise nicht unterstützt werden.

Diese Option ist seit PHP 8.1.0 als VERALTET markiert und sollte nicht mehr verwendet werden. Die Option stream_context bietet mit dem Kontextparameter 'crypto_method' eine flexiblere Alternative, die es ermöglicht, einzelne Versionen von TLS anzugeben.

Beispiel #1 Die Verwendung von TLS 1.3 vorschreiben

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

Fehler/Exceptions

Wenn die Optionen location und uri im non-WSDL-Modus nicht angegeben werden, erzeugt SoapClient::__construct() einen Fehler der Stufe E_ERROR.

Wenn der wsdl-URI nicht geladen werden kann, wird eine SoapFault-Exception ausgelöst.

Beispiele

Beispiel #2 SoapClient::__construct()-Beispiel

<?php

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

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

$client = new SoapClient("ein.wsdl", array('login'          => "ein_name",
                                           'password'       => "ein_passwort"));

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

$client = new SoapClient("ein.wsdl", array('proxy_host'     => "localhost",
                                           'proxy_port'     => 8080,
                                           'proxy_login'    => "ein_name",
                                           'proxy_password' => "ein_passwort"));

$client = new SoapClient("ein.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("ein.wsdl",
  array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9));

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

class MeinBuch {
    public $titel;
    public $autor;
}

$client = new SoapClient("buecher.wsdl", array('classmap' => array('book' => "MeinBuch")));

$typemap = array(
    array("type_ns"  => "http://schemas.example.com",
         "type_name" => "book",
         "from_xml"  => "unserialize_book",
         "to_xml"    => "serialize_book")
);
$client = new SoapClient("buecher.wsdl", array('typemap' => $typemap));

?>

Beispiel #3 Verwendung des Features SOAP_SINGLE_ELEMENT_ARRAYS

<?php
/* Unter der Annahme einer Antwort wie dieser und einer entsprechenden 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 "Voreinstellung:\n";

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

echo "\nMit 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 );

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Voreinstellung:
string(6) "Single"
array(2) {
  [0] =>
  string(5) "First"
  [1] =>
  string(6) "Second"
}

Mit SOAP_SINGLE_ELEMENT_ARRAYS:
array(1) {
  [0] =>
  string(6) "Single"
}
array(2) {
  [0] =>
  string(5) "First"
  [1] =>
  string(6) "Second"
}