Code First Approach of Developing Services with WSF/PHP 2.0

WSF/PHP comes with many new features + feature enhancements including improvments for WSDL Generation. WSDL Generation is a core module of the WSF/PHP which allows developers to use 'Code First Approach' to develop web services.

I have blogged about existing features + new features avaialble in the WSF/PHP supporting the code first approach of developing services. If you prefer this approach you will find this post really helpful.

WSF/PHP WSDL Generation 2 Minutes Introduction

If you want a quick look at how to generate a WSDL from a PHP Script Read my blog on WSF/PHP WSDL Generation 2 Minutes Introduction

WSDL Generation with arrays

Currently WSF/PHP generates WSDL using the annotation mechanism. But this works only if you hard code the annotation in your script page. How if your operation parameters and operations change dependingon the user configuration. In fact that happened when we were providing Data Service Library. There we needed to generate the WSDL according the data base schema information, which can be configured by the library user.

So we came up with a mechanism to describe the service operation and operation parameters using arrays in addition to the annotation API already shipping with WSF/PHP.

You can visit here, for complete demonstration on the array based annotation API which is to going to be part of the WSF/PHP next release.

WSDL Generation with and without $classmap option

The $classmap is an option you can provide to the WSService constructor to tells the WSF/PHP engine that how you map the xml elements to PHP classes in your program.

When you provide classmap option, your service function declration should be such that it input the request object and output the response object.

When you don't provide classmap option, you will have a service function declration with set of input fields as input parameters. (Note that in both cases the response can be either an array or response, only the request parameter set is different from each other in two cases)

You can see how the WSDL is genererting for both above cases, which will also demonstrate the different between the service fuction declarations.

1. When the $classmap is provided, http://labs.wso2.org/wsf/php/php2wsdltool.php?example=Example3
The function declration is

/**
* echoValue function
* @param object Foo $echoString echoString description
* @return object FooResponse $echoStringResponse
*/
function echoValue($echoString){
}

2. When the $classmap is not provided, http://labs.wso2.org/wsf/php/php2wsdltool.php?example=Example4
The function declration is
/**
* echoValue function
* @param array of object Foo $param1 param1 description
* @param string $param2
* @return array of object Boo $ret_value
*/
function echoValue($param1, $param2){
}

You can find more details at here, http://wso2.org/project/wsf/php/1.3.2/docs/wsdl_generation_api.html

wsdl2php and php2wsdl are now online

If you have just heard wsdl2php tool and ?wsdl (wsdl generation) features in wsf/php, now you have a chance to check how they work, online at http://labs.wso2.org/wsf/php (Note the right side box)

In wsdl2php tool you can input the wsdl location url and generate the relevant php code (server side or client side as your preference).

In php2wsdl tool you are given text box to input your wsf/php service code. If you are not familiar of coding with wsf/php, you can start with an example (there are 6 difference samples), and edit them as your requirement.

Hope you will find this really useful.

WSDL Generation with WSF/PHP - Arrays and Complex types

When you are working on code first approach you want to derive the contract WSDL from the code that you already have for the Web Service.

If you may have worked on Java or .NET Web Services you already familiarized with this approach. PHP developers are also provided the opportunity to work on this approach with WSF/PHP. You only need to give a simple introduction for your service operations and their parameter types as annotations, and you will get the WSDL generated in a flash.

Here is how you will put the annotations for a simple operation like add.

<?php

/**
* operation add
* @param int $x operand1 <- This is the PHP type
* maps to xs:int <- This is the schema type
* @param int $y operand2 <- This is the PHP type
* maps to xs:int <- This is the schema type
* @return int $result
*/
function add($x, $y)

{
   return array("result" => $x + $y);

}

$operations = array("add" => "add");
$opParams = array("add" => "MIXED");


$svr = new WSService(array("operations" => $operations,
                    "opParams" => $opParams,
                    "serviceName" => "Calculator"));


$svr->reply();

?>
 

Here just examine how the operation parameters are described. If this is not clear you can have a look at the wsdl generation manual[http://wso2.org/project/wsf/php/1.2.0/docs/wsdl_generation_api.html]. It describe the annotation format in a simple fashion.

Anyway in WSF/PHP 1.2.0 you didn't have a way to specify when the input/output parameters are arrays. But in the upcomming 1.2.1 release you will get this facility.

For an example you can add an operation to add vectors like this,

/**
* operation addVectors
* @param array of int $x operand1 <- This is the PHP type
* maps to xs:int <- This is the schema type
* @param array of int $y operand2 <- This is the PHP type
* maps to xs:int <- This is the schema type
* @return array of int $result
* maps to xs:int <- This is the schema type
*/
function addVectors($x, $y)
{

   $result = array();
   for($i = 0; $i < count($x); $i ++)

   {
       $result[$i] = $x[$i] + $y[$i];
   }

   return array("result" => $result);
}
 

NOTE: you should update the $operations and $opParams with the new operation.

Note the change in annotation notation, you have add a prefix called 'array of' (just 'array' is enough) and you will have the elements maxOccurs="unbounded" in the WSDL means you are having arrays as input and output parameters in your service operation.

How about providing complex types as input and output parameters. That also will available in the WSF/PHP 1.2.1 release.

For an example say you want to add matrices. Here is how your code will look like.

/**
* operation addMatrices
* I have considered matrix as an array of Rows, which in tern array of columns
* @param array of object Row $x operand1 <- This is the PHP type
* maps to non xs:type <- This is required
* @param array of object Row $y operand2 <- This is the PHP type
* maps to non xs:type
* @return array of object Row $result
* maps to non xs:type
*/
function addMetrices($x, $y)
{

   $result = array();
   for($i = 0; $i < count($x); $i ++)

   {
       $row1 = $x[$i];
       $row2 = $y[$i];
       $result[$i] = new Row();
       $result[$i]->cols = array();
       for($j = 0; $j < count($row1->cols); $j ++)

       {
           $result[$i]-> cols[$j] = $row1[$j] + $row2[$j];
       }

   }
   return array("result" => $result);
}


/**
* @namespace http://my.org/test/calculator/demo
*/
class Row
{
   /**
    * @property array of int cols columns
    * maps to xs:int
    */
   public $cols;
}
 

NOTE: you should update the $operations and $opParams with the new operation.

Note that you only have to put 'object class_name' to declare that that the parameter is expected to have that PHP class type.

WSF/PHP 1.2.1 on the way

After a month of time, WSF/PHP is preparing for its 1.2.1 patch release. Sanjaya have uploaded the artifacts here for RC1. After doing some heavy tests, the release would be happened early next week.

One of the key feature of this release is improved WSDL mode and WSDL generation support.

In 1.2.0 we had support for simple WSDL generation like this.

<?php

/**
* addUser
* @param string $name here string is for php type
* this maps to xs:string (this is really optional declaration)
* @param int $age the age
* @return int $status
*/
function addUser($name, $age)
{

/* some logic add the user */
return 1;
}

/* map of service operation to php function */
$operations = array("addUser"=> "addUser");


/* this is required in the wsdl generation */
$opParams = array("addUser"=>"MIXED");

$service = new WSService(array("operations"=> $operations,
                       "opParams"=> $opParams,
                       "serviceName" => "User"));


$service->reply();

?>

There, the annotations are used to provide meta data about the Service, input and output parameter types.
If you are going to use the new release you would be able to improve the above code to more organized way like one in the following.

<?php

/**
* addUser
* @param object User $user : note the "object User" as the php type.
* @return int $status
*/
function addUser($user)
{
/* some logic add the user */

return 1;
}

/**
* @namespace http://im.me/types the namespace
*/
class User
{
/**
 * @property string $name
 * schema type xs:string - this is still optional
 */

public $name;
/**
 * @property int $name
 * xs:int
 */
public $age;
}

$clasmap = array("User"=> "User");

/* map of service operation to php function */

$operations = array("addUser"=> "addUser");

/* this is required in the wsdl generation */
$opParams = array("addUser"=>"MIXED");


$service = new WSService(array("operations"=> $operations,
                        "opParams"=> $opParams,
     "classmap"=> $classmap,

                        /* the serviceName can provided as an option */

                        "serviceName" => "User"));

$service->reply();


?>

There we use class "User" to declare a schema type in the WSDL. So if you want to add method like getUsers you can share this type with the current addUser method. Here is how you would define getUsers method with correct annotations. Hopefully you should add this method to "operations" and "opParams" options as well.

/**
* @param string $condition
* @return array of object User $users : note the array of is prefixed
* to the php type
*/
function getUsers($condition)
{
 $user1 = new User();
 $user1->name = "Hiro";
 $user1->age =23;


 $user2 = new User();
 $user2->name = "Clair";
 $user2->age = "14";


 return array("users" => array($user1, $user2));

}

This illustrate how you should extract the request and build the response in your logic when there are arrays and class types in your service operations.

Well how you would write a client for this operations. Here is a sample client that use simple arrays to build requests and return response. Similarly if you set "classmap" option to the WSClient you would instead build the requests and extract responses from PHP class objects..

<?php
$client = new WSClient(array("wsdl"=>"http://localhost/mails/06_blog/MuchNewService.php?wsdl"));


$proxy = $client->getProxy();

//add user operation
$res = $proxy->addUser(array("user"=>

                      array("name" => "cyler", "age" => 28)));

print_r($res);

//getUsers operation
$res = $proxy->getUsers(array("conditions" => "none"));

print_r($res);
?>

Hope you all will enjoy this new set of features..