Dimuthu’s Blog

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.

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

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'

.

In this case study “ PHP Data Services Extract Content from Drupal Database“, I intended to present how Data Service concepts can be applied to extract data with marketing value from  a CMS database and publish it as web services.  I used the drupal instance deployed at http://wso2.org as the CMS for the use case. And as the data service framework, I used WSF/PHP data services library, as it requires minimum changes to the existing infrastructure (the LAMP stack).

The case study also talks about how to consume the data service by any third party mashup to present textual/ graphical views of analyzed data. These mashups can be extended up to intergreate with social networks like facebook, twitter and etc to communicate back and forth a wider community and may be it can be used to track the distribution of active users using Google maps. Simply it makes easier to analyze business data + engagement with the community.

libcurl is a famous C library which can be used to transfer data through http/tcp or any custom protocols. It has a very easy to use API to make web requests programatically.

PHP has an extension that wraps the libcurl API and provide a very convenient API to PHP programmers.

Normally PHP has a lot of functions that are available in C standard libraries. For an example you have the strlen in both C and PHP that gives you the length of a string. But PHP has additional helper functions that allows programmers to manipulate strings easily. For an example you can compare strings in PHP using strcmp function as in C style. Or you can simply use “==” operator.

Similarly libcurl APi for PHP  is very similar to the C API. But it has specially made to suit for the PHP language.

Here is a C code that make a web request to my blog and print it in the console.

#include <curl/curl.h>
#include <curl/types.h>
#include <curl/easy.h>
#include <string.h>

/* function prototypes to define later */
char *do_web_request(char *url);
size_t static write_callback_func(void *buffer,
                        size_t size,
                        size_t nmemb,
                        void *userp);

/* the main function invoking */
int main()
{
    char *url = "http://dimuthu.org";
    char *content = NULL;

    content = do_web_request(url);

    printf("%s", content);
}

/* the function to return the content for a url */
char *do_web_request(char *url)
{
    /* keeps the handle to the curl object */
    CURL *curl_handle = NULL;
    /* to keep the response */
    char *response = NULL;

    /* initializing curl and setting the url */
    curl_handle = curl_easy_init();
    curl_easy_setopt(curl_handle, CURLOPT_URL, url);
    curl_easy_setopt(curl_handle, CURLOPT_HTTPGET, 1);

    /* follow locations specified by the response header */
    curl_easy_setopt(curl_handle, CURLOPT_FOLLOWLOCATION, 1);

    /* setting a callback function to return the data */
    curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, write_callback_func);

    /* passing the pointer to the response as the callback parameter */
    curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, &response);

    /* perform the request */
    curl_easy_perform(curl_handle);

    /* cleaning all curl stuff */
    curl_easy_cleanup(curl_handle);

    return response;
}

/* the function to invoke as the data recieved */
size_t static write_callback_func(void *buffer,
                        size_t size,
                        size_t nmemb,
                        void *userp)
{
    char **response_ptr =  (char**)userp;

    /* assuming the response is a string */
    *response_ptr = strndup(buffer, (size_t)(size *nmemb));

}

Lets see how simple it is with PHP.

<?php

echo do_web_request("http://dimuthu.org/");

/* the function to make the request */
function do_web_request($url)
{
    /* initializing curl */
    $curl_handle = curl_init($url);

    /* set this option the curl_exec function return the response */
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);

    /* follow the redirection */
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, 1);

    /* invoke the request */
    $response = curl_exec($curl_handle);

    /* cleanup curl stuff */
    curl_close($curl_handle);

    return $response;
}

?>

Now you can view the article I wrote titling “Introduction to PHP Data Services“. There I explain how you can design and implement Data Services in PHP using WSF/PHP Data Services Library.

This article covers,

1. Designing your Data Service API.
2. Writing the Data Service.
3. Deploying and Testing Data Service.
4. Make the Data Service available in both SOAP and RESTful form.
5. Use of WS-* features in your Data Service.

If you are thinking of adapting SOA in to your database backed PHP applications, this article will be a good starting point.

PHP is one of the famous choice, when it comes to develop a web site. As the web evolve with the emerge of web service, REST (REpresentational State Transfer) concepts, the PHP language is also adapted to the new requirements specially with the availability of new SOA (Service Oriented Architecture), REST frameworks and libraries. Anyway there were hardly any guides, references or samples that properly describe the methodologies of developing REST applications using PHP.

The book “RESTful PHP Web Services‘ by Samisa Abeysinghe certainly fill this gap. It can be used as a step by step guideline for newbies to learn the concepts and write simple RESTful PHP applications and Mashups. And even experienced developers would find this a great reference to keep nearby while working with RESTful Web Services in PHP. And it has lot of code samples, utility functions that developers can use it in their applications.

About the Author

Samisa Abeysinghe is a well recognized name in the web services world. He lead the development of Apache Axis2/C and WSO2 WSF/PHP, two famous open source web service frameworks for ‘C’ and PHP. In addition to his deep knowledge in the subject, his experience in involving with the community and the enterprise for years and working as a lecturer in universities, should have influenced a lot in writing this book.

The Arrangement and the Content

The arrangement of the book is done really well to make sure the reader can go through it in the right sequence. All the content is bundled just within 200 pages. So you don’t need to allocate a lot of time to go through the whole book. It is organized into 7 chapters and two appendixes which are mostly independent from each other.

The first chapter is completely devoted to explain the concepts of RESTful web services. It basically explains what is RESTful web service and why it is needed. And it briefly mentions about the currently available REST Frameworks for PHP.

The second chapter introduce some PHP codes that do REST web service requests and handles the XML responses using both DOM and SimpleXML APIs. And in the third chapter it shows more code samples specially about consuming real world web services like BBC, Yahoo and an earthquakes information service. Theses codes are written as mashups mostly combining two services to produce more meaningful information.

The forth chapter is about  designing and writing web service providers. Its counterpart, writing web service consumers is described in the chapter five. There it demonstrate a library system that operate using RESTful webservices. You can map this example to any system that you may like to develop to run with RESTful web services. The chapter five of the book is available as a free download, RESTful PHP Web Services – Chapter 5.

The forth and fifth chapters are not using any framework to write the sample codes on consuming and providing web services. But in the sixth chapter it shows the use of Zend framework to do write them. There it rewrites the same example (The RESTful library system) in MVC (Model -View – Controller) approach using the functionalities of Zend framework. (In fact the View in the service is omitted).

The seventh chapter is about debugging web services. Debugging is a much needed step in any software development cycle. So if you are a newbie, you should read this chapter before start writing any of your own code. This introduces tools and methodologies to make your debugging easy and effective.

The book contains two appendixes. They are too really useful as the chapters of the book. In the first appendix it explains another REST web service framework, WSO2 Web Services Framework for PHP (WSF/PHP). To demonstrate it uses, some selected functionalities of the example library system (that is mentioned in chapters 4, 5, 6) is re-implemented using WSF/PHP. And it shows you how you can convert this RESTful system to a SOAP system in a minute. The second appendix provides you a code of a class (RESTClient), that you can use in consuming web services very effectively.

Recommended Readers

This book assume you have some knowledge in PHP. But it doesn’t require you to know anything related to web services, REST or XML. As you read the first few chapters, you will have a good understanding on the concepts and the basic applications of REST and XML using PHP. And the later chapters will guide to get deeper knowledge in writing complex and real world applications.

If you are a professional developer, you can skip the introduction chapters and jump directly to where you need to refer. For an example, if you use this book as a reference in designing and developing RESTful web service providers, you can directly read the chapter4 – Resource Oriented Services, chapter6- Resource Oriented Clients and Services with Zend Framework and probably the chapter 7 – Debugging Web Services.

This book contains the same example system (the library system) written in three different approaches, first without using any framework support, second using the Zend Framework, third using WSF/PHP. Each of them has its own pros and cons. So if you want to determine the approach more suitable to your requirements, or thinking of migrating from one to another, this book will be an ideal resource for you.

As you may have already noticed, this book contains lot of code samples. All the concepts are followed by simple code samples that explain the concept. In appendix it gives you a complete code for RESTClient class that you can use to call any REST service. Apart from the code of the example library system written using different frameworks, it has lot of codes for calling public web service APIs. And the explanation of the code is also done really well.

So it is clear this book is more targetting readers who like to implement PHP RESTful Systems in practice. And it covers enough concepts that you needed to know in writing practicle applications. So this book can take you from the zero knowlege to a deeper knowlege of RESTful PHP Web Services.

LAMP (Linux + Apache + Mysql + PHP) stack powers many servers in the Internet today. For a LAMP  server, PostgreSQL could be the first alternative to Mysql. Similar to PHP + MySQL,  PHP + PostgreSQL too can be easily used in to host data services. Here are the steps to do it.

1. If you already don’t have Apache + PHP + PostgreSQL download them from the following locations. Apache – http://httpd.apache.org/download.cgi, PHP – http://php.net and PostgreSQL – http://www.postgresql.org/download/
2. You have to enable the PHP pdo_pgsql, pdo and pgsql plugins. Read here for the instructions to setup these libraries. (For an example: if you are windows you have to set the system ‘PATH’ variable to the <postgresql_installed_dir>/bin directory.
3. If you already don’t have WSF/PHP, download and install it according to the guidelines provided in wsf/php installation guide.NOTE: You can check pdo_pgsql and wsf/php has properly installed with the help of phpinfo() function.
4. Now lets start with creating a sample Database table. For this example I created a database called ‘workshop’, schema called ‘workshop’ and inside there the table ‘Employee’ with the following schema.
   

   Column Name	Column Type
   employId	integer
   name	character varying
   email	character varying
   jobTitle	character varying
   project	character varying

   Note: You can use phpPgAdmin (web based) or pgAdmin III to create tables from GUI

5. Then you can write a small php script to expose the data in the above table as a web service.

   <?php
   
   //Including the Data Services library
   require_once("wso2/DataServices/DataService.php");
   
   // Including the connection information (i.e. PGSQUL USERNAME
   // and PGSQL_PASSWORD) for my PGSQL Connection
   require_once("constants.php");
   
   // database configurations
   $config = array(
   		"db" => "pgsql",
   		"username" => PGSQL_USERNAME,
   		"password" => PGSQL_PASSWORD,
   		"dbname" => "workshop",
   		"dbhost" => "localhost"
   		);
   
   $output_format = array(
                       "resultElement" => "employees",
                       "rowElement" => "employee",
                       "elements" => array(
   			    "id" => "employeeId",
                               "name" => "name",
                               "email" => "email",
                               "jobTitle" => "jobTitle",
                               "project" => "project"));
   
   $sql = "SELECT * FROM workshop.Employees";
   
   $get_employees_op = array("outputFormat" => $output_format, "sql" => $sql);
   
   $get_employees_url = array("HTTPMethod" => "GET", "RESTLocation" => "employees");
   
   // list of operations
   $operations = array(
                   "getEmployees" => $get_employees_op,
                   );
   
   // list of rest url mappping (operation => url)
   $restmap = array(
                   "getEmployees" => $get_employees_url,
                   );
   
   // creating DSService and reply
   $service = new DataService(array(
            "config" => $config,
            "operations" => $operations, "RESTMapping"=>$restmap));
   $service->reply();

   ?>

6. We just wrote a PostgreSQL Data Services that provides its service as both REST and SOAP form. To deploy this service, We just need to copy this in to the web root directory. And the web URL for the script will be the endpoint to the web service.
7. We can test the service either by calling its SOAP interface, which we may need to write a small SOAP client or by calling its REST interface, which only need a GET request from the browser. Say my script name is “my_dataservice.php” and I’ve put it in the web root directory, then the URL to call the REST interface of the service is

   http://localhost/my_dataservice.php/employees

WSDL Generation for PostgreSQL Data Service
You can get the WSDL for the service from the URL formed adding the suffix “?wsdl” (or “?wsdl2″ to wsdl v2.0) to the service URL,

http://localhost/my_dataservice.php?wsdl

Here all the schema data types are shown as xsd:anyType, which may not be the behavior that you want. In fact you can provide the schema data types to the fields from the code itself. Lets change the $outputFormat variable to provide the schema information as well using the following code snip.

$output_format = array(
                    "resultElement" => "employees",
                    "rowElement" => "employee",
                    "elements" => array(
			    "id" => array("column" => "employeeId",
		    			  "xsdType" => "xsd:int"),
			    "name" => array("column" => "name",
		    			  "xsdType" => "xsd:string"),
			    "email" => array("column" => "email",
		    			  "xsdType" => "xsd:string"),
			    "jobTitle" => array("column" => "jobTitle",
		    			  "xsdType" => "xsd:string"),
			    "project" => array("column" => "project",
		    			  "xsdType" => "xsd:string")));

Note that you provide the xsd type for each field explicitly. In fact this change is not needed for mysql pdo extension since it allows identifying field types programatically. Since this feature is not available in all the other pdo drivers, we have to explicitly give xsd type information for them.

If you wan to provide data services with SQLite or MSSQL, You can check my other posts on MSSQL(Microsoft SQL) Data Services In PHP and Data Services with SQLite in PHP.

With WSF/PHP Data Service library, you can convert a SQL query to a Data Service very easily in few steps.

1. Decide your SQL query first, For the query you may require some input parameters, and you have to decide what should be returned by the query, Say your query is

   $sql_query = "SELECT name, age, email FROM users where country = ?";

   Then the “country” is our input parameter and the name, age, email are our return values.

2. Define the input Format. For the above query it will be something like,

   $inputFormat = array("country" => "INT");

3. Define the output format. We are giving the name “Users” for the out most wrapper element and the name “user” for the wrapper element of each user. Here is how we define it,

   $outputFormat = array("resultElement" => "users",
                   "rowElement" => "user",
                   "elements" => array(
                               "name" => "name",
                               "age" => "age",
                               "email" => "email"));

   For this output format, our expected result payload would be like,

   <users>
     <user>
        <name>xxx</name>
        <age>23</age>
        <email>xxx@xxx.xx</email>
     </user>
     <user>
        <name>yyy</name>
        <age>23</age>
        <email>yyy@yyy.yy</email>
     </user>
     ....
   </users>

4. Define your operation using the sql query, input and output formats.

   $operations = array("getUsersByCountry" => array(
                                 "inputFormat" => $inputFormat,
                                 "sql" => $sql_query,
                                 "outputFormat" => $outputFormat));

5. Define your database configuration in an array like this,

   $config = array(
       "db" => "mysql", // your db engine
       "username" => "myname", // name & password for the db server
       "password" => "mypasswd",
       "dbname" => "db", // the db
       "dbhost" => "localhost");

6. Create a DataService instance using the database configuration and the operations we just created. And call DataServices reply method.

   $ds_service = new DataService(array(
                  "config" => $config,
                  "operations" => $operations));
   
   $ds_service->reply();

That is it. You just exposed your query as a web service. The PHP script URL will be the endpoint URL for the web service.

In SOAP 1.1, the SOAP action is mentioned as a compulsory HTTP header. In practice it was used to identify the operation for a given request which we identify by the term ‘dispatching operations’.
As of SOAP 1.2, the SOAP action field became optional, and it was part of the content type header.

In WSF/PHP, you can use the “action” property of WSMessage to set the SOAP action in a request SOAP message.

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

$requestMessage = new WSMessage($requestPayloadString,
	    array("action" => "http://localhost/samples/echo_service/echoString"));

$responseMessage = $client->request($requestMessage);

printf("Response = %s <br>", htmlspecialchars($responseMessage->str));

WSF/PHP send SOAP 1.2 request by default. So the SOAP message HTTP headers for the above code would be like this,

POST /samples/echo_service.php HTTP/1.1
User-Agent: Axis2C/1.5.0
Content-Length: 223
Content-Type: application/soap+xml;charset=UTF-8;action="http://localhost/samples/echo_service/echoString"
Host: 127.0.0.1

Note that the SOAP  Action is sent in the Content-Type inside the optional action parameter.

If you set it to use SOAP 1.1 explicitly in the WSClient like this,

$client = new WSClient(array( "to" => "http://localhost/samples/echo_service.php",
                              "useSOAP" => 1.1 ));

It would send the SOAP Action as a separate HTTP header,

POST /samples/echo_service.php HTTP/1.1
User-Agent: Axis2C/1.5.0
SOAPAction: "http://localhost/samples/echo_service/echoString"
Content-Length: 225
Content-Type: text/xml;charset=UTF-8
Host: 127.0.0.1

If you are using WSF/PHP in the server side, you don’t need to worry about the SOAP version as it will support both SOAP 1.1 and SOAP 1.2 automatically.
Anyway you need to declared the actions to operations map, so WSF/PHP will be able to dispatch the SOAP request and direct the message to the correct 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();

So whenever a SOAP request message hit this script, it will check the SOAPAction HTTP header if it is a SOAP 1.1 message, or the action parameter in the Content-Type HTTP header if it is 1.2, then try to find the function mapped with that action from the actions map.
Anyway if the SOAP action is not set in the request message WSF/PHP will try to dispatch the message with other methods like body based dispatching, WS-Addressing based dispatching which are transport protocol independent dispatching mechanisms.

Anyway since most of the cases SOAP is used on top of HTTP, it is really common SOAP messages are dispatched using the SOAP action which is no doubt a very easy and efficient way of dispatching.