Amazon Online Shopping with Web Service Framework for PHP

I finally managed to submit my first article for WSO2 Oxygen Tank. It is about how to do online shopping with Amazon Web Services using Web Service Framework for PHP.

There I'm demonstrating how to write a simple client library to access Amazon Web Services and how to use that library to write your own application to do online shopping with Amazon.com

There I attached the Client library code and two sample applications, one very simple php command line application and the other much improved web application. Hope this will be useful to people who are interested in working with WSF/PHP.

Select you service operation parameters..

In Web Service Framework for PHP 1.2, when you are writing a service using WSService with a WSDL, you always had to specify the type of the operation parameters to be "MIXED". But it would have been more convenient that the 'MIXED' to be default for ther service operation parameters when WSDL is specified.

So yesterday I took some minitues and change the logic so that,

1. When the WSDL is specified, the opParms would be default to "MIXED"
2. Otherwise, the opParams would be default to 'WSMESSAGE'.

So wsdl-mode code will be simplified to this..

function QueryPurchaseOrderFunction($pro_name, $quantity, $date, $orderNo) {
     // the business logic.

}

$operations = array("QueryPurchaseOrder" => "QueryPurchaseOrderFunction");

// The following line is not required

// $opParms = array("QueryPurchaseOrderFunction" => "MIXED")

$svr = new WSService(array("wsdl"=>"sample_wsdl_11.wsdl",
                         //opParams" => $opParams; // This too not required

                          "operations" => $operations));

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. For an example in order to set the endpoint you can either use the WSClient constructor like this,

new WSClient("to" => "endpoint",
        "other_options" => .. );

or you can use the WSMesasge constructor

new WSMessage("to" => "endpoint",
         "other_options" => .. );

It may seems quite unnecessary to have duplicate methods to set something like "endpoint". But there are cases this is really helpful in your application.

If you ever tried calling two web service operations from one WSClient object, you may have already found the importance of having this way.

In such a case you can set the common options in the WSClient and operation specific options in the WSMessage.

Most probably you will use the same WSClient to invoke different operation in a service. There your service endpoint is the same for all the operation. So you can set the service endpoint and additionally some other common configurations like the soap version in the WSClient constructor.

new WSClient("to" => "common_endpoint",
          "useSOAP" => 1.1 );

After that you can concentrate on message specific options. One would be "action" which is different from message to message. In addition to that common case, say you have some set of operations which need authentication and others don't need. For that you have to use user-name tokens for that particular set of operations. What you can do is setting that security policy and the security token only to that request messages.

$client->request(new WSMessage( $payload,
                     array("action" => "http://me.org/authenticating_operation",
                           "securityToken" => $securityToken,
                           "policy" => $policy)));

So I think it is clear the flexibility provided by the duplicate methods of doing the same thing. It make your code more organized and most importantly more efficient.

Resources for WSF/PHP developers

When you go to the Oxygen Tank you will find they have plenty of resources related to WSF/PHP project. But just to put references to all of them (including resources outside the Oxygen Tank) from one place, I thought to blog a list of resources, mentioning what, when and why you should pick them. Please add here, if I m missing anything.

1. WSF/PHP Manual
If you just now happened to heard about WSF/PHP, then this is the place you should go first. Even if you have some experience working with it, this is surely a place you will be regularly visiting. It will guide you from installing WSF/PHP to testing most of the features in very easy steps.
Some of the cool topics it covers are

• Quick Start Guide for both providing and consuming web services
  
• Using REST and SOAP
• Attachment with MTOM/XOP
• WS-Security with policies

2. WSF/PHP Documentation
Actually WSF/PHP Manual is a part of the WSF/PHP Documentation. In addition to the manual it contains Introduction which brief out the feature set and more importantly API Reference for WSF/PHP Classes. You will find this API reference is organized in a very structured manner with examples.

3. Articles, Tutorial & Demonstration
Oxygen Tanks provides many articles and tutorials for beginners of the PHP web Service development. And recently it is planned to add many demonstration that will guide users to do installation with slide shows. See the first one of it which present you how to install WSF/PHP with XAMPP on Windows.

4. User list mail archives
If you can't find the solution in any of above mentioned links, this is the most probable place you will find the answer. If you can not find that in there too, just don't hesitate to post it in the list. You will be able to subscribe for the list sending a mail to wsf-php-user-request@wso2.org with the subject subscribe. And there is no prohibition to check the dev mail archives of the project too.

5. Forum
If you don't like to subscribe to mailing list (in a case where you are not a regular user), then you have this place. You can check through the old forum topic or start a new topic mentioning your problem.

6. Blogs
There are several blogs that would give you new news about the WSF/PHP project. Here is some list of blogs that you may find useful.

• PHP Web Service Blog
• Samisa Abeysinghe
• Nandika Jayawardana
• Kaushalya Kapuruge
• Manjula Peiris
• Diluka Moratuwage
• Dimuthu Gamage, Yea this what you are reading right now;)

7. Search Oxygen Tank
Are you tired of finding what you want from dozens of places, go to wso2.org and search for it. By the way you can reach to an advanced search page too.

8. Search Google
You trust Google more, then go there and search. Most probably you will be directed to the Oxygen Tank, but sometime with some more accuracy.

Ok, They are the places I know, that you can find lot of resources about WSF/PHP and mostly about web services in PHP in general. Hope this post will helpful to somebody to locate these resources.

Mapping WSDL schema elements to PHP Classes

Since I talked about how you can deal with WSDLs using WSF/PHP in last two days, I thought of blogging a kind of a hidden feature of WSF/PHP related to WSDLs today.

When you are using WSF/PHP wsdl mode API in the client side, you can use classes to hold your data. That is simply you will be filling data in your class like you are creating an XML.

For an example,

<HelloWorld>
<name>Hiro</name>
</HelloWorld>

would map to the following PHP class,

class HelloWorld
{
 public $name;
}

I will take the yesterdays (and the same used in day before yesterday) WSDL to explain a full example of use of this feature..

<?php

/*
* Client.php
*/

/* Class HelloWorld maps to the following schema part
*  <xsd:element name="HelloWorld">
*      <xsd:complexType>
*          <xsd:sequence>
*              <xsd:element name="name" type="xsd:string"/>
*          </xsd:sequence>
*      </xsd:complexType>
*  </xsd:element>
*/

class HelloWorld
{
   public $name;
}

/* Class HelloWordResponse maps to the following schema part
*  <xsd:element name="HelloWorldResponse">
*      <xsd:complexType>
*          <xsd:sequence>
*              <xsd:element name="return" type="xsd:string"/>
*          </xsd:sequence>
*      </xsd:complexType>
*  </xsd:element>

*/
class HelloWorldResponse
{
   public $return;
}

/*
* Additionally you have to create the class map
* (i.e. Schema element => PHP Class Name
 */


$class_map = array("HelloWorld"=> "HelloWorld",
           "HelloWorldResponse"=> "HelloWorldResponse");



/* create the WSClient with the given WSDL and my service endpoint
  Note: Here im overwriting the endpoint declared in the WSDL */
$wsclient = new WSClient( array(
               "classmap" => $class_map,
               "wsdl" => "http://localhost/Service_wsdl.php?wsdl"));


/* we need to take the proxy object to call the wsdl operation */
$proxy = $wsclient->getProxy();

/* prepare the input */

$input = new HelloWorld();


$input->name = "Hiro";

/* Right here I'm calling the HelloWorld function with
* argument as the HelloWorld instance
* Remeber in the WSDL we had "HelloWorld"
* operation with name argument */
$ret_val = $proxy->HelloWorld($input);


/* Retrive the response. Just to recall,
* our response is an instance of HelloWorldResponse */
echo $ret_val->return."\n";

?>

Tutorial2 - Hello World Using Web Service Framework for PHP with WSDL Generation

Yesterday I blogged a tutorial on how to write a Hello World Web Service Client and Service starting from a WSDL. So in order to follow that approach (Contract first, That is starting from a WSDL. I have described these terms in details here) you have to have a WSDL. Yes there are many tools which will help you generating WSDLs. But how if you can generate the WSDL from your PHP service itself.

In fact with WSF/PHP you can get it done easily. For the simplicity I will get the example service (the HelloWorld Service) I took yesterday.

First I write the service like following.

<?php
/**
* Service.php
*/


/* See how we put doc comment for the HelloWorld function */
/**
* First whatever your introduction to the function
* @param string $name
* @return string $return
*/
function HelloWorld($name)

{
 /* Remember in the response we had 'return' element */
 return array("return"=> "welcome ".$name."!");

}

/* Map of the service opertion "HelloWorld" to php functions "HelloWorld" */
$operations = array("HelloWorld" => "HelloWorld");


/* just tell your function parameters should be in mixed format,
that is here parameter will be the string with the name in it*/
$opParams = array("HelloWorld" => "MIXED");

/* Created the WSService */

$svr = new WSService(array(/* "wsdl" => "HelloWorld.wsdl", */ // we removed this line.
                        "bindingStyle"=>"doclit", // we added this line

                        "operations" => $operations,
                        "opParams" => $opParams));

/* Reply the client */

$svr->reply();

?>

Just note the doc comment in the service operation "HelloWorld"..

/**
* First whatever your introduction to the function
* @param string $name - Whatever the name mean
* @return string $return - Something to return
*/

It explain the set of input parameters and the return value with its type. In fact this give a human reader an idea how should somebody should use this operation. But here in this particular case we have put it there just to give the WSF/PHP WSDL Generator a hint about this function (like what are the input and return types)

So put this in a Apache web root and go the following url in the localhost from a browser,

http://localhost/Service.php?wsdl
and
http://localhost/Service.php?wsdl2

You will be able to retrieve the WSDL v 1.1 and WSDL v 2 for our service. Isn't that easy.


If you followed the yesterday my blog get the same client and just change the wsdl location to the new wsdl. (That is the one just typed in the browser)

<?php

/*
* Client.php
*/

/* create the WSClient with the given WSDL and my service endpoint
  Note: Here im overwriting the endpoint declared in the WSDL */
$wsclient = new WSClient( array(
               /* Here is my WSDL */
              "wsdl" => "http://localhost/Service.php?wsdl2"));

/* we need to take the proxy object to call the wsdl operation */

$proxy = $wsclient->getProxy();

/* Right here I'm calling the HelloWorld function with argument "Hiro"
  Remeber in the WSDL we had "HelloWorld" operation with name argument */
$ret_val = $proxy->HelloWorld(array("name" => "Hiro"));


/* Retrive the response. Just to recall, response had the element 'return' */
echo $ret_val["return"]."\n";

?>

 

So you are done. You don't need any explanation of what are in the WSDL to do this tutorial. Since in this case you know what you should call since the service is designed by you and you know PHP.

But some one else (some even you don't know) who want to consume your service may not understand PHP (Say he is a really Java fan), and even though he is PHP guy you should not show your PHP service code to the unknown consumers.

That is where WSDL comes in to the play. You can give the WSDL (in fact just generated from the PHP) and let them consume the service. Surely there are many libraries and tools in Java (or any other language) which understand the WSDL and interpret it that language, so the consumer will find very easy to consume your service.