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() .
|
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.
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); ...
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:
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).
|
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.
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); ?>
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 ...