5 Facts About WS-Addressing Action in WSF/PHP

WS-Addressing Action is used by web services to dispatch the operation for an incoming request SOAP message. This blog "5 Facts About WS-Addressing Action" present you some facts about WSF/PHP API for WS-Addressing.

ScreenCast - How to Consume a Web Service Using WSF/PHP

You can watch a Screencast on How to Consume a Web Service Using WSF/PHP from WSO2 Oxygent Tank (wso2.org) developer portal

DEMO on a SOAP and REST Client with PHP

Amazon ECommerce service is available in both SOAP and REST forms. This guide shows you how to consume the service using either form with the help of a demo application.

Test your SSL SOAP Client with an Online Service

Do you know WSF/PHP Demo Site services are deployed as HTTPS Services as well. You can use these services to test WSClient. This post give you a little overview of this and a sample client code to call the service.

Testing https requests with WSClient

If any case you found your WSClient fails in sending https request, you can use the "https://6ec2.dyndns.org/samples/wsdl_mode/wsdl_11_service.php" service to test whether the problem is in your WSF/PHP installation or something else. What you need to do is edit the samples/wsdl_mode/wsdl_11_client.php so that your WSClient constructor have the following value.


$client = new WSClient(array("wsdl"=>"sample_wsdl_11.wsdl",
"to" => "https://6ec2.dyndns.org/samples/wsdl_mode/wsdl_11_service.php",
"CACert" => "server.crt"
));

Use the approach mentioned in this blog post to generate the above server.crt certifcate.

Then run the sample in the command prompt or shell
php wsdl_11_client.php and test whether the response comes as expected. if not you have to check the wsf/php instatllatioin steps again.

NEW WSClient option for the 1.3.0

WSF/PHP 1.3.* introduced many features specially for WSDL mode API. In addition to that it has updated WSClient a bit as well.

Here are the WSClient options you will found in 1.3.* that was not there in earlier releases.


"httpAuthUsername" - Http basic/digest authentication was added in this release, here is where you give the username to authenticate

"httpAuthPassword" - Password for Http authentication

"httpAuthType" - What type of authentication is used. The possible values are "Basic" or "Digest"

"proxyAuthUsername" - Similar to http authentication, proxy authentication too added.

"proxyAuthPassword" - Password for Proxy authentication

"proxyAuthType" - Declare whether the authentication type used is "Basic" or "Digest"

"useMTOM" - This option was already there, but possible values were only TRUE/FALSE. With this release you can give another value to this option, i.e. "swa". You can enable SOAP with Attachement with setting "useMTOM" => "swa"

For more information look at the documentation http://wso2.org/project/wsf/php/1.3.2/docs/api.html

Calling https service with WSClient

Past few days I saw several users have raised the question, how to call https services from WSClient. In order to call such kind of services, you need to have the server's Certificate Authoritys Certificate (CACert), and specify it in the construction of WSClient,

$client = new WSClient(array("to" => "https://somehost.com/somewhere/service",
"CACert" => "cert.pem"));

If for some reason you don't have the servers CACert you can use the server's certificate itself as the CACert. In order to obtain the server's certificate use the following command, (assuming you already have openssl installed)

openssl s_client -connect somehost.com:443
Note: you should change the somehost.com:443 to the servers name and port.

Then extract out the text between "-----BEGIN CERTIFICATE-----" to "-----END CERTIFICATE-----"(inclusive of those two lines too) and save them in a file (cert.pem),

This way your server will be validated and will do the service call securely.

Custom Faults in WSF/PHP

Custom faults is very much required in cases you have to report exception from your business logic. It is equal to throwing and catching exception in Java, or PHP5 except that one who throws the exception is in one side and the one who catches would be in somewhere else in a network.

WSF/PHP has bound this custom faults in to a PHP language constructs, so PHP developers will not need to worry about web service messages and their formats. Here is a simple example of how you can throw and catch custom faults.

your server side will be

function greet($name)
{
    if(is_my_enemy($name)) {

       throw new WSFault("sender", "you are not my friend");
   return "<xml>{$name}</xml>";

}

$service = new WSService(array("operations" => "greet"));

$service->reply();

You will handle the fault in the client side with this code,

$client = new WSClient(array("to" => "http://localhost/url/to/above/service.php"));
try{

   $res = $client->request($req);
}
catch(Exception $e)

{
   if($e instanceof WSFault) {
      just_report_error($e->reason);
    }

}

Where to set your options?.. in WSClient or in WSMessage?

If you are familiar with WSF/PHP web service API, you may find that you can set your options in different level in your code . For an example when you are writing a web service client, you can set the same options set in the WSClient constructor or in the WSMessage constructor.

I wrote a blog with my ideas on how to select the right place to set the options in order to have well designed and efficient web service client.

SOAP Versions with SoapClient and WSClient

With the PHP SOAP extension, you can use an option in the SoapClient constructor and set the SOAP version to be used.

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => http://test-uri/,
'soap_version' => SOAP_1_2));

The above code sets SOAP 1.2 as the SOAP version to be used. The API document does not mention the default version used in case the user does not provide 'soap_version'. If you want SOAP 1.1, then use 'soap_version' => SOAP_1_1

With the PHP Web services framework, like in the case of SoapClient, you can use the WSClient constructor options to set the SOAP version to be used.

$client = new WSClient(array("to" => http://localhost/tutorial/soap/service.php,
                            "useSOAP" => 1.1));

The above code sets SOAP 1.1 as the SOAP version to be used. As the API document mentions, the default SOAP version used is SOAP 1.2, in case the user does not provide useSOAP option.

Interestingly, "useSOAP" => FALSE can be used as well.

$client = new WSClient(array("to" => http://localhost/tutorial/soap/service.php,


"useSOAP" => FALSE));

This means, instead of sending a SOAP message, send the payload given to the client as Plain Old XML. You can consider this to be a form of REST invocation.

Tracing SOAP Messages

With WSO2 Web services framework for PHP, you can trace the SOAP messages that are sent and received by the client.

The Web services client class, WSClient has two methods for this, 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.

 

$response = $client->request($reqestPayloadString);

printf("<br/> Request = %s </br>", htmlspecialchars($client->getLastRequest()));

printf("<br/> Response = %s </br>", htmlspecialchars($client->getLastResponse()));

 

The above code fragment would display the request and the 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.

The Best Practices of using WSClient

If you are accessing Webservice in your application, the best practice is to delegate your Webservice accessing aspects to a separate class. This way you can hide the Webservice consumer layer from the rest of the application.

When you are using WSClient in WSO2 Web Service Framework for PHP, you can do this by defining a separate class which extend the WSClient. For an example think about a simple Webservice for ScoreBoard which gives the total score of a Cricket match. Then you will write a PHP class which completely interact with the Service.

  1 <?php
2
3 class ScoreBoardClient extends WSClient
4 {
5     // Constructor of the new Client
6     public function __construct() {
7         parent::__construct(array( "to" => "scoreboard.sports.org"));
8     }
9
10     // The service operation of getting Total Score
11     // You can provide the match number and the team name
12     public function getTotalScore($match_no, $team) {
13
14         $xml = <<< XML
15             <GetTotalScore>
16                 <match>{$match_no}</match>
17                 <team>{$team}</team>
18             </GetTotalScore>
19 XML;
20         try
21         {
22             $res = $this->request($xml);
23         }
24         catch(Exception $e)
25         {
26             // Handle the exception..
27             return -1;
28         }
29         // For the clarity I ignore the response xml processing part
30         return $res->str;
31
32     }

33 }
34
35 ?>

• The PHP Class: (lines 3 -33) - The ScoreBoarClient PHP class which extends the WSClient.
• The constructor: (lines 6-8) - This calls the WSClient constructor (the parent of the ScoreBoardClient class) with options, in this case only the service endpoint. If you are intending to use WS-Security, you may initialize the service policies here.
• The Service operation wrapper (lines 12-32) - This is where you do all the Webservice accesing stuffs like building the request payload(lines 14-19), calling the remote service (lines22), and return the result to the caller.

So lets see how the application call the service using this class.

01 $my_scoreboard =  new ScoreBoardClient();
02
03 $total_score = $my_scoreboard->getTotalScore(5, "Sri Lanka");
04
05 echo "Total Score is: $total_score \n";
06 

It s simple as we are calling another local function. If you like to see more example which follow this pattern, just go to the script/wso2 directory of the WSO2 WSF/PHP distribution and observe how amazon, flickr and yahoo webservices are wrapped with PHP Classes.