?xsd option added to WSF/PHP

?xsd is an standard option to serve an xsd file imported within a wsdl. This was a missing feature in WSF/PHP. In WSF/PHP automatic wsdl generation, it does not generate additional xsds which are imported by the wsdl and hence this option would not be required. However, with wsdl mode, you could have additional xsds imported in the wsdl. Now you can obtain these xsds with the option ?xsd=xsdfilename.xsd.

WSF/PHP WSDL Mode - Handling XML Schema Arrays

This post "WSF/PHP WSDL Mode - Handling XML Schema Arrays" talks about how you deal with XML Schema arrays when you write web services in WSDL mode with WSF/PHP.

WSClient WSDL Mode With Array Based API

In WSDL mode you have two APIs. One is Class based API which is more common and the other is Array Based API. Sometime it is easy to use Array Based API over the class based API. I'm explaining this with an example in this blog entry.

Send Binary With Web Services in PHP - 2 Minutes Introduction

If you want to send binary in web services, you have several options. You can use either base64 encoded strings or MTOM, SWA binary optimized protocols. Here is a very quick introduction on how you can implement it in your application.

WSDL Mode Improvement for the next release

Nandika has recently blog about the latest major features in the next WSF/PHP release. In addition to that it has some minor features as well. One of that big minor feature is it is bundled with the complete support for the WSDL mode.

In the last release we have done lot of improvements to the wsdl mode so it was able to handle most of the common wsdls you can find in public and enterprise. And from this release,

• You can send and recieve MTOM, SWA attachements in WSDL mode, Whenever you found base64Binary in wsdl you can specify send this type as MTOM or SWA attachment using the useMTOM option.
• You can send and recieve SOAP headers using WSDL mode.
• The xsi:type based serialization and deserialization. This allows you to send and recieve Child type in place of parent schema types. In other terms you can work with the true polymorphism in your xml messages.

Please look at the latest test cases for the wsdl mode in svn.

• Client Side
• Server Side

WSF/PHP Against different Schema Constructs

WSF/PHP 1.3.2 have support for many Schema constructs in the WSDL mode. You may like to check in what are the new schema constructs it is supporting.
You can find test cases for clients in here, https://wso2.org/repos/wso2/trunk/wsf/php/src/tests/samples/wsdl_mode and for service in here, https://wso2.org/repos/wso2/trunk/wsf/php/src/tests/samples/services/wsdl_mode

These test cases have a description about what scenarios it is testing and provide simple demonstrations how you should write programs for different schemas.

WSO2 Web Services Framework for PHP v1.3.2 Released

Users reported some problems in http basic authentication support which have newly implemented specially for 1.3.0. So we did another quick release fixing the issue + some other minor issues.
Please try out the new release.

WSO2 Web Services Framework for PHP v1.3.2 Released

We are pleased to announce the release of WSO2 WSF/PHP 1.3.2.

WSO2 Web Services Framework for PHP (WSO2 WSF/PHP), is an open source,enterprise grade, PHP extension for providing and consuming Web Services in PHP. WSO2 WSF/PHP is a complete solution for building and deploying Web services and is the only PHP extension with the widest range of WS-* specification implementations. It's Key features include, secure services and clients with WS-Security support, binary attachments with MTOM, automatic WSDL generation (code first model),
WSDL mode for both services and clients (contract first model) and interoperability with .NET and J2EE.

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

Project home page: http://wso2.org/projects/wsf/php

Key Features

1. Client API to consume Web services
   
   
   
   • WSMessage class to handle message level options
   
   
   
   • WSClient class with both one way and two way service invocation support
   
   
   
   • Option of using functions in place of object oriented API with ws_request



2. Service API to provide Web services
   
   
   • WSMessage class to handle message level options
   
   
   
   • WSService class with support for both one way and two way operations
   
   
   
   • Option of using functions in place of object oriented API with ws_reply
   
   


3. Attachments with MTOM
   
   
   • Binary optimized
   
   
   • Non-optimized (Base64 binary)
   
   

4. WS-Addressing
   
   
   • Version 1.0
   
   
   • Submission


5. WS-Security
   
   
   • UsernameToken and Timestamp
   
   
   • Encryption
   
   
   • Signing
   
   
   • WS-SecurityPolicy based configuration
   
   

6. WS-Reliable Messaging
   
   
   • Single channel two way reliable messaging


7. WSDL Generation for Server Side
   
   
   • WSDL generation based on annotations and function signatures, and
     
     serving on ?wsdl or ?wsdl2 requests

8. WSDL mode support for both client and server side
   
   
   • Write services and client based on a given WSDL
   
   
   • WS-Addressing and WS-SecurityPolicy is supported in WSDL mode
   
   

9. REST Support
   
   
   • Expose a single service script both as SOAP and REST service

10. Provide easy to use classes for common services
    
    
    • Consume some well known services such as Yahoo search and Flickr
      and Amazon services using predefined classes
    
    



11. wsdl2php.php script. This script can generate PHP classes for services
    

    and clients for a given WSDL to be used with WSDL Mode .
    
    

Major Changes Since Last Release

1. Added HTTP Authentication support in WSDL mode



2. Fixed memory corruption in wsdl mode

Reporting Problems

Issues can be reported using the public JIRA available at:

https://wso2.org/jira/browse/WSFPHP

Contact Us

Please subscribe to our user or developer mailing lists. For details on how to subscribe please visit: http://wso2.org/mail#wsfphp

We welcome your early feedback on this implementation.

Thank you for your interest in WSO2 WSF/PHP.

-- WSO2 WSF/PHP Team --

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.

"opParams" option for WSService

The option "opParams" is an optional parameter to the WSService. If you set opParams to WSMESSAGE the service function would be like this,

/* this is the service function */
function echoFunction($inMessage /* with the type of WSMessage */) {

$outMessage = new WSMessage($inMessage->str);


return $outMessage; /* with the type of WSMessage */
}

$operations = array("echoString" => "echoFunction");


$opParams = array("echoFunction" => "WSMESSAGE");
/* WSMESSAGE is the default value for this situation */

$service = new WSService(array(


     "opParams" => $opParams,

     "operations" => $operations))

Note that when you provide WSMESSAGE to the "opParams", the service operation parameters(both input and output) are of the type WSMessage.
Now say we put "MIXED" in there like the one in following

/* this is the service function */
function echoFunction($inMessage /* with the type of string */) {

$outMessage = $inMessage;

return $outMessage; /* with the type of String */
}

$operations = array("echoString" => "echoFunction");


$opParams = array("echoFunction" => "MIXED");
/* MIXED is the default value for this situation */

$service = new WSService(array(

     "wsdl" => "http://localhost/echostring.wsdl",
     "opParams" => $opParams,

     "operations" => $operations))

Here note the difference in the service operation. Now the argument types are strings. This types are defined in the wsdl which is provided as an argument to the WSService.

So it is clear

When "wsdl" is provided the opParams are default to "MIXED",
otherwise it is default to "WSMESSAGE".

So you don't need to provide the opParams option explicitly in both above cases.

WSF/PHP 1.2.2 is ready to ship

If you were looking forward to use WSDL mode with PHP here is a good NEWS for you. WSF/PHP 1.2.2 is coming up with the support of many WSDL and XML Schema constructs.
Here is a list of WSDL and Schema Constructs it is going to support,

• Elements with simpleType

• simpleType restriction

• simpleType list

• complexType sequence

• complexType all/choice

• inner content models

• complexContent extension (non xsi:type based serializing, parsing)

• complexContent restriction

• attribute

• simpleContent extension

• attributeGroup

• WSDL import

In addition to the above we still have the following features to implement, and these are planned to implement in the next major release 1.3.0

• anyAttribute

• custom headers

• xsi:type" based serialization and parsing

• Mtom support with WSDL mode
  

We would be able to do the release early next week. Hope you will enjoy the new feature set.

WSF/PHP with doc-lit bare WSDLs

You may use doc-lit bare WSDL to send a web service request with just one simple parameter in the message, like this.

<echoInt>3</echoInt>

In order to prepare this message with wsdl mode in WSF/PHP you can directly input the parameter value without instantiate any wrapper classes. Just take look at the following doc-lit bare WSDL and the corresponding WSDL-mode client to have an idea how easy it is.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
  xmlns:ns0="http://wso2.org/dyn/codegen/demo"
  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"

  xmlns:ns1="http://wso2.org/dyn/codegen/demo/xsd"
  xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://wso2.org/dyn/codegen/demo">

<wsdl:types>
  <xs:schema xmlns:tns="http://wso2.org/dyn/codegen/demo"
          attributeFormDefault="qualified"
          elementFormDefault="qualified" targetNamespace="http://wso2.org/dyn/codegen/demo">

      <xs:element name="echoInt" type="xs:int"/>
      <xs:element name="echoIntResponse" type="xs:int"/>

  </xs:schema>
</wsdl:types>
<wsdl:message name="echoIntRequest">
  <wsdl:part name="parameters" element="ns0:echoInt"/>

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

</wsdl:message>
<wsdl:portType name="EchoServicePortType">
  <wsdl:operation name="echoInt">

      <wsdl:input message="ns0:echoIntRequest" wsaw:Action="urn:echoInt"/>
      <wsdl:output message="ns0:echoIntResponse" wsaw:Action="urn:echoIntResponse"/>

  </wsdl:operation>
</wsdl:portType>
<wsdl:binding name="EchoServiceSOAP12Binding" type="ns0:EchoServicePortType">

  <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
  <wsdl:operation name="echoInt">

      <soap12:operation soapAction="urn:echoInt" 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="EchoService">
  <wsdl:port name="EchoServiceSOAP12port_http" binding="ns0:EchoServiceSOAP12Binding">

      <soap:address location="http://localhost:8080/dyn/codegen/demo/services/EchoService"/>
  </wsdl:port>
</wsdl:service>
</wsdl:definitions>

And the client is simple as this

// the background work for create wsclient and the proxy
$client = new WSClient(array ("wsdl" =>"echo.wsdl"));

$proxy = $client->getProxy();

// you directly input the request parameter
$response = $proxy->echoInt(3);


echo $response;

So in a case where you just need to send only one parameter for the service operation, this form of messages make your web service call more efficient and more easy to implement.

PHP Web Services with WSDL Tutorial

Were you finding a starters tutorial for PHP Web Services with WSDL?. I wrote one for wso2 Oxygen Tank. This is based on the WSO2 WSF/PHP release 1.2.0. But it will be working for newer releases like 1.2.1 without problem. Hope you will be find this really useful.

WS-Security with WSDL mode

If you ever wanted to use ws-security with WSDL mode, you can check this demo. Observe closely how CalendarService.php and CalendarClient.php is implemented from Calendar.wsdl, this gives you a good idea how you can implement both client and server sides with ws-security in wsdl mode.

Simple Calculator - Demo of use of WSDL mode

Here are the steps I followed to create a simple Calculator Service + client.

1. Stated with the CalculatorDoc.wsdl found in here, http://svn.apache.org/repos/asf/webservices/axis2/trunk/c/test/resources/wsdl/CalculatorDoc.wsdl

2. Generated server side code using the wsdl2php.php script packed with the WSO2 WSF/PHP 1.2.1.

3. Run the wsdl2php.php script from command prompt with the following arguments.

/my/home/scripts/wsdl2php.php -s CalculatorDoc.wsdl

Here '-s' means for the server side.

4. I redirected output to the service.php in my linux system, so the command was like
/my/home/scripts/wsdl2php.php -s CalculatorDoc.wsdl > service.php
In a case this this doesn't work for you copy and paste the code to the service.php file.

5. Filled the adding/ subtraction/ multiplication/ division algorithm inside method bodies. There are helping comments which guide you what are the types of parameters and return value in the function, here is my way of doing it.

// define PHP functions that maps to WSDL operations 
function add($input) {
 // TODO: fill in the business logic
 // NOTE: $input is of type add


 $a = $input->arg_0_0;
 $b = $input->arg_1_0;


 $c = $a + $b;
 // NOTE: should return an object of type addResponse

 $res = new addResponse();
 $res->addReturn = $c;


 return $res;
}


function sub($input) {

 // TODO: fill in the business logic
 // NOTE: $input is of type sub

 $a = $input->arg_0_1;
 $b = $input->arg_1_1;


 $c = $a - $b;
 // NOTE: should return an object of type subResponse

 $res = new subResponse();
 $res->subReturn = $c;


 return $res;
}


function mul($input) {

 // TODO: fill in the business logic
 // NOTE: $input is of type mul

 $a = $input->arg_0_2;
 $b = $input->arg_1_2;


 $c = $a * $b;
 // NOTE: should return an object of type mulResponse

 $res = new mulResponse();
 $res->mulReturn = $c;


 return $res;
}


function div($input) {

 // TODO: fill in the business logic
 // NOTE: $input is of type div

 $a = $input->arg_0_3;
 $b = $input->arg_1_3;


 $c = $a / $b;
 // NOTE: should return an object of type divResponse

 $res = new divResponse();
 $res->divReturn = $c;


 return $res;
}

6. Now put the service.php in to your web root directory or some sub directory inside the web root and make sure it is correctly deployed by typing the location in the browser. For an example, I put my service.php inside calculator sub directory inside the web root, so I tested in the browser by typing http://localhost/calculator/service.php

Note: that this doesn't test the algorithm of the service, but just it make sulre the service and the operation set are correctly deployed.

7. So now you can write a client to test the service operation, You can generate a client with the following command,

/my/home/scripts/wsdl2php.php CalculatorDoc.wsdl

Note that the '-s' is dropped.

8. Go through the TODO comments and fill the client logic by filling sample input to test the service,

   // create input object and set values
  $input = new add();
  //TODO: fill in the class fields of $input to match your business logic


  $input->arg_0_0 = 3;
  $input->arg_1_0 = 4;

  // call the operation

  $response = $proxy->add($input);
  //TODO: Implement business logic to consume $response, which is of type addResponse

  echo "3 + 4 =  {$response->addReturn}\n";



  $input = new sub();
  //TODO: fill in the class fields of $input to match your business logic

  $input->arg_0_1 = 3;
  $input->arg_1_1 = 4;


  // call the operation
  $response = $proxy->sub($input);
  //TODO: Implement business logic to consume $response, which is of type subResponsee


  echo "3 - 4 =  {$response->subReturn}\n";

  $input = new mul();
  //TODO: fill in the class fields of $input to match your business logic


  $input->arg_0_2 = 3;
  $input->arg_1_2 = 4;


  // call the operation
  $response = $proxy->mul($input);
  //TODO: Implement business logic to consume $response, which is of type mulResponsee


  echo "3 * 4 =  {$response->mulReturn}\n";

  $input = new div();
  //TODO: fill in the class fields of $input to match your business logic


  $input->arg_0_3 = 3;
  $input->arg_1_3 = 4;


  // call the operation
  $response = $proxy->div($input);
  //TODO: Implement business logic to consume $response, which is of type divResponsee


  echo "3 / 4 =  {$response->divReturn}\n"

9. One more thing, The wsdl is coded with it s endpoint, but for you to test you need to change the endpoint to where you have actually test the service, for an example in my case to " http://localhost/calculator/service.php"
You can do the change in the wsdl. But there is an option in the WSClient constructor where you can give the service endpoint.
So my new WSClient constructor looks like this,

   // create client in WSDL mode
 $client = new WSClient(array ("wsdl" =>"CalculatorDoc.wsdl",
     "to" => "http://localhost/calculator/service.php",
     "classmap" => $class_map));

10. That is all I did, And Finally run the client with the following command,
php client.php

And I received the expected output as following,
3 + 4 = 7
3 - 4 = -1
3 * 4 = 12
3 / 4 = 0.75

XML Schema Parsing in WSF/PHP

WSF/PHP is currently famous for wide range of WS-* implementations like WS-Security, WS-Reliable Messaging. Plus it is the only choice that PHP programmers have when they have to work with optimized binary attachments, secured and reliable messaging.

Anyway when it comes to WSDL-mode, for the time being it supports only very common types of XML schema constructs. Anyway currently we are on the process of improving this, and surely WSF/PHP will be able to handle most of your WSDLs by the next major release.

wsdl2php now Supports Server Side

WSO2 WSF/PHP wsdl2php code now supports server side. I added server side support yesterday.

Now users can write both clients and services in WSDL mode with minimal effort. You just have to generate the code and follow the TODO instructions in the generated code.

This feature will be available with the upcoming 1.2.1 release.

How Code Generation Makes Development Easy Over Traditional WSDL Mode

Yesterday Samisa's blog revealed new approach that WSF/PHP is going to take in the next major release.

WSF/PHP is going to introduce pre code generation for both Web Service clients and services for PHP developers. I think this may little strange to PHP people who used to expect things happening in run time. But sometime it s better to tests different paths to test and pick the ideal method.

I see several advantages in static code generation over current run-time support for the WSDL mode.
1. The usability is high,
Currently we should write classes manually in order build the data tree of the payload, For that you need to have at least some idea of WSDL and XML Schema. But we cannot expect an average user identify these types and write PHP Classes by hand. So it is better we have systems generating classes.

2. Low error-prone
If you have set of classes pre-defined to use in your system it will be no doubt less error-prone than using classes written by yourself. Because current way you may do errors both in writing classes and invoking services, so generated code will eliminate the errors in writing classes.

3. Rapid Development
It would give you some part of code written for you

4. Sample Demos
Easy to generate sample demos for a particular WSDL, so users will be able to follow them in their application

5. Performance,
If we can bypass the wsdl mode with the newer code generation approach that would enhance the performance, So surely in the first step the generated code would be mostly run using the current wsdl mode, so there will be no performance improvement.

6. Easiness in testing
Mostly this open the path to automate testing.

Use WSDL Elements Maps to Your PHP Classes.

WSF/PHP allows you to map schema elements and types in your WSDL to PHP Classes in your code.. You can find a good example of this in the samples/wsdl_generation directory in the WSF/PHP pack.

You have to provide the map of wsdl type to the PHP class name as an option to both WSClient(in a case it is a client) and WSService(in a service).

From WSF/PHP 1.2.1 patch release you will not need to provide the full map of classes to schema construct. Since the engine will be intelligent enough to pick the class with the same name as schema construct when the class is not provided in the class map. If there is no class like that at all, the engine will create a unnamed class and allow to access its properties as it was a class like made to represent that schema construct.

So hope you will enjoy the new improvements to the API.

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..