WSO2Con 2013 CFP Banner

PHP Web Services: After Getting Started

Discuss this article on Stack Overflow
By Samisa Abeysinghe
  • 13 Jan, 2008
  • Level:  Introductory
  • Reads: 19540

In the article titled “PHP Web Services: Getting Started”, I discussed fundamentals of WSO2 Web Services Framework for PHP and looked at writing the first service and client. In this article, I discuss more on the Web services framework for PHP.

samisa abeysinghe's picture
Samisa Abeysinghe
VP, Training
WSO2 Inc.

Applies To

WSO2 WSF/PHP 1.2.0
Environment Windows or Linux

 

WSMessage Class

phpIn a Web services invocation, there are two messages involved for two way operations. One is the request message and the other is the response message. WSMessage class in the Web services framework for PHP is used to represent these messages.

The str member variable of the WSMessage class can hold the message content, termed as payload, as an XML string.

If you are sending a request through a client, you fill in the request WSMessage instance with the XML payload and send the request. The received response payload will be stored in a WSMessage instance as an XML string and returned to client.

 

DrawObject

 

 

If you are receiving a request form a service, this received payload will be contained in a WSMessage instance. You can process the request within the function implementing the service operation being invoked, prepare the response, store it in a WSMessage instance and return that instance.

WSMessage is more useful when sending and receiving attachments than when dealing with simple messages. We will look in to leveraging WSMessage with attachments, in a future article. The following section explains how WSMessage instance can be used form clients and services, using an example.

 

Dealing with Payloads

In my previous article on getting started with PHP Web services, I spoke about getting a simple service and client working. However, these samples did not dig into the details of dealing with the payload. In other words, we just sent XML to and form client and service, but did not bother to process the payload content. In this section, I will explain how the payloads can be processed and used in computations.

Payload is the business logic specific content sent within the SOAP body of the SOAP message. Let us look into a sample where a number is given to calculate the factorial. The client sends the number and the service calculates and returns the factorial.

Here is the payload the client sends:

<getFactorial>
    <param>6</param>
</getFactorial>

Now the service needs to understand the incoming payload and pick the param to calculate the result. Here is the code for the function implementing the service operation:

  1. function getFactorial($message) {
  2.  
  3. $simplexml = new SimpleXMLElement($message->str);
  4. $value = $simplexml->param[0];
  5.  
  6. $result = factorial($value);
  7.  
  8. $responsePayloadString = <<<XML
  9.     <getFactorialResponse>
  10. <result>$result</result>
  11. </getFactorialResponse>
  12. XML;
  13.  
  14. return $responsePayloadString;
  15. }

On line 3, we create a SimpleXMLElement instance, using the incoming payload. As you can see, incoming payload is stored in the str member of the WSMessage instance $message passed to the function implementing the service operation. Also, note that the SimpleXML extension is a built in PHP extension that can be used to process XML. WSO2 WSF/PHP does not restrict the user form using any specific XML processor when dealing with XML payloads. User can choose any XML processor of his or her choice.

Line 4 access the param value within the payload. This means that the service needs to have some understanding about the format of the incoming payload in order to process it. The rest of the logic in the function implementing the operation is simple. On line 6, factorial is calculated for the incoming param value calling another function that implements the actual factorial logic. Form line 8 to 12, the response payload is prepared with the result. Finally on line 14, we return the response payload.

The response payload would look something like:

<getFactorialResponse>

        <result>720</result>

</getFactorialResponse>

The client too can process the response payload in a way similar to how it was done on server side.

  1. $response = $client->request($reqestPayloadString);
  2.  
  3. $simplexml = new SimpleXMLElement($response->str);
  4.  
  5.     echo "Result = ".$simplexml->result[0]."<br/>";


On line 3, create SimpleXMLElement instance out of the response and access the result element. Again, $response is a WSMessage instance and we access the str member containing the response XML payload as a string and pass that to the SimpleXMLElement constructor. Then we access the result element in the response payload.

Now you've learned to deal with incoming payloads both on client as well as on server side.

Note that in the getFactorial function within the service code, in line 14, you could have returned a WSMessage instance instead of returning the payload directly. That is, you could have used the following code segment when returning the respsonse message:

  1. $outMessage = new WSMessage($responsePayloadString);

  2. return $outMessage;

This basically means that the functions implementing service operations accept payload either as a SimpleXMLElement instance or as a WSMessage instance.

The complete code for the samples discussed here can be found at the end of the article as a download.

Tracing Messages

With WSO2 Web services framework for PHP, you can trace SOAP messages that are sent and received by the client. The Web services client class, WSClient, has two methods for this purpose: getLastRequest() and getLastResponse(). After calling the request() method of the client instance, you can call any of those methods to gain access to the messages.

  1. $response = $client->request($reqestPayloadString);
  2. printf("<br/> Request = %s </br>", 
    htmlspecialchars($client->getLastRequest()));
  3. printf("<br/> Response = %s </br>", 
    htmlspecialchars($client->getLastResponse()));


The above code fragment would display request and response messages that were sent and received as a result of the call to the request() method.

An example output would look something like:

Request = <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Header/><soapenv:Body><getFactorial> <param>6</param> </getFactorial></soapenv:Body></soapenv:Envelope>
Response = <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Header/><soapenv:Body><getFactorialResponse> <result>720</result> </getFactorialResponse></soapenv:Body></soapenv:Envelope>

Tracing of SOAP messages in relation to a service invocation is useful specially when troubleshooting services and clients. As an example, you can verify if the client sent a message at all or if the service sent a response at all. You can also verify the format of the outgoing payload as well as the format of the incoming payload.

 

Debugging

Users sometimes run into trouble at two points when getting the PHP Web services extension working:

First, the challenge is to get it installed. How can you check if it is working? Well, first, you can check with the phpinfo() function. Just save the following code to a PHP script, place it in the Web server's document root and access the script with the Web browser.

  1. <?php
  2.  
  3. phpinfo();
  4.  
  5. ?>

If the extension is correctly installed, you will get an entry for the extension, with the name wsf. In a table following the wsf title, you would see a table with 'wsf support' 'enabled' entries. That will be followed by the table displaying the php.ini directives for WSO2 WSF/PHP extension. If this entry is missing form the phpinfo() page, that means the extension is not properly loaded.

If the extension does not seem to appear with phpinfo(), you can double check your PATH variable to verify that the required dlls are on the PATH as mentioned in the install guide. More often than not, extension fails to load due to PATH problems where it cannot find the required libraries.

When you get it installed, the second form of problems come when you cannot seem to get the samples working. Again, there are some settings to be checked. First the php.ini entries. Often, users happen to enter settings where the file locations, such as log path, pointed to by the php.ini entries are either non existent or do not have write access. Also check if your include_path setting in the php.ini file includes the scripts folder that comes with the PHP distribution.

When all the above are correct and if things are still not working, you can turn to log files written by the Web services extension. Logs are written into a folder pointed by the wsf.log_path entry that you add to the php.ini file. If this is not set, the default location is /tmp. Note that, on Microsoft Windows, the default folder may not exist, hence you must set the wsf.log_path setting in php.ini on Windows platform. Logs related to the services are written to a file named wsf_php_server.log and client logs are written to a file named wsf_php_client.log. You can vary the level of information written to the logs by changing the wsf.log_level entry that you add to the php.ini file. I have explained the various log levels in my previous article. You can tune the log level in order to see more or less information based on your requirements. When debugging, it is advisable to set a detailed log level such as debugging (level 4), although, in production, it is advisable to set a less verbose log level such as critical errors (level 0) or errors (level 1).

In case you want to verify that the messages are sent and received by clients and services and that those messages are of the desired format, you can use SOAP message tracing techniques that I've discussed in the previous section.

Summary

In this article, I explained the purpose of WSMessage class and also showed how to deal with payloads using it. Both with the service as well as the client can access the str member of the WSMessage instance and process the incoming XML payload using an XML processor of user's choice. It is a prerequisite that the service as well as the client is aware of the format of the incoming XML payload. Usually the format of the payloads are agreed upon through a contact defined in terms of WSDL, hence it is a reasonable requirement. We will explore how to work with WSDL with WSO2 WSF/PHP in a future article.

This article also introduced SOAP message tracing techniques with the WSClient. We also discussed various debugging techniques that can be used to troubleshoot when things do not seem to work. WSO2 WSF/PHP, being a PHP extension written in C, writes its own log files to make life easy when it comes to debugging. You can tune the log level in order to see more or less information based on your requirements.

Resources

Download source code for the factorial sample.

Links

Author

Samisa Abeysinghe is a Software Architect at WSO2. He is a member of Apache Software Foundation and a project management committee member of the Apache Web services project. He is one of the pioneering members of the Apache Axis2/C project.

samisa at wso2 dot com.

AttachmentSize
wsf-php-tutorial_sample2.gif3.52 KB
payload.zip838 bytes
WSO2Con 2014 USA