Using command line to debug your Web Service

You can actually run your PHP Web Service on the command line. One may wonder what the use of doing that ?

The main use case is that, you can test your service, without having to write a client. It is specially useful, if your are following the code first approach.  You can find the code for actually doing this in one of the WSF/PHP samples. It is in fact the simplest sample of all. The echo_service.php.

Lets have a look at how this becomes possible.

 WSService->reply() function takes an optional string argument . 

1. You can pass the actual XML string expected from the client to the reply function. Then, the service can be executed on the command line to see the actual executed output from an operation.

However, this would work only in cases where you using SOAP Body dispatching or WS-Addressing.

In SOAP Body dispatching case, the XML qualified name of the child element of soap body is used to identify the operation which should be invoked.

In case of WS-Addressing, the addressing action header is used.

2. Lets look at a code sample on implementing this.  This is the echo_service.php sample that comes with WSF/PHP

<?php

$requestPayloadString = <<<XML
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header/>
   <soapenv:Body>
     <ns1:echoString xmlns:ns1="http://wso2.org/wsfphp/samples">
         <text>Hello World!</text>
     </ns1:echoString>
    </soapenv:Body>
</soapenv:Envelope>
XML;

function echoFunction($inMessage) {

    $outMessage = new WSMessage($inMessage->str);

    return $outMessage;
}

$operations = array("echoString" => "echoFunction");

$service = new WSService(array("operations" => $operations));
$service->reply($requestPayloadString);

?>

I have highlighted the important code segments. Note how the Expected soap envelope string is passed to the reply() function as an argument.

3. Now you can execute this service on the command line and get the result.

php echo_service.php

Now you should see the expected output soap envelope after invoking the echoString operation.

4. You can also generate the WSDL for the service on the command line as well. Simply set the reply function argument string to "wsdl" or "wsdl2".

$service->reply("wsdl");

5. Now you can re execute the service and get the wsdl for the service on the command line.

php echo_service.php

This is a very useful feature for debugging your hand coded services  :).

Debugging PHP Web Services

One of the difficulties of doing distributed computing, is the difficulty of debugging when things are not going well. It is no exception for Web Services. Since messages are exchanged between services, clients, we have to have some mechanisms  to capture messages, view the soap messages exchanged, some known error messages etc.

Capturing Messages

One of the most well known technique in debugging web services calls is to  some tcp message capture tool to capture the messages exchanged. There are few such good tools for this task.

1. TCPMON tool from apache

             This is a very simple and easy to use tool which has very wide adoption and is quite popular among developers. You can download this tool from apache tcpmon site. 

2. SOAP UI

            This is another popular tool for debugging and developing SOAP based applications. This tool is able to generate request SOAP message for a given WSDL where you fill out the values and send a valid soap request and response. This is a very useful tool to get started with Web Services. You can download soap UI from soapui.org

3.   Ethereal

         This is another tool that is quite useful is capturing and analyzing messages. http://thud.ethereal.com/

Using debugging functions from framework

you can you framework provided functions for debugging. For example WSF/PHP provides two functions getLastRequest() and getLastResponse() on the WSClient class which returns the exchanged request and response messages. Also it provides functions to obtains the returned HTTP headers. Using these, you can also do some debugging.

Logging

Logging is another useful techniques to idenfity possible problems. You can look as the wsf_php_client.log and wsf_php_server.log files and get an idea of what went wrong. If you are not able to trace what's wrong using the logs , you can post your problem with the appropriate log messages to the forum  and get support.

Using Known Error Messages

Another useful technique is to go through the known set of error messages to locate what went wrong. In WSF/PHP, here are some of the error messages you can get.