XML and PHP

2017-07-07 02:10:07

I l @ ve RuBoard

XML-RPC, as defined on its official web site, is ". . . a spec and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet . . ." ^[1] It was created in 1998 to provide a simple portable framework for transmitting procedure calls and receiving responses over the Internet.

^[1] UserLand Software, Inc. "XML-RPC Home Page." Available from the Internet: http://www.xmlrpc.org/. Last updated: November 5, 2001 .

As the preceding definition states, XML-RPC actually consists of two parts : the XML-RPC specification itself, which defines the structure and format of XML-RPC procedure calls and responses; and a set of implementations for different platforms. Because XML-RPC was designed from the get-go to be easily portable, it won't surprise you to hear that it has spawned a diverse array of implementations. As of this writing, the official web site lists more than 50 different implementations in languages such as Lisp, AppleScript, JavaScript, C, Perl, Python, and PHP.

D ja Vu

If some of this sounds familiar, give yourself 10 points for attentiveness ”because it should. Though the two specifications address different problems, XML-RPC shares a number of important traits with Web Distributed Data eXchange (WDDX) that was last seen in Chapter 5, "PHP and Web Distributed Data eXchange(WDDX)." Here's a brief list:

Neither WDDX nor XML-RPC is an official standard per se; they're both open specifications created by one company and popularized via the developer community.

Both specifications provide an open, extensible architecture for information exchange.

Both specifications use XML as their encoding toolkit. XML-RPC requires HTTP exclusively as its transmission layer, whereas WDDX can be transmitted over any protocol that supports text (HTTP, POP, FTP, SMTP, and so on).

Both specifications use similar data structures to represent native data types.

Both specifications' implementations are available for a wide variety of different languages and platforms.

An XML-RPC procedure call is encoded as a well- formed XML document, with both procedure name and arguments enclosed within a <methodCall> document element. This procedure call is transmitted to the XML-RPC server as a standard HTTP POST request.

Listing 6.1 demonstrates an XML-RPC request to the server some.quote.server ; the request itself is equivalent to calling the function getRandomQuote("Shakespeare") .

Listing 6.1 An XML-RPC Request

POST /RPC2 HTTP/1.0 User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 95) Host: some.quote.server Content-Type: text/xml Content-Length: 287 <?xml version="1.0" ?> <methodCall> <methodName>getRandomQuote</methodName> <params> <param> <value> <string>Shakespeare</string> </value> </param> </params> </methodCall>

As you can see, the XML-RPC request body is clearly demarcated into two sections.The <methodName> element contains the name of the procedure to be invoked on the remote server, whereas the <params> element encloses a list of arguments to be passed to the remote procedure. Individual arguments are represented by individual <param> elements, which in turn enclose a data-typed value (take a look at the following sidebar entitled "Atypically Yours" for a list of the various data types supported by XML-RPC).

The server decodes and interprets the request, processes it, and returns the result to the requesting client, again as an XML-encoded HTTP POST response. Listing 6.2 demonstrates what it might look like.

Listing 6.2 An XML-RPC Response to a Successful RPC Request

HTTP/1.0 200 OK Server: QuoteServer/RPC Connection: close Content-Type: text/xml Content-Length: 270 <?xml version="1.0"?> <methodResponse> <params> <param> <value> <string>Good night, sweet prince, and flights of angels sing thee to thy rest.</string> </value> </param> </params> </methodResponse>

Atypically Yours

The XML-RPC specification currently defines the following data types:

Boolean values, represented by the <boolean> element

Signed 32-bit integers, represented by the <int> or <i4> element

Signed floating-point numbers , represented by the <double> element

ASCII strings, represented by the <string> element (this is the default type)

Date/time values, represented by the <dateTime.iso8601> element (these values must be encoded in ISO8601 format, but the XML-RPC specification does not make any assumption about the time zone offset used)

Binary data encoded with BASE64, represented by the <base64> element

Integer-indexed arrays, represented by the <array> element

Structures, or string-indexed arrays, represented by the <struct> element

Every XML-RPC response must return an HTTP status code of 200 OK ; however, the content of the response differs , depending on whether or not an error occurred while processing the XML-RPC request. The response to a successful RPC invocation looks like Listing 6.2: a document element named <methodResponse> that contains one <params> element enclosing the value returned by the procedure.

An unsuccessful RPC invocation generates an error, which looks like Listing 6.3.

Listing 6.3 An XML-RPC Response to an Unsuccessful RPC Request

HTTP/1.0 200 OK Server: QuoteServer/RPC Connection: close Content-Type: text/xml Content-Length: 585 <?xml version="1.0"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value> <int>2</int> </value> </member> <member> <name>faultString</name> <value> <string>No quotes by that author</string> </value> </member> </struct> </value> </fault> </methodResponse>

In this case, though the document element remains the same, the <params> element is replaced by a <fault> element, which is itself a <struct> containing an error code and a human-friendly error string.

That pretty much covers the basics of XML-RPC. For more information and examples, you should refer to the official web site at http://www.xmlrpc.org/, which contains the complete XML-RPC specification (with examples and code samples), a list of implementations for different platforms, tutorials, FAQs, and a discussion forum.