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 and Troubleshooting PHP Services and Clients

Users sometimes would run into trouble at two stages 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. If the extension is correctly installed, you will get an entry for the extension, with the name wsf. And a table following the wsf  title, you would see a table with 'wsf support' 'enabled' entries. That will be followed by the table displaying hte 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 by the install guide. More often than not, the extension fails to load due to PATH problems, when 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 double check. First the php.ini entries. Often, users happen to enter setting where the file locations, such as login 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 still things are not working, you can turn to log files written by the Web services extension. Logs are written into the 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. 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.

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