Appendix E: Implementing SOAP using SOAPx4

 Download CD Content

Simple Object Access Protocol (SOAP) is a W3C standard for exchanging information between various applications developed in different programming languages and running on various operating systems in a network. SOAPx4 is the PHP implementation of SOAP. SOAPx4 implements SOAP using the PHP server and client classes. SOAPx4 implements Web Services Description Language (WSDL) in Hypertext Pre-Processor (PHP).

This appendix explains how to implement SOAP requests and responses using SOAPx4. The appendix also explains how to create the SOAP server and SOAP client to process the requests of the clients in a distributed network.

Connecting a SOAP Client to a SOAP Server

A server accepts client requests in the form of SOAP request, and responds to the client in the form of SOAP response. The SOAP messages are transmitted in a distributed network in the form of header and body sections consisting of multiple soapval objects. You use the soapval object to specify a SOAP value. The syntax to use the soapval object is:

 $var=new soapval(name, data_type, data) 

The above syntax shows that the constructor of the soapval object accepts three parameters: name, data_type, and data. The name parameter indicates the name of the element, and the data_type parameter indicates the type of data to be stored in the element. The data parameter indicates the value of the element. The variable, $var, contains information stored in the soapval object.

The soapval and soapmsg objects create SOAP requests and SOAP responses. The soapmsg object of SOAPx4 contains a serialized message that is sent to the client and server of SOAP-based systems. The syntax to use the soapmsg object is:

 $var=new soapmsg(procedure_name, array of soapval objects) 

The above syntax shows that the constructor of the soapmsg object accepts two parameters, procedure_name and array of the soapval objects. The procedure_name parameter indicates the name of the procedure that is requested by the client, and the second parameter indicates the information to be sent to server. The $var variable indicates the complete SOAP message that is transmitted from the client to the server.

Creating a SOAP Request

You need to create a SOAP request that invokes the procedure of the SOAP server. In SOAPx4, you need to include the class.soap_client.php class to initiate the SOAP requests and invoke the required procedure.

Listing E-1 shows how to create a SOAP request using the soapval objects:

Listing E-1: Creating a SOAP Request

 <?php //Include the class definition of the php file that you can use to implement SOAP. include("class.soap_client.php");  //Initialize the constructor of the soapval object that accepts three parameters. $object=new soapval("student","string","John Williams"); //Create an object of the soapmsg object that contains data of the soapval object. $message=new soapmsg("getStudentData", array($object)); //Create a SOAP packet that contains complete message to be transmitted using the serialize() function. print $message->serialize(); ?> 

 

The above listing shows that the SOAP packet is a well- formed XML document, because it contains the envelope that indicates the encoding scheme used by the SOAP packets. The listing shows the envelope body that indicates the information to be sent.

The above listing shows that the class.soap_client.php file class is included in the SOAP request class to implement SOAP in PHP. The $object variable contains information that is passed to the procedure stored in the server class. The $message variable contains the complete SOAP information that is transmitted to the server.

Note  

You can use the serializeval() function to serialize data into XML form. The command to display the serialized value of the soapval object is:

 print $object->serializeval(); 

The serialization process of SOAP creates SOAP packets in the XML form, which contains request that is transmitted from the client to the server.

Listing E-2 shows a generated SOAP packet:

Listing E-2: The Generated SOAP Packet

 <xml version="1.0"?> <SOAP-ENV: Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsd="httpd://www.w3.org/2001/XMLSchema" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/ xmlns:si=http://soapinterop.org/xsd xmlns:ns6=http://testuri.org SOAP-ENV: encodingStyle=http://schemas.xmlsoap.org/soap/encoding/ > <SOAP-ENV:Body> <ns6:getStudentData> <student xsi:type="xsd:string">John Williams</student> </ns6:getStudentData> </SOAP-ENV-Body> </SOAP-ENV:Envelope> 

 

The above listing shows that the SOAP packet is a well-formed XML document, because it contains the envelope that indicates the encoding scheme used by the SOAP packets. The listing shows the envelope body that indicates the information to be sent.

Creating a SOAP Response

You need to create a SOAP response that transmits message to the SOAP request.

Listing E-3 shows how to create a SOAP response:

Listing E-3: Creating a SOAP Response

 <?php include("class_soap_client.php"); $object=new soapval("data","string","Age:15, Standard: 10th"); $message=new soapmsg("getStudentData", array($object)); print $msg->serialize(); ?> 

 

The above listing shows that the soapval object contains information stored in the getStudentData procedure. The $message variable contains the complete SOAP packet that is transmitted from the SOAP response to the SOAP request.

You can also serialize the response, sent to the client, using the serialize() function.

Listing E-4 shows a generated response in the form of SOAP packets:

Listing E-4: The Generated SOAP Response

 <xml version="1.0"?> <SOAP-ENV: Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsd="httpd://www.w3.org/2001/XMLSchema" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/ xmlns:si=http://soapinterop.org/xsd xmlns:ns6=http://testuri.org SOAP-ENV: encodingStyle=http://schemas.xmlsoap.org/soap/encoding/ > <SOAP-ENV:Body> <ns6:getStudentData> <data xsi:type="xsd:string">Age:15, Standard: 10th</data> </ns6:getStudentData> </SOAP-ENV-Body> </SOAP-ENV:Envelope> 

 

The above listing shows that the SOAP packet is a well-formed XML document, because it contains the envelope that indicates the encoding scheme to be used by SOAP packets. The listing also shows the envelope body that indicates the information to be sent as the SOAP response to the SOAP request.

Creating a SOAP Server

You create a server class in PHP to implement the SOAP responses. PHP provides the server class to implement SOAP response in SOAPx4. You need to include the class.soap_server.php and class.soap_client.php classes to initiate a SOAP server in SOAPx4. The add_to_map() and service() functions register the required procedures with the newly created server, and send the responses to the clients.

The add_to_map() function adds the requested procedure to the list of procedures stored in the server. This function accepts three parameters: procedure_name, array_of_parameters, and return_type. The procedure_name parameter specifies the name of the procedure that is to be registered with the server. The second parameter specifies the array of the parameters passed to the procedure. The return_type parameter specifies the type of data returned by the procedure. The syntax to use the add_to_map() function is:

 $server_object->add_to_map("procedure_name", "array_of_parameters", "return_type"); 

In the above syntax, the $server_object variable indicates the reference of the server object, which invokes the add_to_map() function to register the procedure.

The service() function processes the SOAP requests and returns the SOAP packets as a response to the client.

Listing E-5 shows how to create a SOAP server:

Listing E-5: Creating a SOAP Server

 <?php include("class.soap_client.php"); include("class.soap_server.php"); // Initialize a SOAP server. $server=new soap_server; $server->add_to_map("retrievePOP3Messages", array("SOAPStruct"), array("int"): $server->service($HTTP_RAW_POST_DATA); // The retrievePOP3Message function is a user-defined function that returns the number of messages stored in the mailbox. function retrievePOP3Messages($structure) {    $box=imap_open("{".$structure["pop_host"]."/pop3:110}", $structure["pop_user"],    $structure["pop_pass"]);    //If the connection is successfully established.    if($box)    {     //Retrieve the number of messages.     $totalMessage=imap_num_msg($box);     imap_close($box);     return $totalMessage;    }    else    {       // Generate an error.       $parameter=array("errorCode"=>"75", "errorString"=>"Connection Not Established",       "detail"=>"Not able to connect POP3 Server");       $errMsg=new soapmsg("Errror", $parameter, http://schemas.xmlsoap.org/soap/envelope/);    } } ?> 

 

In the above listing, the SOAP server establishes a connection with the mail server, POP3, and returns the number of messages stored in the mailbox. In the above code:

• The retrievePOP3Messages function is a user-defined function that takes the parameters passed by the clients.

• The imap_open() function establishes a connection with the POP3 mail server by passing three parameters: user name, password, and the host name of the mail server.

• The reference of the mail server is stored in the $box variable.

• The imap_num_msg() function retrieves the number of messages stored in the mailbox if the connection is established with the mail server.

• The imap_num_msg() function returns the value of the $totalMessage variable that contains the number of messages stored in the mailbox.

• The retrievePOP3Message() function generates an error if the connection with the mail server is not established.

Creating a SOAP Client

You need to include the class.soap_client.php class to initiate a SOAP client in SOAPx4. The SOAP client generates a SOAP request, and translates the SOAP packet returned as a response by the requested procedure.

The soapclient object lets you initiate a SOAP client with SOAPx4. The constructor of the soapclient object contains the location of the SOAP server as a parameter. The call() function of the soapclient object sends a request to the SOAP server and retrieves the SOAP packets as a response from the server.

This function accepts four parameters: procedure name, array of the soapval object, namespace, and SOAPAction parameter. The syntax to use the call() function is:

 $client_object->call(procedure_name, array_of_soapval_object, namespace, SOAPAction) 

In the above syntax, the procedure_name parameter indicates the name of the procedure to be invoked. The array_of_soapval_object parameter indicates the parameters passed by the SOAP client to the procedure. The urn: soapserver is the value for both namespace and SOAPAction parameters.

You can create a soap client code in any client-side script, such as Hypertext Markup Language (HTML) or Active Server Pages (ASP).

Listing E-6 shows how to code a SOAP client in HTML:

Listing E-6: Creating a SOAP Client

 <html> <head> <basefont face="Times New Roman"> </head> <body> <?php if(!$_POST[