W3Net.eu

PHP-ben az xmlrpc bővítménnyel tudunk XML-RPC szolgáltatást készíteni. A bővítmény előnye, hogy C nyelven íródott, így biztosan jobb teljesítményt nyújt, mint más PHP-ben írt XML-RPC könyvtárak. Annak ellenére, hogy már négy éve létezik, sajnos még mindig "experimental" státuszban van. A PHP oldalán elég gyenge dokumentáció olvasható róla, ezért megpróbálom azokat az információkat röviden felsorolni, amelyek nekem hiányoztak.

Az RPC protokollok közül a legismertebbek az XML-RPC és a SOAP.
A távoli eljáráshívás (RPC) lehetővé teszi programunkból más rendszerek API-ját használni. Távoli eljáráshívás alatt azt értjük, hogy meghívunk egy eljárást. Az eljárásnak paramétereket adhatunk át. A távolí eljáráshívás annyiban különbözik a helyi eljáráshívástól, hogy a meghívott eljárást egy másik rendszer valósítja meg, általában egy távoli számítógépen. Az XML-RPC párbeszéd két részből áll: az ügyfél kérelméből és a kiszolgáló válaszából. A kérelmet át kell alakítani egy szabványos nyelvre, el kell küldeni, majd a kiszolgálónak a kérelmet át kell alakítania a számára érthető formára. Ezt a folyamatot “marshalling”-nak nevezzük. Ez természetesen meglehetős lassulással jár.

A kommunikáció HTTP protokollon keresztül történik, az üzenetváltás pedig XML formában. A PHP-hez írt xmlrpc bővítmény csak a kérelem dokumentumok előallítására és a válasz dekódolására szolgál.

Lássunk példát egy egyszerű kérelemdokumentumra:
<?xml version="1.0" encoding="UTF-8"?> <methodCall> <methodName>myfunc</methodName> <params> <param> <value><int>4</int></value> </param> <param> <value><string>Parameter String</string></value> </param> <param> <value><double>2.405</double></value> </param> </params> </methodCall>

A válasz szintén XML formátumú:
<?xml version="1.0" encoding="UTF-8"?> <methodResponse> <params> <param> <value> <string>hello world!</string> </value> </param> </params> </methodResponse>

Hiba esetén ilyen XML dokumentumot kapunk vissza:
<?xml version="1.0" encoding="UTF-8"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value> <int>-1</int> </value> </member> <member> <name>faultString</name> <value> <string>Invalid Procedure Requested</string> </value> </member> </struct> </value> </fault> </methodResponse>

Az xmlrpc bővítmény szerencsére elvégzi helyettünk az XML-dokumentumok előállítását és visszaalakítását (dekódolását)
az xmlrpc_encode_request() és xmlrpc_decode() függvények segítségével.

string xmlrpc_encode_request(string method, mixed params [, array output_options])

mixed xmlrpc_decode(string $xml [, string $encoding])

XML-RPC kiszolgáló létrehozása

Az XML-RPC kérések mindig HTTP POST-ként vannak elküldve. A következő módon tudjuk elérni a nyers POST adatot:
$raw_post_data = file_get_contents("php://input");
Második lépésben létrehozzuk a kiszolgálót:
$rpcserver = xmlrpc_server_create();
A harmadik lépés során visszahívott függvényeket (callback) írunk és meghatározzuk, hogy az egyes bejövő kérelmeket melyik visszahívott függvények fogják ellátni.

Lássunk erre egy példát:
class Webservice { static function Greetings($method_name, $args, $app_data){ if (!is_array($args) || count($args) <> 2){ return array('faultCode'=>-2, 'faultString'=>'Invalid Number of Parameters'); } $firstName = $args[0]; $lastName = $args[1]; return "Hello $firstName $lastName !"; } } function function sayHello($method_name, $args, $app_data){ return "Hello World!"; } xmlrpc_server_register_method($rpcserver, 'test.greetings', 'sayHello'); xmlrpc_server_register_method($rpcserver, 'test.greetings', array('Webservice', 'greetings'));

Mielőtt visszaküldenénk valamit is a kliensnek, be kell állítanunk az adat adattartalom típusát (content type).
if (!headers_sent()){ header("Content-type: text/xml; charset=utf-8"); }

Utolsó lépésben feldolgozzuk a kérelmet és visszaadjuk a kigenerált XML-dokumentumot.

echo xmlrpc_server_call_method($rpcserver, $request_data, array(), array('encoding' => 'utf-8'));

A kliens megírása

Egy távoli eljárás meghívása a következő lépésekre bontható:

1. Az xmlrpc_encode_request() függvénnyel legyártatjuk az XML-lekérést.
   $aOptions = array(); $aOptions['verbosity'] = 'pretty'; $aOptions['encoding'] = 'utf-8'; $xml_request = xmlrpc_encode_request('test.greetings', array('John','Doe'), $aOptions);
2. A legyártott XML-dokumentumot elküldjük a távoli kiszolgálónak (a letölthető forráskódban az XmlRpc_Client osztály valósítja ezt meg).
3. A visszakapott választ az xmlrpc_decode függvénnyel alakítjuk át a PHP saját adattípusára

Az XML-RPC szolgáltatás leírása (Introspection)

Van néhány rezervált függvénynév, amelyeknek speciális feladata van. Ezek a függvények arra szolgálnak, hogy információkat kérjünk le a tagfüggvényekről (függvények paraméterlistái, a paraméterek adattípusai, a függvény visszatérési értéke, stb.). Lényegében a WSDL-hez hasonló célt szolgálnak. Az XML-RPC szolgáltatások automatikus felderítését teszik lehetővé.

system.listMethods

Visszaadja a kiszolgáló által megvalósított összes tagfüggvény nevét.

system.methodHelp

A tagfüggvény neve alapján megadja a lehetséges prototípusokat.

system.methodSignature

Fogadja a tagfüggvény nevét, és a leírásával tér vissza.

system.describeMethods

fully describes the methods and types implemented by this XML-RPC server.

system.multiCall

executes multiple methods in sequence and returns the results

system.getCapabilities

returns a list of capabilities supported by this server

Az xmlrpc bővítményünk szerencsére (majdnem) automatikusan létrehozza helyettünk ezeket a tagfüggfényeket. Mivel a PHP nyelv nem típusos nyelv, ezért saját magunknak kell megadni a típusokat. Ehhez egy XML dokumentumot kell írnunk, amiben az általunk megvalósított tagfüggvényeket írjuk le.

Ezután meg kell irnunk PHP-ben egy függvényt, ami beolvassa a diszkről ezt az XML-fájlt és visszaadja.

Az xmlrpc_server_register_introspection_callback() függvénnyel regisztráljuk az előbb megírt tagfüggvényt. Ez a módszer azért jó, mert az XML-fájl csak akkor lesz beolvasva és feldolgozva, ha tényleg szükség van rá (on demand), azaz amikor egy kliens érdeklődik a webszolgáltatásunk tagfüggvényeiről.

function _introspection_cb($userdata){ return file_get_contents('meta.xml'); } xmlrpc_server_register_introspection_callback($rpcserver, '_introspection_cb');

Ezekkel a speciális függvényekkel az a baj, hogy szinte egyik XMLRPC webszolgáltatás sem implementálta őket (például a Flickr és a WordPress sem). Valószínűleg semmilyen szabvány sem írja ezt elő. Mindenesetre én jó ötletnek tartom, hiszen nem sok munkába kerül, és lehetséges automatikus úton dokumentációt generálni belőle (lásd lentebb a linkeket) a webszolgáltatásunkat használni kivánó fejlesztők részére.

Tagfüggvényeinknek akár többféle paraméterezése (signature - szignatúrája) is lehetséges (egyfajta method overloading). Sajnos az XMLRPC bővítmény nem jól adja vissza a túlterhelt tagfüggvények paraméterezését. Ezt az észrevételemet ezen a fórumon írtam le XMLRPC introspection hiba. Ez azért nem jó hír, mert ha automatikusan szeretnénk kigenerálni a webszolgáltatásunk tagfüggvényeinek listáját automatikus felderítéssel, akkor a túlterhelt tagfüggvények paraméterezése nem lesz jó. Kerülő megoldásnak megírhatunk egy XSLT stíluslapot, ami a meta.xml fájlból készítene dokumentációt.

Letölthető példakód

Megírtam egy rövid, de hasznos példaalkalmazást, amely jó kiindulópont lehet azoknak, akiknek gyorsan kell XML-RPC webszolgáltatást készíteni.
Kipróbálható online is:

• HTML-interfész a tagfüggvények kipróbálására (csak Firefox böngészővel működik)
• A tagfüggvények leírása XML-fájlban
• Letölthető forráskód

És mi a helyzet a SOAP-al?

Egy webszolgáltatás megírása előtt el kell döntenünk, hogy SOAP-ot, vagy XML-RPC-t használjunk-e. Ilyenkor figyelembe kell vennünk a következő tényezőket:

• programozási nyelv
• milyen programozási nyelven íródott kliensek fogják használni a webszolgáltatást
• enterprise méretű webszolgáltatást írunk-e

A SOAP mellett szól, hogy W3C-szabványos leírónyelven kommunikál, és kliens-alkalmazások megírása is egyszerűbb.
Ha PHP-ben egyszerű lenne SOAP kiszolgáló megírása, gondolkodás nélkül a SOAP-ot választanám. ASP.NET-ben például egy SOAP szerver létrehozása gyerekjáték, szinte semmivel sem kell törődnünk, mindenről a .NET gondoskodik. PHP-be azonban egyáltalán nem könnyű és fáradságmentes egy SOAP szerver megírása. Magunknak kell megírni a WSDL (Web Services Description Language - webszolgáltatás-leíró nyelv) fájlt, ami jónéhány hosszú W3C-ajánlás elolvasását követeli meg. Erre meglehetősen sok idő elmegy, így sokan az XML-RPC-t használják PHP-ben.

Ha webszolgáltatásunkat csak PHP kliensek fogják használni, nyugodtan használjunk XMLRPC-t. Komoly méretű webszolgáltatáshoz mindenképpen a SOAP-ot tudom javasolni. A WSDL fájl megírásában esetleg segítségünkre lehet a Zend Studio WSDL generátora. Más ötletem nincsen, hogyan lehetne megúszni a WSDL fájl fáradságos megírását.

Remélem ez a rövid összefoglalás hasznos útmutatást adott azoknak, akik most tervezik saját webszolgáltatás írását.

A témához kapcsolódó linkek

• XML-RPC Specification
• XML-RPC: Együttműködés távoli szolgáltatásokkal
• Introspection
• jsolait (JavaScript O Lait)
• JSON-RPC