WSF/PHP comes with a Data Service Library. It allows you to expose your Database as a Web Service with Full WS-* support.
1.Prepare the Database
Before configuring your database you need to install the PDO extension corresponding to your Database engine. For an example if you select to use "mysql" you have to install the pdo_mysql extension. PDO extensions are available for many popular databases like mysql, pgdql, sqlite, odbc, oci, firebird. For this manual I m using 'mysql' to demonstrate the use of basic Data Services.
Now we will first prepare a Database to use in our Data Service. Here is my Database Format.
Database Name: ds
Tables
Customers:
customerNumber | customerName | contactLastName | contactFirstName | phone | addressLine1 | addressLine2 | city | state | postalCode | countdy | salesRepEmployeeNumber | creditLimit |
Orders
orderNumber | orderDate | requiredDate | shippedDate | status | comments | customerNumber |
You can use the following commands to create the database and tables. Or you can use the sql scripts inside samples/Data Services/sql in the wsf/php pack to create these tables and fill sample data
create database ds; use ds; CREATE TABLE Customers( customerNumber INTEGER, customerName VARCHAR(50), contactLastName VARCHAR(50), contactFirstName VARCHAR(50), phone VARCHAR(50), addressLine1 VARCHAR(50), addressLine2 VARCHAR(50), city VARCHAR(50), state VARCHAR(50), postalCode VARCHAR(15), country VARCHAR(50), salesRepEmployeeNumber INTEGER, creditLimit DOUBLE ); CREATE TABLE Orders( orderNumber INTEGER, orderDate DATE, requiredDate DATE, shippedDate DATE, status VARCHAR(15), comments LONG VARCHAR, customerNumber INTEGER );
In this service we will list all the orders done by a perticular customer.
2.Writing the Dataservices Script
We will straight away look in to the complete code. Please continue reading for the explanations.
require_once("wso2/Data Services/Data Service.php"); // database configurations $config = array( "db" => "mysql", "username"=>"your_db_username", "password"=> "your_db_password", "dbname"=>"ds", "dbhost"=>"localhost"); // input format array(param_name => SQL_TYPE) $inputFormat = array("customerNumber" => "INT"); // output format, please check the API from http://wso2.org/wiki/display/wsfphp/API+for+Data+Services+Revised $outputFormat = array("resultElement" => "Orders", "rowElement" => "Order", "elements" => array( "order-number" => "OrderNumber", "order-date" => "OrderDate", "status" => "status")); // SQL statement 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)); $my_data_service = new Data Service(array("config"=>$config, "operations"=>$operations)); $my_data_service->reply(); ?>
Database configurations
$config = array( "db" => "mysql", "username"=>"your_db_username", "password"=> "your_db_password", "dbname"=>"ds", "dbhost"=>"localhost");
Here you need to give the database engine as the "db" option. Note that in order to run 'mysql' you need to have the pdo_mysql extension as explained above. Simmilarly you can use pdo_pgsql, pdo_sqlite, and etc to run the Data Service with the corresponding database engines.
The rest of the configuration are the hostname, username and the password of the your database connection.
If you are running on a file or memory based database like 'sqlite' you may need to give the DSN(Data Source Name) directory instead of providing the value for 'db', 'dbname' and 'dbhost' seperately. For that you can use the 'dsn' option. For more information about how 'dsn' should be provided please see the section correspond to your database engine in PHP PDO Manual
Prepare the operation/ Query
// input format array(param_name => SQL_TYPE) $inputFormat = array("customerNumber" => "INT"); // output format, please check the API from http://wso2.org/wiki/display/wsfphp/API+for+Data+Services+Revised $outputFormat = array("resultElement" => "Orders", "rowElement" => "Order", "elements" => array( "order-number" => "OrderNumber", "order-date" => "OrderDate", "status" => "status")); // sql statement 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));
In the WSF/PHP Data Services, terms operation and query refers to the same set of properties. They both contain the "inputFormat", "outputFormat", "sql", "inputMapping".
There is an another option "inputMapping" which enable you to select the name of the element name and map it in to the names you used in inputFormat option, outputFormat and other inner queries. Please see the Data Services API Documentation for more details.
Calling the Data Service
require_once("wso2/Data Services/Data Service.php"); $my_data_service = new Data Service(array("config"=>$config, "operations"=>$operations)); $my_data_service->reply(); ?>
After you prepared the operations/queries you need to create an instance of Data Service class which is declared in "wso2/Data Services/Data Service.php" relative to the 'scripts' directory packed with WSO2 WSF/PHP. Note that You need to set the include_path directory of php.ini to the 'scripts' directory in order to run Data Services (and WSDL mode and WSDL generation). Please see the installation manual for more details.
Data Service class is inherited from WSService class. So you can give all the option available in the WSService class constructor to the Data Service class constructor as well. For an example you can enable the security features here by providing valid values for 'policy' and 'securityToken' options.
You can deploy the Data Service easily by putting your dataservice script in to your web documents directory. This is similar to how you deploy a normal Webservice with WSF/PHP.
You can use the WSF/PHP WSDL Mode to generate a client using your Data Service. You can retrieve the WSDL of the service adding '?wsdl' ( or '?wsdl2' for wsdl verison 2.0) to the dataservice endpoint.
For this manual I will be writing a simple client which uses XML API.
<? $requestPayloadString = <<<XML <customerOrders> <customerNumber>406</customerNumber> </customerOrders> XML; try { $client = new WSClient(array("to" => "http://localhost/my_data_service.php")); $responseMessage = $client->request( $requestPayloadString ); printf("Response = %s <br>", htmlspecialchars($responseMessage->str)); } catch (Exception $e) { if ($e instanceof WSFault) { printf("Soap Fault: %s\n", $e->Reason); } else { printf("Message = %s\n",$e->getMessage()); } } ?>