Dimuthu’s Blog

1. WS-Addressing Action is used by web services to dispatch the operation for an incoming request SOAP message. It is one way of dispatching operations in WSF/PHP and it base Apach Axis2/C, other ways are SOAP action based dispatching which covers in my early blog “The Use of SOAP Action with WSF/PHP“,  Body based dispatching and URI based dispatching.
2. In WSF/PHP client, we can enable the addressing by setting the “action” field in the request WSMessage instance and setting “useWSA”=> TRUE in the WSClient instance. Here is an example.

   $requestPayloadString = <<<XML
   <ns1:echoString xmlns:ns1="http://wso2.org/wsfphp/samples">
      <text>Hello World!</text>
   </ns1:echoString>
   XML;
   
   $client = new WSClient(array("to" => "http://localhost/samples/echo_service.php",
                                "useWSA" => TRUE));
   
   $requestMessage = new WSMessage($requestPayloadString,
   	    array("action" => "http://localhost/samples/echo_service/echoString"));
   
   $responseMessage = $client->request($requestMessage);
   
   printf("Response = %s <br>", htmlspecialchars($responseMessage->str));

   If you doesn’t set “useWSA” => TRUE explicitly, the client will send the action as a SOAP action rather than a WSA Action. The above is the same example I used in demonstrating SOAP action with just the addition of “useWSA” option.

3. You can select WS-Addressing version among “submission” which .NET support by default and “1.0″, just by mention it in the “useWSA” field.
   I.e.

   “useWSA” => “submission”	Then the namespaces are having the values defined in the submission specification of WS-Addressing.
   “useWSA” => 1.0	Then the namespace are having the values defined in the WS-Addressing 1.0 spec.

4. In the option “actions” in the WSService, we can provide the action to operation map, so the service will direct the SOAP messages to the correct operation by looking at the WS-Addressing action of the SOAP message.
   Here is a sample code that use action to dispatch the operation.

   function echoStringFunc($inMessage) {
       // logic of echoString operation
   }
   
   function echoIntFunc($inMessage) {
       // logic of echoInt operation
   }
   
   // we will take echoString and echoInt as tow operations
   $operations = array("echoString" => "echoStringFunction",
                       "echoInt" => "echoIntFunction");
   
   // soap action to operation map
   $actions = array("http://localhost/samples/echo_service/echoString" => "echoString",
                    "http://localhost/samples/echo_service/echoInt" => "echoInt");
   
   // creating the service with the operations and actions set
   $service = new WSService(array("operations" => $operations,
                                  "actions" => $actions));
   
   $service->reply();

   Note that this code is same as the code I post in a previous blog “The Use of SOAP Action with WSF/PHP” which uses SOAP action to dispatch the operation. In fact WSService will adjust to dispatch SOAP messages, so if there is a SOAP action in the message, it will be dispatched using that, and if it contains WS-Addressing action, it will used to do dispatching without the need of writing a single additional line of code. Note that this same code for both “submission” and “1.0″ WS-Addressing versions.

5. In a WSDL 1.1, WS-Addressing action can be declared in the message element in the portType section.

       <wsdl:portType name="echoPortType">
           <wsdl:operation name="echoString">
               <wsdl:input message="ns0:echoStringRequest" wsaw:Action="http://localhost/samples/echo_service/echoString"/>
               <wsdl:output message="ns0:echoStringResponse" wsaw:Action="http://localhost/samples/echo_service/echoStringResponse"/>
           </wsdl:operation>
           <wsdl:operation name="echoInt">
               <wsdl:input message="ns0:echoIntRequest" wsaw:Action="http://localhost/samples/echo_service/echoInt"/>
               <wsdl:output message="ns0:echoIntResponse" wsaw:Action="http://localhost/samples/echo_service/echoIntResponse"/>
           </wsdl:operation>
       </wsdl:portType>

   When you use WSF/PHP in wsdl mode, it will pick the action declared in the WSDL and set it in the SOAP message, if you have enabled the addressing for the WSClient by setting non-null value for “useWSA” option.

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

There I have presented the steps you need to follow to consume a web service. I choose US National Digital Forecasting database Web Service as my example service to write the demo client.

This screencast contains,

1. Where to find the Service documentation + WSDL and what are the information available in there.
2. How to generate the PHP client from the WSDL using wsdlphp tool.
3. What is in the php file generated from the wsdl2php tool and how you select the required operations to invoke.
4. How to fill the input parameter for the web service operation
5. How to handle the response returned from the service.
6. Finally It shows some different ways the data that you are extracting from the service, can be presented to your user.

Last week I wrote a how to on Writing a SOAP and REST Service with PHP. It shows how to write a single script that enables the SOAP and REST web services interfaces using WSF/PHP. Today I’m going to show you how you can use WSF/PHP to write clients in both SOAP and REST form.

For that I use the Amazon Client Demo hosted in the PHP Web Services Demo Site. With this demo you can do shopping with Amazon using their web services API. It uses a php library (AmazonClient.php) that allows us to connect Amazon using SOAP or REST libraries.

You can see in the library code It is using different values for “useSOAP” argument depending on what form of messaging we like to use. Amazon SOAP service uses the SOAP 1.1 and the REST service uses the “GET” HTTP method for messaging. We can configure these details as mentioned in the following table.

array(
      "to"=>self::AMAZON_REST_ENDPOINT,
      "HTTPMethod"=>"GET",
      "useSOAP" => FALSE)

array(
      "to"=>self::AMAZON_SOAP_ENDPOINT,
      "useSOAP" => "1.1",
      "action" => "http://soap.amazon.com")

Since Amazon requires different request messages for SOAP and REST services, we have to create them separately depending on the request type. But the response returns by the service is same in both cases so we can handle it using the same code.

Here is how ItemLookup operation of the Amazon service is written within the above mentioned constrains.

    /**
     * ItemLookup
     * @param $ASIN Amaxon Item Id
     * @return associate array consist of the response parameters
     */
    public function ItemLookup($ASIN)
    {

        if($this->is_soap)
        {
             $req_payload = <<<XML
                <ItemLookup xmlns="http://webservices.amazon.com/AWSECommerceService/2007-10-29">
                    <SubscriptionId>{$this->amazon_key}</SubscriptionId>
                    <ResponseGroup>Medium</ResponseGroup>
                    <Request>
                        <ItemId>{$ASIN}</ItemId>
                        <ReviewPage>1</ReviewPage>
                    </Request>
                </ItemLookup>
XML;
        }
        else
        {
             $req_payload = <<<XML
                <ItemLookup xmlns="http://webservices.amazon.com/AWSECommerceService/2007-10-29">
                    <SubscriptionId>{$this->amazon_key}</SubscriptionId>
                    <Service>AWSECommerceService</Service>
                    <ResponseGroup>Large</ResponseGroup>
                    <Operation>ItemLookup</Operation>
                    <ItemId>{$ASIN}</ItemId>
                    <ReviewPage>1</ReviewPage>
                </ItemLookup>
XML;
        }

        $ret_message = $this->request($req_payload);

        $simplexml = new SimpleXMLElement($ret_message->str);

        $res = $simplexml;

        return $res;
    }

In WSF/PHP WDL Mode we have two APIs, first one is the class based API which we give a class object as the input parameter for the operation and expect to retrieve a class object as the response as well. The other API is the array based API. which we give an array (in fact an associated map) containing all the necessary information and returns an array filled with response information.

If you are using WSDL2PHP script you are always using the class based API. But there are situations where you can easily use array based API instead of the class based API. Here is an example.

Take the simple add operation of the following WSDL, http://labs.wso2.org/wsf/php/example.xml.

If you generated the code using wsdlphp tool (Here is the complete generated code for the above wsdl using online wsdlphp tool) You can see two classes are generated for the above operation, one for the input object and the other for the output object.

class simpleAdd {

    /**
     * @var int
     */
    public $param0;

    /**
     * @var int
     */
    public $param1;

}

class simpleAddResponse {

    /**
     * @var int
     */
    public $return;

}

So in order to invoke the service you need to create an object of the simpleAdd and set your input parameters and return the value from the simpleAddResponse object.

  $input = new simpleAdd();

  $input->param0 = 3;
  $input->parma1 = 4;

  // call the operation
  $response = $proxy->simpleAdd($input);

  // extract the return value
  echo $response->return;

But if you are using array mode for the same operation it will be something like this.

  // input as an array
  $input = array("param0" => 3, "param1" => 4);

  // call the operation
  $response = $proxy->simpleAdd($input);

  // extract out the return value from the array
  echo $response["return"];

In this approach you don’t need to declare classes at the start. So you can write the code without the support of WSDL2PHP tool. Anyway for complex scenarios it is not easy to find the keys needed to be in the input array, so it is better depend on the generated code. But you can use array based approach more productively for simple scenarios like this.

If you are behind a proxy server you need to configure your client to send the request through proxy. With WSF/PHP you can do it in two ways.

1. Setting proxy configuration in WSClient itself

You can use the ‘proxyHost’ and ‘proxyPort’ options to provide the proxy information through WSClient.

$client = new WSClient(array("to" => "http://my.external.host/service_url",
                  "proxyHost" => PROXY_HOST,
                  "proxyPort" => PROXY_PORT));

2. Use the axis2.xml

Change the axis2.xml to the following. (axis2.xml is in the wsf_c directory which is by default installed inside the php extension directory unless you specified it explicitly in your php.ini ‘wsf.home’ entry)

    <transportSender name="http" class="axis2_http_sender">
        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
      <parameter name="xml-declaration" insert="false"/>
      <!--Here is where you set the proxy host and the port-->
      <parameter name="PROXY" proxy_host="MY_PROXY_HOST" proxy_port="MY_PROXY_IP" locked="true"/>
    </transportSender>

So if you want only to use the proxy for particular clients, you can use the former approach. But if you want to use the proxy for all the clients in your system just use the later approach so you don’t need to edit each client.

WSDL2PHP makes the development of web service providers and consumers quick and easy. I wrote a 2 minutes guide on developing web services providers sometimes ago. So lets concentrate on developing web service consumers here.

Where is WSDL2PHP?

WSDL2PHP script is included in the WSF/PHP packs. You can find the wsdl2php.php script inside the ‘scripts’ directory of any source or binary package. Or you can use the online wsd2php tool hosted in WSF/PHP web services DEMO Site.

How to Run the Script?

Here is the command

/scripts/wsdl2php.php mywsdl.wsdl > myclient.php

The Code is Generated. How Can I add My Code There?

It is simple. Just search for the comment “//TODO”.
Check for an example here.

You have to write custom code for 2 occasions per operation.

1. To Provide Input Parameters
2. To Handle output parameters.

An Example?

Here is the code snippet corresponding to the simpleAdd request for our demo WSDL.

    $input = new simpleAdd();
    //TODO: fill in the class fields of $input to match your business logic

    // call the operation
    $response = $proxy->simpleAdd($input);
    //TODO: Implement business logic to consume $response, which is of type simpleAddResponse

Here is how after I filled my logic in place of TODO comments.

    $input = new simpleAdd();
    //DONE: fill in the class fields of $input to match your business logic

    //-------my code----
    $input->param0 = 2;
    $input->param1 = 3;
    //------------------

    // call the operation
    $response = $proxy->simpleAdd($input);
    //DONE: Implement business logic to consume $response, which is of type simpleAddResponse

    //--------my code-----
    echo $response->return;
    //--------------------