17.2. Zend_XmlRpc_Client
Zurück | Kapitel 17. Zend_XmlRpc | Weiter

## 17.2. Zend_XmlRpc_Client

### 17.2.1. Einführung

Die Verwendung von `Zend_XmlRpc_Client` ist sehr ähnlich wie die Verwendung von `SoapClient` Objekten (SOAP web service extension). Du kannst einfach die XML-RPC Dienstprozeduren als `Zend_XmlRpc_Client` Methoden aufrufen. Übergebe die komplette Adresse des Dienstes an den `Zend_XmlRpc_Client` Konstruktor.

Beispiel 17.1. Eine einfache XML-RPC Anfrage

    <?php
    /**
     * Verbinde mit dem framework.zend.com Server und rufe das Array
     * mit den verfügbaren Methoden auf
     */
    require_once 'Zend/XmlRpc/Client.php';

    $server = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');

    print_r( $server->system->listMethods() );

    ?>

| Anmerkung
`Zend_XmlRpc_Client` versucht, die entfernten Methoden so weit wie möglich so aussehen zu lassen wie native Methoden. Wenn eine entfernte Methode Namensräume, wie z.B. das obige `system.listMethods()`, enthält, wird der Aufruf in PHP über Objektverkettungen durchgeführt: `$server->system->listMethods()`.

### 17.2.2. Verwendung von Parametern

Einige XML-RPC Dienstprozeduren benötigen Parameter, so dass die notwendigen Werte als Parameter an die `Zend_XmlRpc_Client` Methode übergeben werden. Die XML-RPC Prozedurparameter müssen von einem bestimmten XML-RPC Typ sein. Parameter können auf zwei Weisen übergeben werden: als native PHP Variablen oder als `Zend_XmlRpc_Value` Objekte, die XML-RPC Typen abbilden.

#### 17.2.2.1. Übergabe von nativen PHP Variablen als Parameter

Parameter, die als native PHP Variablen, also als String, Integer, Float, Boolean, Array oder als Objekt, übergeben werden. In diesem Fall wird jeder native PHP Typ automatisch erkannt und in einen der XML-RPC Typen anhand dieser Tabelle umgewandelt:

Tabelle 17.1. Konvertierung von nativen PHP Variablen in XML-RPC Typen

nativer PHP Typ | XML-RPC Typ
--- | ---
Integer | int
Double | double
Boolean | boolean
String | string
Array | array
assoziatives Array | struct
Objekt | array

    ...
    /**
     *  2 Parameter werden in dieser Prozedur übergeben
     *  Der erste Parameter ist ein String, der automatisch in den XML-RPC String Typ umgewandelt wird
     *  Der zweite Parameter ist ein assoziatives Array, das in den XML-RPC Struct Typ umgewandelt wird
     */

    $p1 = 'parameter 1';
    $p2 = array('name' => 'Joe', 'age' => 30);

    $service->serviceProcedure($p1, $p2);
    ...

#### 17.2.2.2. Übergabe von `Zend_XmlRpc_Value` Objekten als Parameter

Parameter, die als `Zend_XmlRpc_Value` Objekte übergeben werden. Du kannst eine der `Zend_XmlRpc_Value` Instanzen erstellen, um den genauen XML-RPC Typ deiner Parameter festzulegen. Die Hauptgründe für die eindeutig Festlegung der XML-RPC Typen sind:

- Wenn du sicherstellen möchtest, dass der korrekte Parametertyp an die Prozedur übergeben wird (d.h. die Prozedur erfordert einen Integer and du hast den Parameter aus dem $_GET Array als String erhalten)
- Wenn die Prozedur einen base64 oder dateTime.iso8601 Typ erfordert (welche nicht als native PHP Typen existieren)
- Wenn die automatische Konvertierung fehlschlagen könnte (d.h. du möchtest einen leeren XML-RPC Struct als Parameter übergeben. Leere Structs werden in PHP als leere Arrays abgebildet, aber wenn du ein leeres Array als Parameter übergibst, wird es automatisch in ein XML-RPC Array konvertiert, da es kein assoziatives Array ist)

Es gibt zwei Wege, um ein `Zend_XmlRpc_Value` Objekt zu erstellen: den eindeutigen Weg (rufe den Konstruktur des Objekts auf) oder die Verwendung der statischen Funktion `Zend_XmlRpc_Value::getXmlRpcValue()` mit der notwendigen Konstante des XML-RPC Typs.

Tabelle 17.2. `Zend_XmlRpc_Value` Objekt, die den XML-RPC Typ abbilden

XML-RPC Typ | Passende `Zend_XmlRpc_Value` Konstante | `Zend_XmlRpc_Value` Objekt
--- | --- | ---
int | `Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER` | `Zend_XmlRpc_Value_Integer`
double | `Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE` | `Zend_XmlRpc_Value_Double`
boolean | `Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN` | `Zend_XmlRpc_Value_Boolean`
string | `Zend_XmlRpc_Value::XMLRPC_TYPE_STRING` | `Zend_XmlRpc_Value_String`
base64 | `Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64` | `Zend_XmlRpc_Value_Base64`
dateTime.iso8601 | `Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME` | `Zend_XmlRpc_Value_DateTime`
array | `Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY` | `Zend_XmlRpc_Value_Array`
struct | `Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT` | `Zend_XmlRpc_Value_Struct`

    ...
    /**
     *  2 Parameter werden in dieser Prozedur übergeben
     *  Der erste Parameter ist ein XML-RPC base64 Typ, der durch Verwendung der statischen Funktion
     *  Zend_XmlRpc_Value::getXmlRpcValue() erstellt wird
     *  Der zweite Parameter ist ein XML-RPC Struct, der eindeutig erstellt wird
     */

    $p1 = ZXmlRpcValue::getXmlRpcValue('encoded string', Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64);
    $p2 = new Zend_XmlRpc_Value_Struct(array('name' => 'Joe', 'age' => 30));

    $service->serviceProcedure($p1, $p2);
    ...

| Anmerkung
Der Parameterwert wird nach wie vor in einer PHP Variable übergeben, wird aber durch Verwendung der PHP Konvertierungstechniken in den festgelegten Typ konvertiert (d.h. wenn ein String als Wert an das `Zend_XmlRpc_Value_Integer` Objekt übergeben wird, wird es durch Verwendung von `(int)$value` konvertiert).

#### 17.2.2.3. Parse einen XML String in einen XML-RPC Parameter

Diese Methode der Parameterübergabe wird intern im `Zend_XmlRpc` Paket verwendet und die Verwendung wird nicht empfohlen.

Wenn Du dennoch diese Methode verwenden musst, solltest du die statische Funktion `Zend_XmlRpc_Value::getXmlRpcValue()` verwenden, um einen XML String in ein `Zend_XmlRpc_Value` Objekt zu parsen, das den entsprechenden XML-RPC Typ abbildet. Die Funktion `Zend_XmlRpc_Value::getXmlRpcValue()` sollte 2 Parameter übergeben bekommen: den XML String und die `Zend_XmlRpc_Value::XML_STRING` Konstante.

### 17.2.3. Typbestimmung für Parameter

Der Hauptunterschied zwischen XML-RPC und einem SOAP Web Service ist die WSDL Datei. Das SOAP Protokoll hat normalerweise eine WSDL Datei, welche die Schnittstelle des Web Service beschreibt. Entsprechend dieser Schnittstelle, kennt der SOAP Client die notwendigen Paramatertypen, die er an den Server senden muss, und welche Typen die zurückgegebenen Werte haben. Ohne eine WSDL Datei, könnte der Benutzer ein Problem haben, diese Typen zu kennen.

Die Lösung des XML-RPC Protokolls verwendet eine spezielle Prozedur des Dienstes, die `system.methodSignature` lautet. Diese Prozedur erhält einen Prozedurnamen als Parameter und gibt die Signatur der übergegeben Prozedur zurück. Diese Signatur besteht aus den notwendigen Parametertypen und den Typen der zürckgegeben Werte dieser Prozedur.

| Anmerkung
Nicht alle XML-RPC Server unterstützen diese besondere Prozedur `system.methodSignature`. Server, die dies nicht unterstützen, können keine Typbestimmung anbieten.

Der `Zend_XmlRpc_Client` implementiert eine Art von 'WSDL' Typdatei für den XML-RPC Server durch Verwendung der Prozedur `system.methodSignature`. Wenn sie aufgerufen wird, fordert `Zend_XmlRpc_Client` eine Liste aller Prozeduren des XML-RPC Servers an, fordert alle Signaturen dieser Prozeduren an und legt diese Daten in einer XML Datei ab (ähnlich wie die SOAP WSDL Datei). Wenn derselbe XML-RPC Server wieder verwendet wird, kann der Benutzer die XML Datei bereitstellen und der `Zend_XmlRpc_Client` wird die Typen aller Parameter der angeforderten Prozedur entsprechend deren Signatur bestimmen können.

Die XML Datei mit den Signaturen der Prozeduren wird durch Aufruf der Funktion `Zend_XmlRpc_Client::__getMethodsXml()` erstellt (die Funktion gibt einen XML String mit allen Daten der Signatur zurück). Um eine existierende XML Datei mit Signaturen festlegen zu können, kann der Benutzer die XML Daten als Parameter an den Konstruktur von `Zend_XmlRpc_Client` übergeben oder die Funktion `Zend_XmlRpc_Client::__setMethodsXml()` aufrufen.

Beispiel 17.2. Einen XML-RPC Dienst mit Typbestimmung aufrufen

    <?php
    /**
     * Verbinde mit einem XML-RPC Server und speichere die Signaturendatei (das Äquivalent von
     * XML-RPC zur SOAP WSDL Datei)
     */
    require_once 'Zend/XmlRpc/Client.php';

    $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc');

    file_put_contents('/tmp/xmlrpc-signatures/example.xml', $service->__getMethodsXml());

    /**
     * Das $service Objekt enthält alle Signaturen des XML-RPC Servers, wenn die Funktion
     * serviceProcedure() aufgerufen wird, deren Parameter ($param) werden in die notwendigen
     * Typen entsprechend the Signatur der Prozedur konvertiert.
     */
    $service->serviceProcedure($param);
    ?>

    <?php
    /**
     * Beim Verbinden mit einem XML-RPC Server unter Verwendung einer existierenden Signaturdatei
     * stellen wir sicher, dass die Parametertypen, die an die Prozedur übergeben werden, den
     * notwendigen Typen entsprechen
     */
    require_once 'Zend/XmlRpc/Client.php';

    $signature_file_xml = file_get_contents('/tmp/xmlrpc-signatures/example.xml');
    $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc', 'namespace', $signature_file_xml);

    /**
     * Das $service Objekt enthält alle Signaturen des XML-RPC Servers, wenn die Funktion
     * serviceProcedure() aufgerufen wird, deren Parameter ($param) werden in die notwendigen
     * Typen entsprechend the Signatur der Prozedur konvertiert.
     */
    $service->serviceProcedure($param);
    ?>

### 17.2.4. Antworten entgegen nehmen

Die XML-RPC Prozedur gibt einen Wert in einem XML-RPC Typ zurück. Die Methode von `Zend_XmlRpc_Client`, welche die XML-RPC Prozedur aufruft, gibt einen nativen PHP Typ zurück, der aus dem zurückgegebenen XML-RPC Typ konvertiert wurde.

Du kannst die Funktion `Zend_XmlRpc_Client::__getResponse()` verwenden, um den Rückgabewert der angeforderten Prozedur zu erhalten. Die Funktion `__getResponse()` erhält einen Parameter, der auf den Typ des Rückgabewerts hinweist. Die Antwortoptionen sind:

- `Zend_XmlRpc_Client::RESPONSE_PHP_NATIVE` - Gib den Rückgabewert der Prozedur als nativen PHP Typ zurück (konvertiere den XML-RPC Typ in einen PHP Typ).
- `Zend_XmlRpc_Client::RESPONSE_XML_STRING` - Gib eine Darstellung der XML-RPC Antwort in einem XML String zurück.
- `Zend_XmlRpc_Client::RESPONSE_ZXMLRPC_OBJECT` - Gib ein `Zend_XmlRpc_Value` Objekt zurück, dass den erhaltenen XML-RPC Typ abbildet.

    ...
    $service->serviceProcedure();

    $response = $service->__getResponse();
    // $response ist eine PHP Variable, die aus dem XML-RPC Typ des Rückgabewerts konvertiert wurde

    $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_XML_STRING);
    // $response ist ein String, der die XML Darstellung des Rückgabewertes der Prozedur enthält

    $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_ZXMLRPC_OBJECT);
    // $response ist eine Instanz von Zend_XmlRpc_Value, der den XML-RPC Typ des Rückgabewerts abbildet
    ...

Zurück | Nach oben | Weiter
Kapitel 17. Zend_XmlRpc | Zum Anfang | Anhang A. Zend Framework PHP Coding Standard