Chapter 6: PHP and XML-Remote Procedure Calls | Integrating PHP and XML 2004

Download CD Content

Extensible Markup Language-Remote Procedure Call (XML-RPC) is a protocol that allows applications running on various operating systems to make procedure calls on a remote server for executing a procedure.

Implementing XML-RPC in PHP helps build network-based services. You can implement XML-RPC in PHP to encode and decode Remote Procedure Call (RPC) messages and create and manage a remote server. This implies that you can use PHP scripts to invoke procedures on remote servers by transferring messages that are in the XML format.

You can access different remote procedures directly from a PHP script using standard client-server protocols, such as HyperText Transfer protocol (HTTP). After executing a remote procedure, the remote server returns a value, which can be used in other applications.

This chapter explains the XML-RPC protocol, and how to create and transfer a request to a server using XML-RPC. This chapter also explains the data types that the XML-RPC protocol supports.

Understanding XML-RPC

RPC provides a client-server framework that allows methods or procedures on the server to be remotely executed by the client in a secure and efficient manner. It uses HTTP to transfer data between the client and server. The client that invokes the procedure may be either on the same computer as the server or a different computer on the network. You can implement RPC over the Web using XML encoding and the HTTP protocol for transferring data.

The XML-RPC protocol encodes remote procedure calls in XML. It uses HTTP to transfer client requests to a server and receive the responses. XML-RPC uses an XML format to pass the method parameters and receive the returned values from the server. XML-RPC implements client requests and server responses in various languages, such as Lisp, JavaScript, C, Perl, and PHP. XML-RPC supports various data types, such as integer, string, Boolean, and double.

Introducing RPC

RPC is a programming interface that allows a program to use the services of another program available on a remote computer. The calling program transfers a message to the remote program, which executes the procedure and returns the result to the calling program.

Figure 6-1 shows the communication in a network using RPC:

click to expand: this figure shows a client-server model in which two processes communicate with each other using rpc.

Figure 6-1: Network Communication using RPC

The client process, Computer X, transfers a request to the Computer Y server process, and passes the parameters for the called procedure. The server executes the called procedure and returns the result to the client.

RPC consists of three components , which are:

An Application Programming Interface (API): Handles procedure calls on the client-side and executes client requests on the server-side.
A set of rules: Encode and decode RPC requests and responses.
A network transmission layer: Establishes communication between the client and server.

RPC provides a framework to execute the procedures on a remote computer in an efficient manner. To make a remote procedure call:

The RPC client invokes a remote procedure.
The RPC client encodes the procedure call request, along with its parameters, in a form suitable for transmission over a network transmission layer, such as HTTP.
The network transmission layer transfers the procedure call request to the RPC server in the form of packets.
The RPC server extracts the procedure name and its parameters from the request packet.
The RPC server invokes the specified procedure and obtains the result.
The RPC server encodes the result of the procedure in the form of response packets and transmits the response packets to the RPC client.
The RPC client receives the response packet, decodes it, and extracts the return value of the procedure. The RPC client can use the value that the called procedure returns in other programs.

There are two methods to implement an RPC, XML-RPC and Simple Object Access Protocol (SOAP). To create an XML-RPC call, the client issues a request to the server specifying a method name, its parameters, and the server name. The methods that you define in PHP are called XML-RPC methods and the parameters correspond to the arguments that you pass to these XML-RPC methods. The arguments can be of any data type, such as integer and Boolean.

The client packages the request in the XML format and issues an HTTP-POST request that transfers the message to the server. The HTTP-POST request informs the server that the client is ready to transfer data. The server calls the requested method and passes the parameters to this method. The method on the server returns a response, and the server packages the response into the XML format. The server returns the response to the client, which parses the XML package to retrieve the returned value. The value that a remote method returns is called server response.

SOAP is a specification for creating structured data packets that an application needs to transfer across a network. SOAP enables information exchange among the computers in a network. Unlike XML-RPC, it is not necessary that SOAP returns the HTTP status code, 200 OK, to indicate the server response. Instead, the SOAP specification uses standard HTTP error code to identify the successful processing of a client request.

Working with the XML-RPC Protocol

The XML-RPC protocol is a specification with a set of implementations that allow software running on different operating systems to make remote procedure calls. The XML-RPC request and response that you create consists of an HTTP header and an XML body. The use of the HTTP protocol ensures that XML-RPC client requests are synchronous and stateless.

A synchronous XML-RPC client request means that the server immediately responds to the client request. The XML-RPC server transfers the response on the same HTTP layer as the client request. A stateless XML-RPC client request means a client request does not preserve any information from one request to another. For example, if a client invokes a remote method on a server, receives the server response, and again invokes the same method on the server, the client requests are regarded as two different requests.

The XML-RPC client does not perform any other function until it receives the server response. A client request can invoke only a single remote method and each server response can return only a single value. The single value that the XML-RPC server returns can be either an array or a structure with multiple values. There are two types of XML-RPC servers:

Mini Web serverM: Processes an XML-RPC request.
XML-RPC listener: Assists the Web server in processing an XML-RPC request.

XML-RPC packages data for information exchange between two computers by defining the structure and format of the procedure calls and responses. XML-RPC is useful in applications where a server provides various services, such as remote procedure access to its clients . To use XML-RPC, you need to install the XML-RPC package on your computer.

Figure 6-2 shows the architecture of XML-RPC:

click to expand: this figure shows how the client encodes the procedure call as xml data and transfers the call to the server using the http protocol. the server decodes the xml encoded data. the client request and server response are in the xml format.

Figure 6-2: Architecture of XML-RPC

The data types that XML-RPC supports are:

<boolean> : Represents Boolean values, 0 or 1. The following syntax shows how to represent the <boolean> data type in XML-RPC:
```
 <value><boolean>n</boolean></value> 
```
In the above syntax, n represents a Boolean value.

<double> : Represents floating-point data. The following syntax shows how to represent floating-point data in XML-RPC:
```
 <value><double>n</double></value> 
```
In the above syntax, n denotes a floating-point value.

<int> or <i4> : Represents signed 32-bit integers. You can represent the integer data type in XML-RPC using the following syntax:
```
 <value><i4>n</i4></value> <value><int>n</int></value> 
```
In the above syntax, n denotes an integer value.

<string> : Represents the ASCII string. The following syntax shows how to represent the string data type in XML-RPC:
```
 <value>s</value> 
```
In the above syntax, s denotes a string value. The string data type is the default value. If you do not indicate the variable data type, the value inside the <value> tag is called as the string value.

<base64> : Represents binary data encoded with BASE64. The following syntax shows how to represent the binary data type in XML-RPC:
```
 <value><base64>n</base64></value> 
```
In the above syntax, n denotes a binary value.

<array> : Represents an array of data. The <array> element contains a single <data> element, which consists of many <value> elements. The following syntax shows how to represent the <array> element in XML-RPC:
```
 <value> <array> <data> <value>n</value> ...... <value>n</value> </data> </array> </value> 
```

<struct> : Represents an associative array that contains string values. It contains many <member> elements, with each element containing a <name> and a <value> element. The following syntax shows how to represent the <struct> element in XML-RPC:
```
 <value> <struct> <member> <name>n</name> <value>v</value> </member> .... <member> <name>n</name> <value>v</value> </member> </struct> </value> 
```

<dateTime.iso8601> : Represents the date and time according to the International Standard Organization (ISO) 8601 standard. The following syntax shows how to represent date and time in XML-RPC:
```
 <value><dateTime.iso8601>YYYYMMDDTHH:MM:SS</dateTime.iso8601></value> 
```

Note	An XML-RPC array data type is similar to an indexed array, and an XML-RPC struct data type is similar to an associative array. For example, the array data type is represented as $array=array ( ˜one , ˜two ), and the struct data type is represented as $struct=array ( ˜var1 = one , ˜var2 = two ).

Listing 6-1 shows the example of an XML-RPC request:

Listing 6-1: XML-RPC Client Request

 POST /myserver.php HTTP/1.0 User-Agent: Konqueror Host: 192.148.0.146 Content-Type: text/xml Content-Length: 256 <?xml version="1.0"?> <methodCall> <methodName>getCharacter</methodName> <params> <param> <value> <string>Phoenix</string> </value> </param> </params> </methodCall>

In the above listing:

The server transfers the request to the Uniform Resource Identifier (URI), /myserver.php.
The client calls the getCharacter() method on the server to obtain the number of characters in the Phoenix file.
The <methodCall> structure consists of the <methodName> element, which specifies the name of the method on the remote server that an XML-RPC client needs to call, which is the getCharacter() method. The <methodName> element is a string that can contain characters such as alphabets, numerics, underscore , period, colon , or slash.
The server interprets the <methodName> string either as the location of a file or name of a file that contains the program that a client requests for execution.

Note	The client request should contain the <params> element even if a remote method does not need any parameters.

The <methodCall> structure includes the <params> element to indicate the parameters that a remote method accepts. The <param> element represents individual arguments of a remote method. The User-Agent specifies the medium through which the client and server communicate. The Host specifies the IP address of the server. In addition to the User-Agent and Host, you should also indicate the Content-Length, which represents the accurate character length of the message.

The path that you describe after the POST method indicates the script that receives the client data. The HOST attribute, in the header of the XML-RPC client request, indicates the name of the server that services the XML-RPC request.

Note	You can download the XML-RPC package for PHP either in a zipped format or tar.gz archives from the following Web site: http://xmlrpc.usefulinc.com/php.html.

The XML-RPC server decodes and interprets the client request and provides result to the client. If no error occurs while processing a client request, the XML-RPC server returns the response. Every XML-RPC response should return the 200 OK HTTP status code even if an error occurs while processing the XML-RPC client request. The <methodResponse> structure returns a single value and so the <params> element consists of a single <param> element.

Listing 6-2 shows the example of an XML-RPC response:

Listing 6-2: XML-RPC Server Response to a Successful Client Request

 HTTP/1.0 200 OK Connection: close Server: 192.168.0.146/myserver.php Content-Type: text/xml Content-Length: 210 <?xml version="1.0"?> <methodResponse> <params> <param> <value> <string>100</string> </value> </param> </params> </methodResponse>

The above listing shows the value that the getCharacter() method returns to the XML-RPC client.

If the server does not process a client request successfully, the <fault> element replaces the <params> element in the <methodResponse> structure.

Listing 6-3 shows the XML-RPC response to an unsuccessful request:

Listing 6-3: XML-RPC Server Response to an Unsuccessful Client Request

 HTTP/1.0 200 OK Connection: close Server: 192.168.0.146/RPC Content-Type: text/xml Content-Length: 210 <?xml version="1.0"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value> <int>x</int> </value> </member> <member> <name>faultString</name> <value> <string>No characters in the file</string> </value> </member> </struct> </value> </fault> </methodResponse>

In the above listing:

The <fault> element replaces the <params> element, which appears in the server response to a successful client request.
The <fault> element contains the x fault code along with the fault string that describes the type of fault. The fault string indicates that there are no characters in the Phoenix file.
The <struct> element contains two elements, faultCode and faultString.
- The faultCode element is a numeric value corresponding to a fault.
- The faultString element is a string that contains the text description of the fault.

Note	The <methodResponse> structure cannot simultaneously include the <params> and <fault> elements.

Extending the XML-RPC Protocol

Implementing XML-RPC in PHP provides the introspection feature. The introspection feature lists and describes the services that an XML-RPC server provides. It provides a way to query methods and obtain the description of methods from the server. PHP XML-RPC provides the following introspection features:

system.listMethods() : Generates a list of methods available with the XML-RPC server.
system.describeMethods(): Describes the server methods. The description includes the expected arguments for the method, method return type, and optional arguments for the method.
system.methodHelp() : Generates documentation for a particular method. The system.methodHelp() method accepts the name of a method that the XML-RPC server implements as its argument and returns a string that describes the use of that method.
system.methodSignature() : Returns the signature for a particular method. The signature describes the data type of the parameters that a client should pass to a method. It also indicates the return type for a method.

In addition to features that the XML-RPC protocol supports, the protocol can support features, such as an asynchronous client request and authentication of Web services. The three extensions of XML-RPC protocol are:

Asynchronous protocol for XML-RPC
State- preserving protocol for XML-RPC
A protocol with authentication for XML-RPC

In the asynchronous XML-RPC protocol, the server does not immediately transfer the response to a client request. The server transfers the response to the client at a time other than the time when the client makes a request. For implementing the asynchronous XML-RPC protocol, both the XML-RPC client and server process should be able to perform the functions of each other. This means that the client process can perform the functions of the server process and the server process can perform the functions of the client process. The client and server processes should contain the code for handling asynchronous responses.

To create a system that uses the asynchronous XML-RPC protocol, the server process should return a unique identifier. To communicate using the asynchronous XML-RPC protocol:

The client makes a request to the server.
The server returns an ID for the request without processing it.
The client receives the ID and continues its current operation.
The server processes the client request and creates a result container.
The server makes a call to the client by passing the ID and the result of the client request.
The client receives the response of the client request.
The client processes the response.

The XML-RPC protocol is stateless and does not preserve any information from one client request to another. However, for applications, such as Web-based shopping carts, it is necessary to preserve the server state for use in another client request. For example, a client request creates a particular method on a server and another client request requires a change in the created method. In such situations, it is necessary to preserve the server state. To create subsequent requests that utilize the server states, the client uses the identifiers held either in cookies or in the Uniform Resource Locator (URL) of the page.

You can implement a state preserving system in XML-RPC by representing the first argument of all the remote procedure calls as a session identifier. XML-RPC keeps track of the client requests, and uses the information of an earlier request in the consequent request.

The authentication protocol for XML-RPC ensures that the message content is from an authorized client. As a result, the message cannot be modified during transfer through the HTTP transport layer. The authentication protocol is based on Message Authentication Code (MAC), which is a keyed form of the request message. This means that the client attaches a secret code to the request message.

For many-to-many client/server relationships, it is not possible to maintain databases on each server. As a result, both the client and server maintain keys with a keyserver that authenticates the clients to the servers. If your Web server supports HTTP, the client can invoke a remote method on the server by supplying a user name and password that are validated by the server.

Using XML-RPC for Web Services

A Web service is an application that runs on a Web server and enables the client programs to call remote procedures using the HTTP transport layer. The process of data exchange is similar in Web services and Web browsers. The Web browser transfers a request to a Web site in the HTML form and obtains a Web page in response. A Web service uses the XML format while a browser uses the HTML format to transfer data.

A Web service packages a collection of functions as a single entity, and publishes these functions over the Web to be used by other programs.

A Web service contains three components: service provider, service discovery agency, and service requestor . The service requester requests the service provider for the execution of a Web service. The service requester searches the description through the discovery agency and uses the service description to bind with the service provider to interact with the Web service. The service provider processes a Web service request, provides the Web service description, and publishes it to a requester or discovery agency. The service discovery agency publishes a Web service description to multiple service registries.

Figure 6-3 shows the Web service architecture:

click to expand: this figure shows the web service architecture where the service provider and service requester interact based on the web service description that the service provider publishes to a discovery agency.

Figure 6-3: The Web Service Architecture

The components of a Web service interact to perform the following functions:

Define the interface and invocation methods of a Web service.
Publish the Web service to the intranet or Internet storage locations so that the end users can easily locate the service.
Locate a Web service.
Invoke a Web service for use by end users.

A Web service has the following advantages:

Provides interoperability that helps to execute Web services regardless of the platform used.
Permits just-in-time integration by dynamically locating and invoking the Web service.
Allows a change in either a Web service or the application that uses it, without affecting the other components.

XML-RPC helps to access Web services for many end users. A Web service executes procedures available on a remote computer from another computer. It provides interoperability among applications running on different computers. For example, there are paid Web services, where you need to pay a prescribed fee for information exchange. An application can access a Web service over the Internet using standard Web protocols, such as HTTP. A Web service is heterogeneous because it allows communication between a client and server running on different platforms.

The XML-RPC protocol acts as a middleware between Web clients and remote Web services. XML-RPC accepts client requests, translates the request into an XML format, and transfers it using the HTTP protocol to access the remote Web service.

Figure 6-4 shows how to access a Web service using the XML-RPC protocol:

click to expand: this figure shows how the xml-rpc protocol acts as a middleware to translate the web client request to an xml format and transfer the request to access the remote web service using the http protocol.

Figure 6-4: Accessing a Web Service Using the XML-RPC Protocol