Previous Next

Zend_XmlRpc_Client

Einführung

Zend Framework bietet Unterstützung, als Client - durch das Zend_XmlRpc_Client Paket - entfernte XML-RPC-Dienste zu nutzen. Seine wichtigsten Möglichkeiten beinhalten das automatische Umwandeln zwischen PHP und XML-RPC, ein Server Proxy-Objekt und den Zugriff auf Server-Prüfungsmöglichkeiten.

Methodenaufrufe

Der Konstruktor von Zend_XmlRpc_Client erhält den URL des Endpunktes des entfernten XML-RPC-Server als ersten Parameter. Die zurückgegebene Instanz kann genutzt werden, um eine beliebige Anzahl von entfernten Methoden (des Endpunktes) aufzurufen.

Um eine entfernte Methode mittels des XML-RPC-Clients aufzurufen, muss man den Client instanzieren und dessen Methode call() aufrufen. Das hierunter gegebene Codebeispiel demonstriert den XML-RPC server der Zend Framework Webseite. Es kann benutzen, um Zend_XmlRpc-Komponenten zu testen oder auszuprobieren.

Example #1 XML-RPC Methodenaufruf

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

echo $client->call('test.sayHello');

// hello

Der - durch den Aufruf einer entfernten Methode - zurückgegebene, typenlose XML-RPC Wert wird automatisch zu dessen nativen PHP-Äquivalent umgeformt. In obigem Beispiel wird ein string zurückgegeben und ist sofort benutzbar.

Der erste Parameter the Methode call() ist der Name der aufzurufenden Methode. Wenn die entfernte Methode weitere Parameter benötigt, können diese durch einen zweiten, optionalen Parameter des Typs array angegeben werden, wie folgendes Beispiel zeigt:

Example #2 XML-RPC Methodenaufruf mit Parametern

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

$arg1 = 1.1;
$arg2 = 'foo';

$result = $client->call('test.sayHello', array($arg1, $arg2));

// $result ist ein nativer PHP-Typ

Wenn die entfernte Methode keine Parameter erwartet, kann der optionale Parameter weggelassen oder stattdessen ein leeres array() übergeben werden. Das, die Parameter - für die entfernte Methode - enthaltende, Array kann native PHP-Typen, Zend_XmlRpc_Value-Objekte oder eine Mischung aus Beidem enthalten.

Die call()-Methode konvertiert automatisch die XML-RPC-Antwort in dessen äquivalenten nativen PHP-Typen und gibt sie zurück. Ein Zend_XmlRpc_Response-Objekt als Rückgabewert ist auch verfübar durch das Aufrufen der Methode getLastResponse() nach dem Aufruf (der entfernten Methode).

Typen und Konvertierung

Einige entfernte Methodenaufrufe benötigen Parameter. Diese werden an die Methode call() des Zend_XmlRpc_Clients als Array im zweiten Parameter übergeben. Jeder Parameter kann entweder ein nativer PHP-Typ sein, der automatisch konvertiert wird, oder ein Objekt, das einem speziellen XML-RPC-Typen (eines der Zend_XmlRpc_Value-Objekte) entspricht.

Native PHP-Typen als Parameter

Parameter können der Methode call() als native PHP-Variablen übergeben werden, also als string, integer, float, boolean, array oder als ein Objekt. In diesem Fall wird jeder native PHP-Typ automatisch erkannt und dann in sein entsprechendes Pendant konvertiert, welches in dieser Tabelle ersichtlich ist:

PHP- und XML-RPC-Typkonvertierungen
Nativer PHP-Typ XML-RPC Typ
integer int
double double
boolean boolean
string string
array array
associative array struct
object array

Note: Auf welchen Typ werden leere Arrays gecastet?

Die Übergabe eines leeren Array an eine XML-RPC Methode ist problematisch, da es entweder ein Array oder ein Struct repräsentieren könnte. Zend_XmlRpc_Client erkennt solche Konditionen und führt eine Abfrage zur system.methodSignature Methode des Servers aus, um den richtigen XML-RPC Typ festzustellen auf den gecastet werden soll.

Trotzdem kann das selbst sogar zu Problemen führen. Erstens werden Server die system.methodSignature nicht unterstützen fehlerhafte Anfragen protokollieren, und Zend_XmlRpc_Client wird selbst einen Ausweg nehmen und den Wert auf ein Array casten. Zusätzlich bedeutet das das jeder Aufruf mit einem Array Argument zu einem zusätzlichen Aufruf beim Remote Server führt.

Um das Nachsehen komplett abzuschalten kann die setSkipSystemLookup() Methode aufgerufen werden bevor der XML-RPC Aufruf durchgeführt wird:

$client->setSkipSystemLookup(true);
$result = $client->call('foo.bar', array(array()));

Zend_XmlRpc_Value-Objekte als Parameter

Parameter können auch direkt als Zend_XmlRpc_Value-Instanzen erstellt werden, um einen exakten XML-RPC-Typen darzustellen. Die wichtigsten Gründe dafür sind:

  • Wenn sichergestellt werden soll, dass der Prozedur der korrekte Parametertyp übergeben wird (z.B. braucht die Prozedur einen integer, während diese vielleicht von einer Datenbank als String zurückgegeben wird).

  • Wenn die Prozedur einen base64- oder einen dateTime.iso8601-Typ benötigt, da diese nicht als native PHP-Typen existieren.

  • Wenn eine automatische Konvertierung fehlschlägt. Z.B. wenn eine leere XML-RPC-Struktur als Parameter für die Prozedur gewünscht ist. Leere Strukturen werden jedoch als leere Arrays in PHP gehandhabt, was bei einer Übergabe des leeren Arrays dazu führen würde, dass es zu einem Array konvertiert wird, da es kein assoziatives Array ist.

Es gibt zwei Möglichkeiten ein Zend_XmlRpc_Value-Objekt zu erstellen: Direkte Instanzierung einer Zend_XmlRpc_Value-Subklasse oder das Nutzen der statischen Fabrikmethode Zend_XmlRpc_Value::getXmlRpcValue().

Zend_XmlRpc_Value Objekte als XML-RPC Typen
XML-RPC Typ 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

Note: Automatische Konvertierung

Bei der Erstellung eines neuen Zend_XmlRpc_Value-Objekts wird dessen Wert durch einen nativen PHP-Typ gesetzt. Dieser PHP-Typ wird durch PHP-Casting in den gewünschten Typ umgewandelt. Beispielsweise wird ein String, der als Wert für ein Zend_XmlRpc_Value_Integer-Objekt genutzt wird, durch (int)$value in ein Integer konvertiert.

Server-Proxy-Objekt

Ein anderer Weg um entfernte Methoden mittels des XML-RPC-Clients aufzurufen, wird durch die Benutzung des Server-Proxys eröffnet. Dies ist ein PHP-Objekt, das einen entfernten XML-RPC Namensraum umleitet, sodass es möglichst so aussieht, als würde ein natives PHP-Objekt angesprochen werden statt des XML-RPC-Services.

Um einen Server-Proxy zu instanzieren, muss die Methode getProxy() der Klasse Zend_XmlRpc_Client aufgerufen werden. Jeder Methodenaufruf wird zur entsprechenden entfernten Methode weitergeleitet. Die Parameter können übergeben werden, wie bei jeder anderen PHP-Methode.

Example #3 Umleitung zum Standard-Namenraum

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

$server = $client->getProxy();           // Umleitung im Standard-Namenraum

$hello = $server->test->sayHello(1, 2);  // test.Hello(1, 2) gibt "hello" zurück

Die Methode getProxy() erhält ein optionales Argument, welches den Namensraum des entfernten Servers definiert, zu welchem die Methodenaufrufe umgeleitet werden. Wenn kein Namensraum übergeben wird, wird zum Standard-Namensraum umgeleitet. Im nächsten Beispiel wird zum test-Namensraum umgeleitet:

Example #4 Umleitung zu einem beliebigen Namensraum

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

$test  = $client->getProxy('test');     // Leitet zum "test"-Namensraum um

$hello = $test->sayHello(1, 2);         // test.Hello(1,2) gibt "hello" zurück

Wenn der entfernte Server verschachtelte Namensräume jeglicher Tiefe erlaubt, können diese auch durch den Server-Proxy genutzt werden. Wenn der Server in obigem Beispiel eine Methode test.foo.bar() hätte, könnte es durch $test->foo->bar() aufgerufen werden.

Fehlerbehandlung

Es gibt zwei Arten von Fehlern, die während eines XML-RPC Methodenaufruf autreten können: HTTP- und XML-RPC-Fehler. Der Zend_XmlRpc_Client erkennt beide und ermöglicht es, diese unabhängig voneinander zu entdecken und abzufangen.

HTTP-Fehler

Wenn ein HTTP-Fehler auftritt, wie z.B. wenn der entfernte HTTP-Server einen 404 Not Found zurückgibt, wird eine Zend_XmlRpc_Client_HttpException geworfen.

Example #5 Verarbeiten von HTTP-Fehlern

$client = new Zend_XmlRpc_Client('http://foo/404');

try {

    $client->call('bar', array($arg1, $arg2));

} catch (Zend_XmlRpc_Client_HttpException $e) {

    // $e->getCode() gibt 404 zurück
    // $e->getMessage() gibt "Not Found" zurück

}

Ungeachtet des benutzten XML-RPC-Clients wird immer eine Zend_XmlRpc_Client_HttpException geworfen, wenn ein HTTP-Fehler auftritt.

XML-RPC-Fehler

Ein XML-RPC-Fehler wird analog zu einer PHP-Exception verwendet. Es ist ein spezieller Typ, der durch einen XML-RPC-Methodenaufruf zurückgegeben wurden und einen Fehlercode sowie eine -meldung enthält. XML-RPC-Fehler werden unterschiedlich behandelt, was von der Benutzung des Zend_XmlRpc_Clients abhängt.

Wenn die Methode call() oder der Server-Proxy genutzt wird, würde durch einen XML-RPC-Fehler eine Zend_XmlRpc_Client_FaultException geworfen werden. Der Fehlercode und die -meldung der Exception zeigen auf deren zugehörige Werte in der originalen XML-RPC-Fehlerantwort.

Example #6 Verarbeiten von XML-RPC Fehlern

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

try {

    $client->call('badMethod');

} catch (Zend_XmlRpc_Client_FaultException $e) {

    // $e->getCode() gibt 1 zurück
    // $e->getMessage() gibt "Unknown method" zurück

}

Wenn die Methode call() genutzt wird, um eine Anfrage zu starten, wird die Zend_XmlRpc_Client_FaultException bei einem Fehler geworfen. Ein Zend_XmlRpc_Response-Objekt, das den Fehler enthält, ist allerdings auch verfübar durch die Methode getLastResponse().

Wenn die Methode doRequest() genutzt wird, um eine Anfrage zu starten, wird keine Exception geworfen. Stattdessen wird ein Zend_XmlRpc_Response-Objekt zurückgegeben, das den Fehler enthält. Dieses kann durch den Aufruf der Methode isFault() der Klasse Zend_XmlRpc_Response überprüft werden.

Server Selbstüberprüfung

Einige XML-RPC Server bieten de facto Überprüfungsmethoden unter dem XML-RPC Namesraum system.. Zend_XmlRpc_Client stellt spezielle Verfahren für Server mit diesen Möglichkeiten zur Verfügung.

Eine Instanz der Klasse Zend_XmlRpc_Client_ServerIntrospection kann über die Methode getIntrospector() der Klasse Zend_XmlRpcClient zurückgegeben werden. Sie kann dann genutzt werden, um Überwachungsoperationen auf dem Server auszuführen.

Von der Anfrage zur Antwort

Intern erstellt die Methode call() des Zend_XmlRpc_Client-Objekts ein Anfrage-Objekt (Zend_XmlRpc_Request) und sendet es zu einer anderen Methode, doRequest(), die ein Antwort-Objekt (Zend_XmlRpc_Response) zurückgibt.

Die Methode doRequest() kann auch direkt genutzt werden:

Example #7 Eine Anfrage zu einer Antwort verarbeiten

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

$request = new Zend_XmlRpc_Request();
$request->setMethod('test.sayHello');
$request->setParams(array('foo', 'bar'));

$client->doRequest($request);

// $server->getLastRequest() gibt ein Zend_XmlRpc_Request-Objekt zurück
// $server->getLastResponse() gibt ein Zend_XmlRpc_Response-Objekt zurück

Immer wenn eine XML-RPC-Methode vom Client aufgerufen wird, egal auf welche Weise - entweder über die Methode call(), die Methode doRequest() oder den Server-Proxy -, ist das Objekt der letzten Anfrage, sowie dessen resultierende Antwort-Objekte, immer durch die Methoden getLastRequest() und getLastResponse() verfügbar.

HTTP-Client und das Testen

In jedem der vorangegangenen Beispiele wurde kein HTTP-Client bestimmt. In diesem Fall wird eine neue Instanz eines Zend_Http_Clients mit dessen standardmäßigen Einstellungen erstellt und automatisch vom Zend_XmlRpc_Client benutzt.

Der HTTP-Client kann zu jeder Zeit mit der Methode getHttpClient() zurückgegeben werden. In den meisten Fällen jedoch ist der Standard-HTTP-Client ausreichend. Allerdings erlaubt die Methode setHttpClient() das Setzen eines anderen HTTP-Clients.

Die Methode setHttpClient() ist besonders nützlich für UnitTests. Wenn es mit dem Zend_Http_Client_Adapter_Test kombiniert wird, können entfernte Services für das Testen nachgeahmt werden. In den UnitTests für Zend_XmlRpc_Client sind Beispiele, wie so was erreicht werden kann.

Previous Next
Introduction to Zend Framework
Übersicht
Installation
Zend_Acl
Einführung
Verfeinern der Zugriffskontrolle
Fortgeschrittene Verwendung
Zend_Amf
Einführung
Zend_Amf_Server
Zend_Auth
Einführung
Datenbanktabellen Authentifizierung
Digest Authentication
HTTP Authentication Adapter
LDAP Authentifizierung
Open ID Authentifikation
Zend_Cache
Einführung
Die Theorie des Cachens
Zend_Cache Frontends
Zend_Cache Backends
Zend_Captcha
Einführung
Captcha Anwendung
Captcha Adapter
Zend_Config
Einleitung
Theory of Operation
Zend_Config_Ini
Zend_Config_Xml
Zend_Config_Writer
Zend_Config_Writer
Zend_Console_Getopt
Einführung in Getopt
Definieren von Getopt Regeln
Holen von Optionen und Argumenten
Konfigurieren von Zend_Console_Getopt
Zend_Controller
Zend_Controller Schnellstart
Zend_Controller Grundlagen
Der Front Controller
Das Request Objekt
Der Standard Router
Der Dispatcher
Action Kontroller
Action Helfer
Das Response Objekt
Plugins
Eine konventionelle modulare Verzeichnis Struktur verwenden
MVC Ausnahmen
Migration von vorhergehenden Versionen
Zend_Currency
Einführung in Zend_Currency
Arbeiten mit Währungen
Migration von vorhergehenden Versionen
Zend_Date
Einführung
Theorie der Arbeitsweise
Basis Methoden
Zend_Date API Übersicht
Erstellen von Datumswerten
Konstanten für generelle Datums Funktionen
Funktionierende Beispiele
Zend_Db
Zend_Db_Adapter
Zend_Db_Statement
Zend_Db_Profiler
Zend_Db_Select
Zend_Db_Table
Zend_Db_Table_Row
Zend_Db_Table_Rowset
Zend_Db_Table Relationships
Zend_Debug
Variablen ausgeben
Zend_Dojo
Einführung
Zend_Dojo_Data: dojo.data Envelopes
Dojo View Helfer
Dojo Form Elemente und Dekoratore
Zend_Dom
Einführung
Zend_Dom_Query
Zend_Exception
Verwenden von Ausnahmen
Zend_Feed
Einführung
Feeds importieren
Feeds von Websites abrufen
Einen RSS Feed konsumieren
Einen Atom Feed konsumieren
Einen einzelnen Atom Eintrag konsumieren
Verändern der Feed- und Eintragsstruktur
Eigene Klassen für Feeds und Einträge
Zend_File
Zend_File_Transfer
Prüfungen für Zend_File_Transfer
Filter für Zend_File_Transfer
Migration von vorhergehenden Versionen
Zend_Filter
Einführung
Standard Filter Klassen
Filter Ketten
Filter schreiben
Zend_Filter_Input
Zend_Filter_Inflector
Zend_Form
Zend_Form
Schnellstart mit Zend_Form
Erstellen von Form Elementen mit Hilfe von Zend_Form_Element
Erstellen von Form durch Verwendung von Zend_Form
Erstellen von eigenem Form Markup durch Zend_Form_Decorator
Standard Form Elemente die mit dem With Zend Framework ausgeliefert werden
Standard Form Dekoratore die mit dem Zend Framework ausgeliefert werden
Internationalisierung von Zend_Form
Fortgeschrittene Verwendung von Zend_Form
Zend_Gdata
Einführung zu Gdata
Authentifizierung mit AuthSub
Die Buchsuche Daten API verwenden
Authentifizieren mit ClientLogin
Google Kalender verwenden
Verwenden der Google Dokumente Listen Daten API
Using Google Health
Google Tabellenkalkulation verwenden
Google Apps Provisionierung verwenden
Google Base verwenden
Picasa Web Alben verwenden
Verwenden der YouTube Daten API
Gdata Ausnahmen auffangen
Zend_Http
Zend_Http_Client - Einführung
Zend_Http_Client - Fortgeschrittende Nutzung
Zend_Http_Client - Verbindungsadapter
Zend_Http_Cookie und Zend_Http_CookieJar
Zend_Http_Response
Zend_InfoCard
Einführung
Zend_Json
Einführung
Grundlegende Verwendung
JSON Objects
XML zu JSON Konvertierung
Zend_Json_Server - JSON-RPC server
Zend_Layout
Einführung
Zend_Layout Schnellstart
Zend_Layout Konfigurations Optionen
Erweiterte Verwendung von Zend_Layout
Zend_Ldap
Einleitung
Zend_Loader
Dynamisches Laden von Dateien und Klassen
Plugins laden
Zend_Locale
Einführung
Zend_Locale verwenden
Normalisierung und Lokalisierung
Arbeiten mit Daten und Zeiten
Unterstützte Gebietsschemata
Migrieren von vorhergehenden Versionen
Zend_Log
Übersicht
Writer
Formatter
Filter
Zend_Mail
Einführung
Versand über SMTP
Versand von mehreren E-Mails über eine SMTP Verbindung
Verwendung von unterschiedlichen Versandwegen
HTML E-Mail
Anhänge
Empfänger hinzufügen
Die MIME Abgrenzung kontrollieren
Zusätzliche Kopfzeilen
Zeichensätze
Kodierung
SMTP Authentifizierung
SMTP Übertragungen sichern
Lesen von Mail Nachrichten
Zend_Measure
Einführung
Erstellung einer Maßeinheit
Ausgabe von Maßeinheiten
Manipulation von Maßeinheiten
Arten von Maßeinheiten
Zend_Memory
Übersicht
Memory Manager
Memory Objekte
Zend_Mime
Zend_Mime
Zend_Mime_Message
Zend_Mime_Part
Zend_OpenId
Einführung
Zend_OpenId_Consumer Grundlagen
Zend_OpenId_Provider
Zend_Paginator
Einführung
Verwendung
Konfiguration
Advanced usage
Zend_Pdf
Einführung
Erstellen und Laden von PDF Dokumenten
Änderungen von PDF Dokumenten speichern
Dokument Seiten
Zeichnen
Dokument Informationen und Metadaten
Anwendungsbeispiel für die Zend_Pdf Komponente
Zend_ProgressBar
Zend_ProgressBar
Zend_Registry
Die Registry verwenden
Zend_Rest
Einführung
Zend_Rest_Client
Zend_Rest_Server
Zend_Search_Lucene
Überblick
Indexerstellung
Einen Index durchsuchen
Abfragesprache
Abfrage Erzeugungs API
Zeichensätze
Erweiterbarkeit
Zusammenarbeit Mit Java Lucene
Erweitert
Die besten Anwendungen
Zend_Server
Einführung
Zend_Server_Reflection
Zend_Service
Einführung
Zend_Service_Akismet
Zend_Service_Amazon
Zend_Service_Audioscrobbler
Zend_Service_Delicious
Zend_Service_Flickr
Zend_Service_Nirvanix
Zend_Service_ReCaptcha
Zend_Service_Simpy
Einführung
Zend_Service_StrikeIron
Zend_Service_StrikeIron: Mitgelieferte Services
Zend_Service_StrikeIron: Erweiterte Verwendung
Zend_Service_Technorati
Zend_Service_Twitter
Zend_Service_Yahoo
Zend_Session
Einführung
Grundsätzliche Verwendung
Fortgeschrittene Benutzung
Globales Session Management
Zend_Session_SaveHandler_DbTable
Zend_Soap
Zend_Soap_Server
Zend_Soap_Client
WSDL Zugriffsmethoden
AutoDiscovery
Zend_Test
Einführung
Zend_Test_PHPUnit
Zend_Text
Zend_Text_Figlet
Zend_Text_Table
Zend_TimeSync
Einführung
Arbeiten mit Zend_TimeSync
Zend_Translate
Einführung
Adapter für Zend_Translate
Benutzen von Übersetzungs Adaptoren
Migration von vorhergehenden Versionen
Zend_Uri
Zend_Uri
Zend_Validate
Einführung
Standard Prüfklassen
Kettenprüfungen
Schreiben von Prüfern
Zend_Version
Auslesen der Version des Zend Frameworks
Zend_View
Einführung
Controller Skripte
View Scripte
View Helfer
Zend_View_Abstract
Zend_Wildfire
Zend_Wildfire
Zend_XmlRpc
Einführung
Zend_XmlRpc_Client
Zend_XmlRpc_Server
Zend Framework Voraussetzungen
PHP Version
PHP Erweiterungen
Zend Framework Komponenten
Zend Framework Abhängigkeiten
Zend Framework Coding Standard für PHP
Übersicht
PHP Dateiformatierung
Namens Konventionen
Code Stil
Zend Framework Performance Guide
Einführung
Laden von Klassen
Internationalisierung (I18n) und Lokalisierung (L10n)
Darstellen der View
Urheberrecht Informationen