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] 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] 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] 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
...