Signatur
Beschreibung
SoapFault ist eine spezialisierte Exception-Klasse, die SOAP-Fehler (Fault-Nachrichten gemäß SOAP-Spezifikation) kapselt. Sie wird automatisch vom SoapClient geworfen, wenn der Server einen SOAP Fault zurückliefert, und kann auch manuell im SoapServer-Kontext geworfen werden, um dem Client einen strukturierten Fehler zu melden.
Ein SOAP Fault enthält immer einen Faultcode und eine Faultstring-Nachricht. Optional können auch ein Faultactor (wer den Fehler verursacht hat), Detail-Informationen sowie der Fehler-Namensraum und Header-Fehler mitgeliefert werden. Diese Felder entsprechen den SOAP-Spezifikationselementen für Fault-Nachrichten.
Bei der serverseitigen Nutzung sollte man innerhalb des Handlers eines SoapServer-Objekts eine SoapFault-Exception werfen, die dann automatisch in eine korrekte SOAP-Fault-Antwort umgewandelt wird. Clientseitig werden eingehende Fault-Antworten automatisch in SoapFault-Exceptions umgewandelt, sofern der Client im normalen (nicht WSDL-losen) Modus betrieben wird.
Da SoapFault von RuntimeException erbt, kann sie mit dem Standard-try/catch-Mechanismus behandelt werden. Öffentliche Eigenschaften wie faultcode, faultstring, faultactor und detail geben direkten Zugriff auf die SOAP-Fault-Felder.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $faultcode Pflicht | string | Der SOAP-Fehlercode, z. B. 'Client', 'Server', 'VersionMismatch' oder 'MustUnderstand' (bei SOAP 1.1) bzw. entsprechende Werte bei SOAP 1.2. |
|
| $faultstring Pflicht | string | Eine menschenlesbare Fehlermeldung, die den SOAP-Fehler beschreibt. Entspricht dem <faultstring>-Element in der SOAP-Antwort. |
|
| $faultactor | string|null | null | Optionaler URI, der angibt, welcher Akteur (Node) im SOAP-Verarbeitungspfad den Fehler verursacht hat. Entspricht dem <faultactor>-Element. |
| $detail | mixed | null | Optionale applikationsspezifische Fehlerdetails. Kann ein String, ein Objekt oder ein Array sein und wird in das <detail>-Element der SOAP-Fault-Antwort eingebettet. |
| $faultname | string|null | null | Ein optionaler Name für den Fehler, der bei der Zuordnung zu Fault-Definitionen in einer WSDL-Datei verwendet wird. |
| $headerfault | mixed | null | Optionale Fehlerinformationen, die in einem SOAP-Header-Fault zurückgegeben werden sollen, wenn der Fehler beim Verarbeiten eines SOAP-Headers auftritt. |
Beispiele
SoapFault auf der Serverseite werfen
<?php
// Serverseitiger Handler, der bei einem Fehler einen SOAP Fault sendet
function getUserData(int $userId): array
{
if ($userId <= 0) {
throw new SoapFault(
'Client',
'Ungültige Benutzer-ID: Die ID muss größer als 0 sein.',
null,
['invalidValue' => $userId]
);
}
// ... Daten laden und zurückgeben
return ['id' => $userId, 'name' => 'Max Mustermann'];
}
$server = new SoapServer('service.wsdl');
$server->addFunction('getUserData');
$server->handle();
?>SoapFault auf der Clientseite abfangen
<?php
$client = new SoapClient('https://example.com/service.wsdl', [
'exceptions' => true,
]);
try {
$result = $client->getUserData(-5);
print_r($result);
} catch (SoapFault $e) {
echo 'SOAP-Fehlercode: ' . $e->faultcode . PHP_EOL;
echo 'SOAP-Fehlermeldung: ' . $e->faultstring . PHP_EOL;
if (!empty($e->detail)) {
echo 'Detail: ';
print_r($e->detail);
}
}
?>SoapFault manuell erzeugen und Eigenschaften auslesen
<?php
$fault = new SoapFault(
'Server',
'Interner Serverfehler',
'urn:beispiel:servicenode',
'Datenbankverbindung fehlgeschlagen'
);
echo $fault->faultcode . PHP_EOL; // Server
echo $fault->faultstring . PHP_EOL; // Interner Serverfehler
echo $fault->faultactor . PHP_EOL; // urn:beispiel:servicenode
echo $fault->detail . PHP_EOL; // Datenbankverbindung fehlgeschlagen
// getMessage() ist durch RuntimeException verfügbar
echo $fault->getMessage() . PHP_EOL; // Interner Serverfehler
?>// Wichtig · Fallstricke
Exceptions-Modus beachten: SoapFault wird vom SoapClient nur dann geworfen, wenn die Option 'exceptions' => true (Standard) gesetzt ist. Bei 'exceptions' => false gibt der Client stattdessen ein SoapFault-Objekt als Rückgabewert zurück; dies sollte mit is_soap_fault() geprüft werden.
Öffentliche Eigenschaften: Die Eigenschaften faultcode, faultstring, faultactor und detail sind öffentlich und direkt zugänglich. faultstring wird zusätzlich als Exception-Message gesetzt, sodass getMessage() denselben Wert liefert.
SOAP 1.1 vs. 1.2: Die erlaubten Werte für faultcode unterscheiden sich je nach SOAP-Version. Bei SOAP 1.2 heißen die Codes z. B. 'Sender' und 'Receiver' statt 'Client' und 'Server'.
Keine sensiblen Daten im Detail: Das detail-Feld wird im Klartext an den Client übertragen. Es sollten keine internen Stack-Traces, Datenbankstrukturdetails oder andere sicherheitsrelevante Informationen darin platziert werden.