WSO2 Web Services Framework for PHP 2.1.0 Released

WSO2 just released a newer version of the popular web services framework for php (WSF/PHP). It has lot of bug fixes + performance improvement.  And it now support PHP 5.3. So you can use wsf/php with the latest php version.

You can download the new release from http://wso2.org/downloads/wsf/php.

PHP Web Services: Webinar From WSO2 And Zend

WSO2 and Zend jointly present a webinar titling "PHP Web Services: Why You Should Care" on 26th of May, 2010. The webinar will mainly focus on the following aspects,
• Understand Web services development best practices
• Discuss Web service myths and pitfalls
• Learn about prominent PHP Web services extensions
• Watch a demo of building Web Services with both the Zend Framework and WSO2 Web Services Framework for PHP.

You can find more information about the webinar and the link to registration here, http://wso2.org/library/webinars/2010/05/webinar-php-web-services-you-should-care.

WSF/PHP Code First Approach: Returning an Array of String

Here is a problem that many people have asked me how to do it. "Returning an array of string" with the code first approach. The API or WSDL generation annotation guide, http://wso2.org/project/wsf/php/2.0.0/docs/wsdl_generation_api.html contain all the things required in details. Here is an example of a service that return an array of string.

<?php

/** splitMe function
 * @param string $string_to_split string to split
 * (maps to the xs:string XML schema type )
 * @return array of string $result split to array
 *(maps to the xs:double XML schema type )
 */
function splitMe($string_to_split)
{
    return array("result" => split(":", $string_to_split));

}

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

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

$svr->reply();
?>

Note that the annotation corresponding to the return value.

 * @return array of spring $result split to array

This will generate an schema with an element of maxOccurs='unbounded'. Note that you can get the wsdl from the 'serviceurl?wsdl'.

<xsd:element name="splitMeResponse">
    <xsd:complexType>
        <xsd:sequence>
            <xsd:element name="result" maxOccurs="unbounded" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:element>

Now just generate a client for this service using wsdl2php and try invoke it. You will get an array of string as the response.

    $input = new splitMe();
    $input->string_to_split = "a:b:c:d";

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

Getting the size of BLOB in MySql

If you want to store binary in database, you can use BLOB as the data type of that column. In Mysql you can use TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB depending on your space requirement. Here is an example of database table using BLOB as a column type.

CREATE TABLE BloBTest (
    id INT NOT NULL AUTO_INCREMENT,
    filename VARCHAR( 32 ) NOT NULL,
    content BLOB NOT NULL,
    PRIMARY KEY ( id )
)

Storing Data

PHP:

$filename = "myimage.png";
$filecontent = file_get_contents($filename);
$filecontent_escaped = mysql_real_escape_string($filecontent);

$sql = "INSERT INTO BloBTest(filename, content) " +
       "VALUES('$filename','$filecontent_escaped')";
mysql_query($sql, $link);

Java:

String filename = "myimage.png";
InputStream filecontent = new FileInputStream(filename);

String sql = "INSERT INTO BloBTest(filename, content) VALUES(?, ?)";

int size = filecontent.available();
PreparedStatement ps = conn.prepareStatement(sql);
ps.setString(1, filename);
ps.setBinaryStream(2, filecontent, size);
ps.executeUpdate();

Retrieving Data

PHP

$sql = "SELECT filename, content FROM BloBTest";
$result = mysql_query($sql, $link);
while ($row = mysql_fetch_assoc($result)) {

    $filename = $row["filename"];
    $content = $row["content"];
    $new_filename = "new_" . $filename;
    file_put_contents($new_filename, $content);
}

Java:

String sql = "SELECT filename, content FROM BloBTest";

PrepareStatement ps  = conn.prepareStatement(resourceContentSQL);
ResultSet result = ps.executeQuery();

if (result.next()){
    String filename = result.getString("filename");
    InputStream contentStream = result.getBinaryStream("content");
    String newFilename = "new_" + filename;
    // storing the input stream in the file

    OutputStream out=new FileOutputStream(newFilename);
    byte buf[]=new byte[1024];
    int len;
    while((len=contentStream.read(buf))>0)

    out.write(buf,0,len);
    out.close();
}

Retrieving the Size of the Blob

After you store your data as a blob, you can manipulate or query the data with some of the in-built String functions in mysql. For an example if you want to query the size of the blob you just stored, you can use OCTET_LENGTH function. Here is an example,  (this will give you the size in bytes.)

SELECT OCTET_LENGTH(content) FROM BloBTest WHERE filename='myimage.png'

.

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));

PHP Web Services with fopen ..

If you have done little bit of 'C' (at least up to the lesson 'File Handling'), you may have come up with the function 'fopen'.

In PHP you can use 'fopen' not only to open a file in your hard disk, but also to open resource over network, specially from the Internet. Simply you can emulate http, https or ftp client functionality with the fopen.

That is simply you may cheat your friends by writing a your own version of Google like this.

<h1>My Google</h1>

<?php
$fp = fopen("http://www.google.com", "r");

$google_html = fpassthru($fp);
echo $google_html;
?>

You may find out that fopen is just a http client (and load only what it asks to load), it doesn't load images, since they need some additional http request which is automatically done if you instead did this request from a browser.

I think it is clear what 'fopen' can do. Why not we use it to access 'REST' web services. Yea, it is possible. To access 'REST' web services you only need is a Http client and as I mentioned 'fopen' is a Http client.

Let me show you how to access some real web service with fopen. I take amazon web service for an example.

<?php

$query = "TEST";
$catagory = "Books";
/* Use your own amazon key,
You can get it from http://aws.amazon.com */
$amazon_key = "your_amazon_key";


$fp = fopen("http://webservices.amazon.com/onca/xml?".
              "SubscriptionId={$amazon_key}&".
              "Service=AWSECommerceService&".
              "Operation=ItemSearch&".
              "Keywords={$query}&".
              "SearchIndex={$catagory}&", "r");


$res = fpassthru($fp);

// For now I m just echoing the output as it is
echo $res;

?>

... It is really simple.

Is that only what fopen can do?. Hm! do you believe that we can do simple 'SOAP' webservices with fopen?. If you have seen lot of 'SOAP' messages, that will not be a problem to write a simple SOAP request with 'fopen'.

That is you can have a good control of your HTTP Request associating a stream context with 'fopen'. A simple SOAP request may only need few http headers and request XML wrapped with 'soap' headers as 'POST' data.
you can create a simple stream context with php standard function 'stream_context_create'.

Here is how you may use the 'fopen' with stream_context_create to do a POST http request.

<?php

$data = "Here is my POST data";

$opts = array(
'http'=>array(

'method'=>"POST",
'header'=>"User-Agent: My Own Http Client\r\n".
         "Content-length: " . strlen($data)."\r\n",
'content' => $data

)
);

$context = stream_context_create($opts);

$fp = fopen($url, 'r', false, $context);


/* you got the pointer to $fp, use any function like fgets, freed to read the buffer */
?>

So if i use 'fopen' to do a SOAP request to call the same amazon web service, it will be like this..

<?php

$query = "TEST";
$catagory = "Books";
/* Use your own amazon key,
You can get it from http://aws.amazon.com */
$amazon_key = "your_amazon_key";


$soap_msg = <<<XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
  <ItemSearch xmlns="http://webservices.amazon.com/AWSECommerceService/2007-10-29">

     <SubscriptionId>${amazon_key}</SubscriptionId>
     <Request>
        <Keywords>{$query}</Keywords>

        <SearchIndex>${catagory}</SearchIndex>
     </Request>
  </ItemSearch>
</soapenv:Body></soapenv:Envelope>

XML;

$opts = array(
'http'=>array(
'method'=>"POST",
'header'=>"User-Agent: fopen soap engine\r\n".
          "Content-Type: text/xml;charset=UTF-8\r\n".
          "SOAPAction: \"http://soap.amazon.com\"\r\n".
          "Content-length: " . strlen($soap_msg)."\r\n",
 'content' => $soap_msg

)
);

$context = stream_context_create($opts);

$fp = fopen("http://soap.amazon.com:80/onca/soap?Service=AWSECommerceService", 'r', false, $context);

$result = fpassthru($fp);

echo $resutl;

fclose($fp);


?>

Tutorial - Hello World with WSDL Mode Using Web Service Framework for PHP

Web Service Framework for PHP (WSF/PHP) allows you to write web services and clients using WSDL. In there you are not writing the XML message manually, rather you only need to provide parameters and the framework generate the xml message for you. So this is a simple tutorial which allow you to write a Hellow World service and client from a WSDL.

Here is my WSDL.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:ns1="http://org.apache.axis2/xsd"
 xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" 
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:ns0="http://MyTest"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
 targetNamespace="http://MyTest">

<wsdl:types>
<xs:schema xmlns:ns="http://MyTest"
 attributeFormDefault="qualified"
 elementFormDefault="qualified"
targetNamespace="http://MyTest">

<xs:element name="HelloWorld">
  <xs:complexType>
      <xs:sequence>
          <xs:element name="greet" type="xs:string"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>
<xs:element name="HelloWorldResponse">
  <xs:complexType>
      <xs:sequence>
          <xs:element name="return" type="xs:string"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types>
<wsdl:message name="HelloWorldRequest">

<wsdl:part name="parameters" element="ns0:HelloWorld"/>
</wsdl:message>
<wsdl:message name="HelloWorldResponse">

<wsdl:part name="parameters" element="ns0:HelloWorldResponse"/>
</wsdl:message>
<wsdl:portType name="HelloWorldPortType">

<wsdl:operation name="HelloWorld">
<wsdl:input message="ns0:HelloWorldRequest" 
wsaw:Action="urn:HelloWorld"/>

<wsdl:output message="ns0:HelloWorldResponse"
  wsaw:Action="urn:HelloWorldResponse"/>
</wsdl:operation>
</wsdl:portType>

<wsdl:binding name="HelloWorldSOAP12Binding" 
type="ns0:HelloWorldPortType">
<soap12:binding transport="http://schemas.xmlsoap.org/soap/http" 
style="document"/>

<wsdl:operation name="HelloWorld">
<soap12:operation
 soapAction="urn:HelloWorld" style="document"/>

<wsdl:input>
  <soap12:body use="literal"/>
</wsdl:input>
<wsdl:output>

  <soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>

<wsdl:service name="HelloWorld">
<wsdl:port name="HelloWorldSOAP12port_http"
binding="ns0:HelloWorldSOAP12Binding">
<soap12:address 
location="http://localhost:8080/axis2/services/HelloWorld"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>

Just don't worry about what it means, But to use this you may need a little knowledge of finding the operation name and finding the arguments that we have to set in order to generate the request XML.

First to understand what are the operations and arguments, just check the 'wsdl:portType' element.

  <wsdl:portType name="HelloWorldPortType">

<wsdl:operation name="HelloWorld">
<wsdl:input message="ns0:HelloWorldRequest" wsaw:Action="urn:HelloWorld"/>

<wsdl:output message="ns0:HelloWorldResponse" wsaw:Action="urn:HelloWorldResponse"/>
</wsdl:operation>
</wsdl:portType>

So you can see this has one operation with the name "HelloWorld" and it contains both input and output messages. Anyway this doesn't reveal the format of the message. In order to have a clue on that, you have to go one level up in the WSDL.

 <wsdl:message name="HelloWorldRequest">

<wsdl:part name="parameters" element="ns0:HelloWorld"/>
</wsdl:message>
<wsdl:message name="HelloWorldResponse">

<wsdl:part name="parameters" element="ns0:HelloWorldResponse"/>
</wsdl:message>

Oops!, you will see this again point to another upper level through the 'element' attribute. Actually It is where the schema of your message is shown. First we will check 'HelloWorld' element.

        <xs:element name="HelloWorld">
  <xs:complexType>
      <xs:sequence>
          <xs:element name="greet" type="xs:string"/>

      </xs:sequence>
  </xs:complexType>
</xs:element>

Here is the schema of your "HelloWorld" XML, I can see it validate an XML like this..

<HelloWorld xmlns="the namespace">
<greet>Hiro</greet>
</HelloWorld>

Don't worry, here you dont' need to understand the XML. just keeping in mind that we have to provide the argument 'greet' when calling HelloWorld.

The same way we will can expect the response message.

<HelloWorldResponse xmlns="the namespace">
<return>Welcome Hiro!</return>
</HelloWorldReponse>

So it is all about the explanation of the WSDL. We will go to the real steps of the tutorial

Building the Provider of the Web Service.. Here I have done explanation inline in each line.

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

/* This is where your logic is
Remeber in the WSDL we had "HelloWorld" operation with name argument */
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",
                    "operations" => $operations,
                    "opParams" => $opParams));


/* Reply the client */
$svr->reply();

?>

Then you may put that in the htdocs directory to deploy with the Apache Server. I put it that directly in the htdocs directory. So my service endpoint is
http://localhost/Service.php.

Remember you restart the Apache server after you did this..

Just go to the browser and type "http://localhost/Service.php". This will give you the list of deployed services and their operations. Confirm your service is in there.

Then start writing the PHP web service client ..

<?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(

           "wsdl" => "HelloWorld.wsdl",
           "to" => "http://localhost/Service.php"));

/* 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";

?>

It is all coding you should do. Now just go to a command line and run

php Client.php

or go to the browser and type

http://localhost/Client.php

If you retrieve exactly what the server set, You are done.

Interoperability of WSO2 WSF/PHP

Interoperability is a very much highly mentioned feature when we talk about Webservice Framework for PHP. It s proven to be inter-operable with Not only WSO2 WSF/C, WSF/Ruby or WSAS, but also with Microsoft WSF and Sun J2EE in case of MTOM, WS-Security and WS-Reliable Messaging support.

It is no doubt interoperability is a must feature for a Webservice Framework. Because the idea of the webservices itself is to provide a medium to communicate between heterogeneous environments, So whenever you want to host a web service make sure it can be accessed from a client from any environment. In that case WSF/PHP have released PHP developers from these concerns by providing the interoperability from the framework itself.

Blog for PHP Webservices

Recently WSO2 WSF/PHP developers started a blog for PHP Webservices. And I managed to post my first blog (about 'The Best Practices of using WSClient') today:)

In addition to the PHP Webservices blog, there are blogs about C Webservices and Ruby Webservices as well.

Hope these will be a great resource for developers who are hunting web services knowledge no matter what programming language they are mastered in.