SoapHeader — Klasse · PHP-Referenz

Signatur

class SoapHeader

Beschreibung

SoapHeader repräsentiert einen einzelnen SOAP-Header-Block, der in einer SOAP-Nachricht übertragen werden kann. SOAP-Header dienen dazu, Meta-Informationen wie Authentifizierungstoken, Session-IDs oder Transaktionskontexte zusammen mit dem eigentlichen Nachrichteninhalt zu senden, ohne den SOAP-Body zu verändern.

Instanzen von SoapHeader werden typischerweise über SoapClient::__setSoapHeaders() an ausgehende Anfragen angehängt oder in SoapServer-Anwendungen über SoapServer::addSoapHeader() an Antworten hinzugefügt. So lässt sich z. B. eine WS-Security-Authentifizierung elegant abbilden.

Ein Header-Objekt besteht aus einem Namespace, einem lokalen Namen, einem optionalen Datenwert sowie den SOAP-spezifischen Attributen mustUnderstand und actor (bzw. role in SOAP 1.2). Das Attribut mustUnderstand gibt an, ob der Empfänger den Header zwingend verarbeiten muss.

Parameter

Name	Typ	Default	Beschreibung
$namespace Pflicht	string		Der XML-Namespace-URI des Headers, z. B. `'http://example.com/auth'`.
$name Pflicht	string		Der lokale Name des Header-Elements, z. B. `'AuthHeader'`.
$data	mixed		Der Inhalt des Headers — kann ein einfacher Wert, ein Array oder ein Objekt sein, das automatisch in XML serialisiert wird.
$mustUnderstand	bool	false	Wenn `true`, muss der Empfänger diesen Header verarbeiten können, sonst wird ein SOAP-Fault ausgelöst.
$actor	string\|null	null	URI, die den Empfänger (Actor/Role) des Headers identifiziert. In SOAP 1.1 als `actor`, in SOAP 1.2 als `role` bezeichnet.

Beispiele

Authentifizierungs-Header an eine SOAP-Anfrage anhängen

<?php
$client = new SoapClient('http://example.com/service?wsdl');

// Authentifizierungsdaten als Objekt
$authData = new stdClass();
$authData->username = 'benutzer';
$authData->password = 'geheim';

// SoapHeader erstellen
$header = new SoapHeader(
    'http://example.com/auth',  // Namespace
    'AuthHeader',               // Name
    $authData,                  // Daten
    false                       // mustUnderstand
);

// Header dem Client zuweisen
$client->__setSoapHeaders($header);

// SOAP-Anfrage absenden
try {
    $result = $client->someMethod(['param' => 'wert']);
    var_dump($result);
} catch (SoapFault $e) {
    echo 'Fehler: ' . $e->getMessage();
}

Antwort-Header im SoapServer setzen

<?php
function myWebServiceMethod(): string {
    // Antwort-Header mit Session-ID hinzufügen
    $responseHeader = new SoapHeader(
        'http://example.com/session',
        'SessionHeader',
        ['sessionId' => bin2hex(random_bytes(16))],
        false
    );

    // Globale SoapServer-Instanz muss den Header kennen
    global $server;
    $server->addSoapHeader($responseHeader);

    return 'Anfrage erfolgreich verarbeitet';
}

$server = new SoapServer('http://example.com/service?wsdl');
$server->addFunction('myWebServiceMethod');
$server->handle();

Mehrere Header gleichzeitig setzen

<?php
$client = new SoapClient('http://example.com/service?wsdl');

$authHeader = new SoapHeader(
    'http://example.com/auth',
    'AuthHeader',
    ['token' => 'abc123'],
    true  // mustUnderstand = true
);

$traceHeader = new SoapHeader(
    'http://example.com/trace',
    'TraceHeader',
    ['requestId' => uniqid()]
);

// Mehrere Header als Array übergeben
$client->__setSoapHeaders([$authHeader, $traceHeader]);

try {
    $result = $client->getData();
    print_r($result);
} catch (SoapFault $e) {
    echo 'SOAP-Fehler: ' . $e->getMessage();
}

// Wichtig · Fallstricke

mustUnderstand: Wird mustUnderstand auf true gesetzt und der Empfänger-Server kann den Header nicht verarbeiten, so muss er laut SOAP-Spezifikation einen MustUnderstand-Fault zurückliefern. Setze dieses Flag daher nur, wenn du sicher bist, dass der Server den Header kennt.

Sicherheitshinweis: Übertrage sensible Daten wie Passwörter oder Token im SOAP-Header ausschließlich über verschlüsselte Verbindungen (HTTPS/TLS). Der SOAP-Header wird im Klartext übertragen, sofern keine WS-Security-Verschlüsselung verwendet wird.

Header zurücksetzen: Um alle zuvor gesetzten Header zu entfernen, kann SoapClient::__setSoapHeaders() ohne Argumente oder mit null aufgerufen werden.

Siehe auch

SoapClient SoapServer SoapFault SoapVar SoapParam