PHP DevCenter
oreilly.comSafari Books Online.Conferences.

advertisement


Developing Web Services Using PHP
Pages: 1, 2, 3, 4

Creating an XML-RPC Web Service

XML-RPC is a specification and a set of implementations designed for applications to make remote procedure calls over the network. The remote procedure calls are made using HTTP as the transport and XML as the encoding.



Structure of an XML-RPC Request and Response

An XML-RPC message is an HTTP-POST request. The request body is in XML format. The request is sent to an XML-RPC server, which runs some business logic and returns a response in the form of XML. An example XML-RPC request is listed below.

POST /php/xmlrpc-server.php HTTP/1.0
User-Agent: Example Client
Host: localhost
Content-Type: text/xml
Content-length: 190

<?xml version="1.0"?>
<methodCall>
   <methodName>getCatalog</methodName>
   <params>
      <param>
         <value><string>catalog1
         </string></value>
         </param>
      </params>
   </methodCall>

The URI in the header, /php/xmlrpc-server.php specifies the server URI to which the request is sent. The HTTP version is also specified. The User-Agent and Host are required to be specified. The Content-Type is text/xml and the Content-Length specifies the content length.

The request body is in XML with root element as methodCall. The methodCall element is required to contain a sub-element methodName which specifies the name of the method to be invoked as a string. If the XML-RPC request has parameters, the methodCall element contains sub-element params. The params element contains one or more param elements. Each of the param elements contains a value element. The param value may be specified as a string, a Boolean, a four-byte signed integer, double-precision signed, floating point number, date/time, or base-64 encoded binary. The sub-element of value in which a param value is specified is different for different value types. If a type is not specified the default type is string. The sub-elements for the value types are listed in Table 3.

Table 3. Value elements

Value Type Element
ASCII String <string>
Four-byte signed integer <i4> or <int>
Boolean <boolean>
Double-precision signed or floating point number. <double>
Date/time <dateTime.iso8601>
Base-64 encoded binary. <base64>

A param value may also be of type <struct>. A <struct> element consists of <member> elements. Each <member> element contains a <name> element and a <value> element. An example of struct value is listed below.

<struct>
   <member>
      <name>catalogId</name>
      <value><string>catalog1
      </string></value>
      </member>
   <member>
      <name>journal</name>
      <value><string>IBM developerWorks
      </string></value>
      </member>
   </struct>

A value element in a member element may be of any of the param data types including struct. A param type may also be of type <array>. An <array> element consists of of a <data> element, which consists of one or more <value> elements. An example of an <array> param value is listed below.

<array>
   <data>
      <value><i4>1</i4></value>
      <value><string>IBM developerWorks
      </string></value>
      <value>XML</value>
      <value><string>Introduction to dom4j
      </string></value>
      <value><string>Deepak Vohra</string
      ></value>
      </data>
   </array>

A <value> element in a <data> element may consist of any of the data types including struct and array. The server response to an XML-RPC request is in the format of XML. An example response is listed below.

HTTP/1.1 200 OK
Connection: close
Content-Length: 190
Content-Type: text/xml
Date: 
Server: Example Server

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>Introduction 
         to SQLXML</string></value>
         </param>
      </params>
   </methodResponse>

If an error has not occurred, the server response returns "200 OK." The Connection header specifies the state of the connection after the response is completed. For non-persistent connection the Connection header value is "close." The Content-Type is text/xml. The response body is in XML format with root element as methodResponse. The methodResponse element consists of a single <params> element, which consists of a single <param> element. The <param> element contains a single <value> element.

Instead of a <params> element a methodResponse element may also consists of a single <fault> element. The <fault> element contains a <value> element, which contains a <struct> element with two <member> elements faultCode of type integer and faultString of type string. An example of a XML-RPC server response with a <<fault> element is listed below.

HTTP/1.1 200 OK
Connection: close
Content-Length: 190
Content-Type: text/xml
Date: 
Server: Example Server

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>4</int
               ></value>
               </member>
            <member>
               <name>faultString</name>
               <value><string>No such Method.
               </string></value>
               </member>
            </struct>
         </value>
      </fault>
   </methodResponse>

Creating an XML-RPC Server

The PHP XML-RPC extension is a PHP implementation of the XML-RPC specification. The XML-RPC PHP class library provides functions to create a XML-RPC server and invoke methods on the server. Some of the commonly used XML-RPC functions are discussed in Table 4.

Table 4. XML-RPC PHP functions

Function
Description
xmlrpc_server_create ()
Creates an XML-RPC server
xmlrpc_encode_request ( string method, mixed params [, array output_options] )
Generates XML for a method request or response. Returns a string or FALSE on error.
xmlrpc_encode ( mixed value )
Generates XML for a PHP variable.
xmlrpc_decode_request ( string xml, string &method [, string encoding] )
Decodes XML into PHP. Returns an array.
xmlrpc_get_type ( mixed value )
Returns XML-RPC data types, for example "struct", "int", "string", "base64" for a PHP value.
xmlrpc_set_type ( string &value, string type )
Sets xmlrpc type, base64, or datetime for a PHP string value. Returns True or False on error.
xmlrpc_server_register_method ( resource server, string method_name, string function )
Registers PHP function to a web service method. The method_name value is the same as the value of the methodName element in the XML-RPC request.
xmlrpc_server_call_method ( resource server, string xml, mixed user_data [, array output_options] )
Parses XML request and invokes method. Returns result of method call. The user_data parameter specifies any application data for the method handler function. The output_options parameter specifies a hashed array of options for generating response XML. The following options may be specified. output_type: Specifies output data type; "php" or "xml". Default data type is "xml". If output type is "php" other values are ignored. verbosity: Specifies compactness of generated message.escaping: Specifies if and how to escape some characters.version: Specifies version of XML to use. Value may be "xmlrpc", "soap 1.1" and "simple". Version may also be set to "auto", which specifies to use the version the request came in. encoding: Specifies the encoding of the data. Default is "iso-8859-1".Example value of the output_options parameter is as follows.$output_options = array( "output_type" => "xml", "verbosity" => "no_white_space", "escaping" => array("markup", "non-ascii", "non-print"), "version" => "xmlrpc", "encoding" => "utf-8" );
xmlrpc_is_fault ( array arg )
Determines if an array value represents XML-RPC fault.
xmlrpc_server_destroy ( resource server )
Destroys a server resource.

Pages: 1, 2, 3, 4

Next Pagearrow




Valuable Online Certification Training

Online Certification for Your Career
Earn a Certificate for Professional Development from the University of Illinois Office of Continuing Education upon completion of each online certificate program.

PHP/SQL Programming Certificate — The PHP/SQL Programming Certificate series is comprised of four courses covering beginning to advanced PHP programming, beginning to advanced database programming using the SQL language, database theory, and integrated Web 2.0 programming using PHP and SQL on the Unix/Linux mySQL platform.

Enroll today!


Sponsored by: