BiPRO und PHP5

Im Auftrag der iak! GmbH, dem Betreiber des Vergleichsportals vergleichen-und-sparen.de, entwickle ich momentan verschiedene Anbindungen an Webservices, die von Versicherungsunternehmen bereitgestellt werden. Diese Webservices setzen die BiPRO (Brancheninitiative Prozessoptimierung) Normen um. Bei der Entwicklung mit PHP5 bin ich hierbei auf einige Stolpersteine gestoßen, die ich in einer kleinen Serie erläutern werde. Es wird Basiswissen mit Soap Webservices vorausgesetzt.

Heute: Attribute in SoapVar Objekten

Manchmal kommt es vor, dass der einfache Funktionsaufruf eines Webservices mit den entsprechenden Parametern nicht funktioniert. Dies musste ich heute bei der Umsetzung des Webservices zur Abfrage eines Antragsstatus der Rhion Versicherung feststellen. Beim Aufruf der Funktion getStatus lieferte der Webservice immer wieder einen SoapFault. Der Grund hierfür lag im XML Schema, welches vom Soap Client automatisch generiert und gegen die BiPRO Normen und darüber hinaus auch gegen die durch die Versicherung definierten Typen validiert wird. In diesem Fall sagte der SoapFault, dass es ein Attribut „Version“ im Request fehlen würde.
Hat jemand von Euch schon mal versucht ein Attribut in einer objektorientierten Umgebung festzulegen? Nicht? Ich auch nicht. Zumindest bis heute. Wie sich heraus stellte, muss der SoapClient für ein derartiges Vorhaben anders initialisiert werden. Darüber hinaus ist der Aufruf von Webservice-Funktionen mit Attributen ein wenig anders. Aber fangen wir einfach von vorn an.

Die Datenstruktur

Grundsätzlich lege ich für die Parameter, die die Webservice-Funktionen verlangen, Klassen an. Diese Klassen beinhalten die einzelnen Parameter als Klassen-Eigenschaften. Für die Webservice-Funktion getStatus der Rhion Versicherung könnten die Klassen beispielhaft wie folgt aussehen:

class StructStatus {
    public $ProzessID = 0;
    
    public function __construct($ProzessID) {
        $this->ProzessID = $ProzessID;
    }
}

class StructStatusRequest {
    public $Version = '1.0.0.1';
    public $Status = null;
	
    public function __construct($ProzessID) { 
        $this->Status = new StructStatus($ProzessID);
    }
}

Die beiden Klassen bilden die Parameter ab, die durch die im Webservice defnierten Typen festgelegt sind. Die BiPRO legt hier Normen von verschiedenen einfachen und komplexen Datentypen fest, die über die Webservice-Funktionen abgebildet werden.

Der Webservice Client

Wie bereits zuvor geschrieben, muss bei der Initialisierung des Soap Clients mit PHP5 etwas beachtet werden, um die Angabe von Attributen zu gewährleisten. Das folgende Beispiel initialisiert den Client unter anderem mit der Option „classmap“, welche die Abbildung von WSDL-Typen über eine Klassenstruktur erlaubt. Die Initialisierung könnte dann so aussehen:

$client = new SoapClient($wsdl, array(
    'trace' => true,
    'exceptions' => true,
    'soap_version' => SOAP_1_1,
    'cache_wsdl' => WSDL_CACHE_NONE,
    'classmap' => array('Request' => 'StructStatusRequest')
));

Der Funktions-Aufruf

$params = new StructStatusRequest(1234);
$encodedParams = new SoapVar($params, SOAP_ENC_OBJECT, "CT_StatusRequest", 'http://www.bipro.net/namespace');
$result = $client->__soapCall('getStatus', array('parameters' => array('Request' => $encodedParams)));

Um die bereits erwähnte Funktion getStatus aufzurufen, müssen wir zunächst unsere Datenklasse initialisieren. In diesem Beispiel übergeben wir einfach mal eine fiktive Prozess ID. Das daraus resultierende Objekt übergeben wir nicht direkt an die Webservice Funktion, sondern erstellen daraus erst einmal ein SoapVar Objekt. Genau hier liegt auch der Knackpunkt, der es uns ermöglicht das Attribut „Version“ zu setzen. Als dritten Parameter geben wir hier den Namen des Typen an. Der vierte Parameter ist der Namensraum, in dem der Typ definiert wird. Anders als gewohnt, rufen wir auch nicht direkt die Webservice-Funktion über den Namen auf, sondern nutzen die __soapCall() Methode des Webservice Clients, die es uns ermöglicht das zuvor erzeugte SoapVar Objekt an die Funktion zu übergeben.

Wie sieht das Ergebnis aus?

Das Ergebnis ist nun ein sauberes XML Schema mit dem Attribut „Version“. Der XML Knoten, um den es ging, sieht nun wie folgt aus:

    
        1234
    

Ich kann nicht eindeutig sagen, ob der beschriebene Weg der einzig richtige ist. Mir persönlich erscheint er etwas umständlich, um Attribute für XML Knoten anhand der gelieferten WSDL Beschreibung zu erstellen. Ich werde das Gefühl nicht los, dass das auch noch einfacher gehen muss. Wenn mir jemand den entscheidenden Geistesblitz liefern möchte … immer her damit! 😉