Dimuthu’s Blog

As the implementation language for a vast space of the applications through out the web, PHP still finding a proper place in the enterprise space. Can PHP go beyond the conventional web based database back-ended applications?. Can I use public data sources to help my finical decisions?. Can I use PHP to communicate with other enterprises?. Can my PHP CRMs, CMSes interact with each other?. Can I make these interactions secure and reliable?.
Yes. Certainly you can. Now PHP is enterprise ready with WSF/PHP toolkit.

In RESTful paradigm we give a piece of data ( or in other word ‘Resource’) a unique URL. And in order to manipulate data we use HTTP verbs POST/PUT (create, update), GET (read), DELETE (delete). For an example
take the scenario of manipulating Students data in a high school. Here is how each operation is mapped to a http request (URL + HTTP verb)

With the addition of all these HTTP verbs WSO2 WSF/PHP 2.0.0 become a great tool for RESTful developers. Specially with the introducing Data Services library it was so easy to make your database a REST service. I m thinking of preparing a series of application to demonstrate the power of WSF/PHP with all these new features.

This demo -RESTful School- shows how you map a URL to a peice of data. Here we use only the http “GET” method (which is the most to used in practicle data service).

Here is some description of the operations you find in there. Just check the source code for RESTful School demo to see how this is done in code level.

subjects

SELECT subjectName, subjectTeacher FROM Subjects

subjects/{name}

SELECT subjectName, subjectTeacher FROM Subjects where SubjectName = ?

students

SELECT * FROM Students

students/{name}

SELECT subjectName, marks FROM Marks m, Subjects s ".
        " where m.studentId = ? and m.subjectID = s.subjectId

SELECT * FROM Students where StudentName = ?

students/{student}/marks/{subject}

SELECT marks FROM Marks, Subjects, Students where StudentName = ?".
        " and SubjectName = ? and Marks.subjectId = Subjects.subjectId".
        " and Marks.studentID = Students.StudentId;

Earlier I wrote a blog about how to make your wordpress blog a web service using the WSF/PHP Data Services library. I will expand that post to demonstrate the use of WS-Security features with WSF/PHP.

This time it is a Tag Search service for my wordpress blog. Check the ‘Tag Search’ Data Services Demo from http://ws.dimuthu.org/. The only difference is here you are authenticated before accessing the service using the username tokens as specified in WS-Security.

Just look at the WSSecurity constructor in the Data Service Demo Code. You can observe 4 new parameters passed in to it. (In addition to the “config” and “operations” options)

• policy – This is where you specify the policy governed by the service.  Here you can either use the WS-Policy compliant policy file or just a simple PHP array that contain the required security token informations.

  $sec_array = array("useUsernameToken" => TRUE);
  $policy = new WSPolicy(array("security"=>$sec_array));

• securityToken: You specify the user parameters like how you handle the authentication and the encoding type in this option.

  $security_token = new WSSecurityToken(array("passwordCallback" => "password_callback_function",
                                         "passwordType" => "Digest"));
  
  /* callback function
   * @param string $username username of the client request
   * @return string $password password for that username
   */
  function password_callback_function($username) {
      // In the real word I should authenticate users from database.
      // for this demo I have a simple if-else block
  
      if($username == "visitor") {
          return "visitor123";
      }
  
      return "notavistor";
  }

  Note that here you specify a callback function to the security token parameter. Inside this function you retrieve the password for the user (mostly from the database) and return. WSF/PHP will authenticate the user from these information.

• useWSA : You need to set this option in order to generate the WS-Addressing parameters (like action) for your WSDL. WS-Addressing is required to run web services with WS-Security in WSF/PHP.
• actions: You should provide a map of action to service operations in order to get the WS Addressing information generated with your WSDL.

  $actions = array("http://ws.dimuthu.org/blog/getPosts" => "getPosts");

  Just have a look at how these information are rendered in the generated WSDL, http://ws.dimuthu.org/blog/WordpressTagSearchService.php?wsdl. (Note the wsaw:action attribute in the messages inside the portType element.

After you deploy the service, it is very easy to generate a client with the WSDL. If you write clients in PHP you can use the wsdl2php tool shipping with WSF/PHP.  The code for my demo client can be found in http://ws.dimuthu.org/source.php?src=tag.search.client. (There I have hard coded the username and password just for the demo purpose)

In the code first approach, WSF/PHP will generate you the WSDL from your annotated PHP code. If you are familiar with older versions of WSF/PHP you should be already familiar with the syntax used in the annotations which are more or less the same as the conventional PHP doc comment. If you are really new to WSF/PHP annotated code here are two examples.

1. Function with simple types for input and output parameters.

/**
 * add function
 * @param int $x (maps to xsd:int)
 * @param int $y (maps to xsd:int)
 * @return int $x (maps to xsd:int)
 */
 function add($x, $y) {
   return $x + $y;
 }

2. Function with PHP classes for input and output parameters

/**
 * add function
 * @param object Vector $x (maps to objects)
 * @param object Vector $y (maps to objects)
 * @return object Vector $z (maps to objects)
 */
 function add($x, $y) {
   return $x + $y;
 }

 class Vector {
    /**
     * @var array of int $numbers (maps to xs:int)
     */
    public $numbers;
 }

WSF/PHP 2.0 has introduced new PHP annotation syntax so you have more control over the generating WSDL.

• Now you can have custom namespaces for your schemas
• More control over minOccurs and maxOccurs values.
• Supporting ‘In only’ Message Exchange Pattern.
• Generating with WS-Addressing parameters if the ‘useWSA’ option is set to true.
• Fixes for empty input parameters.

So if you prefer Code First approach, WSF/PHP 2.0 will provide you an ideal platform for quick and easy development of web services.

WSDL2Java and WSDL2C tools shipped with the Axis2/Java project are used to generate Stubs(client side) and Skeletons(Server Side) respectively for Axis2/Java and Axis2/C codes. This make the development of web services and consumers more quicker and easier.

The tools come with many options allowing the user to customize the code generation. One of the such option is ‘-uw’ which used to turn on the ‘unwrapping’ mode. WSDL2Java project had this option for a long time, But it is just Today I was able to enable that option in the WSDL2C tool. So lets see how it make the code easier.

Say you have the ‘simpleAdd’ operation with the following schema,

            <xs:element name="simpleAdd">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element minOccurs="0" name="param0" type="xs:int"/>
                        <xs:element minOccurs="0" name="param1" type="xs:int"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
            <xs:element name="simpleAddResponse">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element minOccurs="0" name="return" type="xs:int"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>

When you generate the code for server side with Java using the following command, (note the option -uw which stands for ‘unwrapping’)

wsdl2java.sh -uri xxx.wsdl -u -ss -sd -uw

it gives you the following service function.

public int simpleAdd(int param0, int param1)
{
    //TODO : fill this with the necessary business logic
}

Note the input and output parameters of the function are simple types. If you don’t give the ‘-uw’ option, You will instead get a function with input and output variables as class names wrapping these simple types which is not this much straight forward.

So now the same is available with C. You can use WSDl2C tool with the same option set to generate a very simple service API.

wsdl2c.sh -uri xxx.wsdl -u -ss -sd -uw

And here is the service logic you may write, Can you think of an API simpler than this,

        /**
         * auto generated function definition signature
         * for "simpleAdd|http://ws.apache.org/axis2" operation.
         * @param env environment ( mandatory)
         * @param _param0 of the int
         * @param _param1 of the int
         *
         * @return int
         */
        int axis2_skel_UnwrappedAdder_simpleAdd(const axutil_env_t *env,
                                              int _param0,
                                              int _param1 )

        {
          return _param0 + _param1;
        }

You can find the code for complete case (wsdl, skel and stub) in the Axis2/C Jira Attachment space for the ‘unwrapping’ issue. Note that this update is only available in the nightly build and not in the release. You can download the nightly build from wso2′s axis2/java nightly build page.

I have been working for Axis2/C codegen tool for sometime now and I found lot of users who want to edit the codegen templates for a more optimized code specific to their use cases. This is mainly because codegen tool generates a very general code (For an example lot of unused variables generated for some WSDLs, but they are used in some other WSDLs) where as mostly ‘C’ people prefer to be as optimized as possible. Axis2 Java templates are more stable and not needed to customized as much as C templates, but Java developers too may find it is really useful to edit them in a case they need some customizations.

Both Axis2 C and Java tools comes with Axis2/Java project. So you may already have downloaded the latest Axis2/Java release or the Axis2/Java nightly build. As per title you can do this customization not only in the source but also in the binary pack. So I assume you have the binary pack.

Codegen tool mainly comes within two jars inside the lib directory of your Axis2/Java pack. (Here xxxx should be replaced with the particular jar version, it can be 1.4, 1.4.1 or SNAPSHOT)

• axis2-codegen-xxxx.jar – The core classes of the codegen (This is where WSDL2C and WSDL2Java classes reside)
• axis2-adb-codegen-xxxx.jar – This is the library containing the adb component of the codegen tool. ADB (Axis2 Data Binding) is the native databinding format of Axis2 which convert your xml schema to a more programmer friendly set of java classes or ‘C’ structures. The XSD2Java class comes in this jar.

Editing the Stub and Skeleton templates

When you unpack the axis2-codegen-xxxx.jar

jar xf axis2-codegen-xxxx.jar

you can find the template for Stub and Skel in org/apache/axis2/wsdl/template/c or org/apache/axis2/wsdl/template/java directories.

• Stub For C – org/apache/axis2/wsdl/template/c/StubSourceTemplate.xsl (source) and org/apache/axis2/wsdl/template/c/StubHeaderTemplate.xsl (header)
• Skeleton for C – org/apache/axis2/wsdl/template/c/SkelSourceTemplate.xsl (source) and org/apache/axis2/wsdl/template/c/SkelHeaderTemplate.xsl (header)
• Stub For Java – org/apache/axis2/wsdl/template/java/InterfaceImplementationTemplate.xsl
• Skel For Java – org/apache/axis2/wsdl/template/java/MessageReceiverTemplate.xsl (Message Reciever) and org/apache/axis2/wsdl/template/java/SkeletonTemplate.xsl (skeleton)

These templates are written is XSL. Even if you are an XSL expert, you may find little difficult to understand whole lot of codes in there. But if you really know what you need to change, you can track back the lines (may be using comment or some specific static set of code). So you don’t actually need to know any XSL to do these little customizations.

After you do the change simply pack the classes (which are in the ‘org’ directory) as the jar with the same name.

jar cf axis2-codegen-xxxx.jar org

Editing the ADB templates

You can similarly observe the axis2-adb-codegen-xxxx.jar. All the templates are in the org/apache/axis2/schema/template/ directory.

• C ADB templates – org/apache/axis2/schema/template/CADBBeanTemplateHeader.xsl (Source) and org/apache/axis2/schema/template/CADBBeanTemplateHeader.xsl (Header)
• Java ADB template – org/apache/axis2/schema/template/ADBBeanTemplate.xsl

You will find the template for the Java classes and C structures there. In C code generation if you find some variables are not used throughout your WSDLs, you can remove directly if from the templates. And some constants which are defined to allocate memory can be changed to suit to your application.

Anyway after all these notes, I have to say it is not really recommended to hack a code specific to your application. If you found a change general to all the applications you better submit the patch to the Axis2 community, so others too can use it. Otherwise whenever you do a upgrade you have to do this again on your own. But I hope these tips may be useful specially when you are working with ADB to do your own experiments.

We have been waiting for a while to do the WSF/PHP 2.0.0 release with a bundle of new features. We took time to test all the features and to make sure they are working smoothly. And it is heavily tested for the interoperability specially with .NET for WS-Security and WS-Reliable Messaging scenarios. And the newly added Data Services library will be a great tool for the PHP community to bring their LAMP/WAMP applications to the SOA platform. WSF/PHP 2.0.0 is not just a SOAP library. It is ready for the RESTful applications as well with the improved support for HTTP verbs.

Here is the list of new features introduced in this release

• Added PKCS12 Keystore Support
• Added Secure Conversation Support
• Added Replay Detection Support
• Contract First Web Services support for MTOM
• SWA ( Soap With Attachments ) Support added
• MTOM Attachment caching support added
• HTTP Chunking support added
• REST API Improved to support HTTP verbs GET,DELETE,PUT and POST
• New PHP Data Services Solution
• WS-RM 1.1 added

Have look at the WSF/PHP 2.0.0 Official Release Note for the complete feature list

WSF/PHP allows you to develop web services with both Contract First (Starting from WSDL) and Code First Approaches. From these two, Contract First approach is the most famous and most recomended way of developing a Webservice. There you need to have a WSDL to start with. I will take the http://labs.wso2.org/wsf/php/example.xml as our WSDL.

Generate The Service Code

When you download the WSF/PHP pack there is a script called ‘wsdl2php.php’ in the script directory. Open a command line and run it with the following options. Or you can use the online wsdl2php tool

php wsdl2php.php http://labs.wso2.org/wsf/php/example.xml -s

Complete The Business Logic

Complete the TODO section of the generated file. Apparently what is left to do is filling the business logic for each function corresponding to the service operations in your WSDL. You are given the hint to the input and output parameters. Here is how I fill the logic for the simpleAdd function.

function simpleAdd($input) {
    // TODO: fill in the business logic
    // NOTE: $input is of type simpleAdd
    // NOTE: should return an object of type simpleAddResponse

    $res = new simpleAddResponse();

    $res->return = $input->param0 + $input->param1;

    return $res;
}

Advanced Types? – Read Generated Hints for Class variables

So how about filling the matrix add logic. Can be it be really complex?. No, what you need to observe is there the class member variables contains not only simple types but also another Class type. There is a comment on each member variables to hint its type. So the logic for the matrix addition is simple as this,

function matrixAdd($input) {
    // TODO: fill in the business logic
    // NOTE: $input is of type matrixAdd
    // NOTE: should return an object of type matrixAddResponse

    $matrix0 = $input->param0;
    $matrix1 = $input->param1;

    $matrix2 = new Matrix();
    $matrix2->rows = array();

    if(count($matrix0->rows) == count($matrix1->rows)) { // considering only happy path

        for($i = 0; $i < count($matrix0->rows); $i ++ ) {

            $row0 = $matrix0->rows[$i];
            $row1 = $matrix1->rows[$i];

            $row2 = new MatrixRow();
            $matrix2->rows[] = $row2;
            $row2->columns = array();

            if(count($row0->columns) == count($row1->columns)) {

                for($j = 0; $j< count($row0->columns); $j ++ ) {

                    $col0 = $row0->columns[$j];
                    $col1 = $row1->columns[$j];

                    $col2 = $col0 + $col1;

                    $row2->columns[] = $col2;
                }
            }
        }
    }

    $res = new matrixAddResponse();
    $res->return = $matrix2;
    return $res;
}

We use the term DataServices for exposing a Database as a WebService. PHP DataServices library make this task easy by providing a very simple API to the developers.

The API is designed to let the service developer to provide the database configurations, input message format, output message format and the SQL query information. So reading and parsing the input SOAP message, building the response SOAP message from the queried data, serving the WSDL and providing the Database independent layer (with the help of PDO extensions) are done by the Dataserivce library.

Configurations

You give your database configurations in this format.

// database configuraitons
$config = array(
      "db" => "mysql", //your sql
      "username" => DB_USERNAME, //your username
      "password" => DB_PASSWORD, //your password
      "dbname" => "ds", //your database name
      "dbhost" => "localhost"); //your database host

Input Format

You have to declare the names and the types of the content of your input message. This is needed to generate the WSDL and invoke the database query with parameters.

// input format array(param_name => SQL_TYPE)
$inputFormat = array("customerNumber" => "INT");

Output Format

You can customize your response SOAP message by providing the names of the wrapper elements  for both the message and the rows.

// output format, plese check the API from http://wso2.org/wiki/display/wsfphp/API+for+Data+Services+Revised
$outputFormat = array("resultElement" => "Orders", //the name of the wrapper element of the message
                      "rowElement" => "Order", //the name of the wrapper element of each row
                      "elements" => array( "order-number" => "OrderNumber",
                                           "order-date" => "OrderDate",
                                           "status" => "status"));

Create the Query

The query in the PHP dataserivces term is not just the SQL query that you are familiar in accessing a database, It contains the input and output formats in addition to the actual SQL query to invoke.

// sql statment to execute
$sql="select o.OrderNumber, o.OrderDate, o.status from Customers c, Orders o where c.customerNumber=o.customerNumber and c.customerNumber=?";

// operations are consist of inputFormat (optional), outputFormat(required), sql(sql), input_mapping(optional)
$operations = array("customerOrders" =>array("inputFormat" => $inputFormat, "outputFormat" => $outputFormat, "sql" => $sql));

DataService object

Finally you create the DataService object with the provided configurations and the query information.

require_once("wso2/DataServices/DataService.php");

$my_data_service = new DataService(array("config" => $config,"operations" => $operations));

$my_data_service->reply();

Whenever you deploy a service script in WSF/PHP you can access its WSDL by adding “?wsdl” or “?wsdl2″ (for WSDL version 2.0) to the service endpoint. Anyway you may have noticed that for some services it will just list the operations with xsd:anyType as the input and output message schemes.

For an example for an operation like this,

<?php

function getInvoice($order_no) {
   //something that return an invoice for this order 
}

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

$svr = new WSService(array("operations" => $operations));

$svr->reply();
?>

This will generate you a nice WSDL but with a schema similar to this,

<xsd:element name="getInvoice">
    <xsd:complexType>
       <xsd:sequence>
           <xsd:element name="order_no" type="xsd:anyType"/>
       </xsd:sequence>
    </xsd:complexType>
</xsd:element>

This schema is not enough for get an understanding about the request, response message formats, because it uses xsd:anyType to represent a general message. In order to get more specific schema, you need to provide more details to the WSDL generator. Here is how it is done using annotations.

<?php
/**
 * @param int $orderNo Order Number
 * (maps to xsd:int)
 * @return string $invoice Invoice as a string
 * (maps to xsd:string)
 */
function getInvoice($order_no) {
   //something that return an invoice for this order 

}

$operations = array("getInvoice" => "getInvoice");
$opParams = array("getInvoice" => "MIXED"); // Have to declare parameters as MIXED

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

$svr->reply();
?>

Now check the schema. It will gives you the information specific to your request, response messages.

<xsd:schema elementFormDefault="qualified"
    targetNamespace="http://www.wso2.org/php/xsd">
    <xsd:element name="getInvoice">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="orderNo" type="xsd:int"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="getInvoiceResponse">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="invoice" type="xsd:string"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

So it is your chance to do more experiment with this feature. Check WSDL generation API for more snippets.