Obtaining Soap Fault Information from WSFault Object

WSFault Object encapsulates the information related to SOAP Fault and stores them as properties of the WSFault object.

WSFault object has the following properties.

Reason, Code, Detail and Role. In addition it has a property "str" which contains the entire Fault xml as a string.

So Obtaining the Fault and Getting Information from it is very simple.

All what is required it to catch the exception object, check whether it is actually a WSFault object, and read the fault properties.

For example, to obtain the Soap Fault Reason , one can use the following code sample.
try{
// Some WSClient related code goes here.
}catch (Exception $e) {
if ($e instanceof WSFault) {
printf("Soap Fault: %s\n", $e->Reason);
} else {
printf("Message = %s\n",$e->getMessage());
}
}

Read documentation from full detail.

Article on Amazon Online Shoping

Dimuthu has written an article on how to utilize WSF/PHP extension to do amazon online shoping.

It has the source code too.

Implementing a Service using a PHP Class

WSF/PHP supports implementing a service using a php class. One of the advantages of implementing the service Operations with in a class is that is gives the ability to pass arguments to the constructor of the class.

Following is a simple example.

class Bar{

private $value = "";
function __construct($str){
$this->value = $str;
}

function echoValue($inMessage){
$responsePayloadString = <<<XML
<ns1:echostring ns1="<a href=">http://wso2.org/projects/wsf/php</a>">
<value>$this->value</value> </ns1:echoString>
XML;
return new WSMessage($responsePayloadString);
}

}

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

$service = new WSService(
array( "classes" => array("Bar" =>
array("operations" =>$operations,
"args" => array("Hello")
)
)));


$service->reply();

Note that Bar class is just a very simple PHP class. It's constructor takes a string argument and echo that value.

Next you have to define the Operations array with is very simple.
Next you need to tell the WSService class about your class, its defined operations and its arguements.

WSService options array accepts a parameter named "classes" which is an associative array. Its key is the class name and value is another array with contains the "operations" options and "args" options. "operations" are the operations defined in the class. The "args" is an array of arguments to the constructor of the corresponding class. Since the "Bar" class has a single argument constuctor, we are providing an string.

Changing the Service Name

WSF/PHP uses the php file location to generate a unique service name which is used to store the service configuration information in the Underlying WSF/C Library. We used "" simple to seperate out the folder paths so that the generated string will be unique for a given file.
This was however causing problems with the generated WSDL file as other WSDL parsers complained of this symbol.

We have now fix this issue by allowing the user to specify a unique service name for a given file. In addition , if the user does not sepcify the "serviceName" option, a service name will be generated using the "_" to separate the folder paths. How ever this may not generate a unique name all the time.
So if you are using WSF/PHP now it is possible to configue your service name.

Eg

WSService(array("serviceName"=>"MyService"));

Accessing Flicker REST API

Accessing Flicker rest API using php is very simple. All what is needed is to construct the arguements array with the url and invoke the query. You can use the file_get_contents function to do the invocation.

For example, to invoke the flicker.photos.getRecent method , you can you the following code sample.

"flickr.photos.getRecent",
'api_key' => "your api key goes here");

foreach ($params as $key => $value) {
$query_string .= "$key=" . urlencode($value) . "&";
}

$url = "$base_string?$query_string";

$output = file_get_contents($url);

echo $output;

?>

you can use the urlencode function to encode the array of parameters and send then use the file_get_contents function to send the reqeust.

Getting WSF/PHP running on Debian

Dinesh has posted a very comprehensive guide to getting WSF/PHP working on debian.
It will provide all the details you will need.

Building WSF/PHP on Windows

Building WSF/PHP on Windows platform is quite straight forward provided that you have the necessary tools and the dependency software.
For building WSF/PHP you will need Microsoft Visual Studio. Else you can build using Windows platform SDK and Visual Studio Express edition.

I will list down the step by step process to building WSF/PHP on windows.

1. Download the dependencies.
1. Libxml2
2. Iconv
3. OpenSSL ( Download MSI installer )
4. PHP Source
5. PHP Binary
6. PHP Win32 Build tools. (Win32 build)
7. WSF/PHP source zip
8. Sqlite

2. Next Install OpenSSL.
3. Unzip all the binary dependencies.
4. Unzip WSF/PHP source. Eg E:\wso2-wsf-php-1.2.0
5. Go to E:\wso2-wsf-php-1.2.0 and open configure.in file.
6. Now you will see an option set like this.


DEBUG = 1
CRUNTIME=/MT
EMBED_MANIFEST=0
LIBXML2_BIN_DIR = E:\libxml2-2.6.30.win32
ICONV_BIN_DIR = E:\iconv-1.9.2.win32
ENABLE_SSL = 1
OPENSSL_BIN_DIR = E:\OpenSSL
WITH_SQLITE = 1
SQLITE_BIN_DIR = "E:\sqlite-3_3_81
SQLITE_SRC_DIR = "E:\sqlite-3_3_81"

PHP_SRC_DIR = E:\php\php-5.2.5
PHP_BIN_DIR = E:\php\php-5.2.5-Win32
WIN32BUILD_DIR = E:\php\win32build

I have removed the comments in the configure.in file. All you have to do is to edit these directory locations and set your corresponding directory locations.
If you want a debug build , set DEBUG option to 1.

7. open a command line.
Go to "C:\Program Files\Microsoft Visual Studio 8\VC\bin" directory and run the vcvars32.bat file. (Note: depending on your VC version, you might have a different location.)

8. Go to your WSF/PHP extract directory and run the build.bat file.

If you have set the directory paths correctly, WSF/PHP will be compiled and you will get the binary directory "wso2-wsf-php-bin-1.2.0-win32" built to the same directory.

Happy Compiling.

WSDL Generation with WSF/PHP

WSF/PHP supports wsdl generation for the well known serviceuri?wsdl request. In addition to that it generates ?wsdl2 as well.

So How can you get make your php service generate the wsdl?
Well, the steps are quite simple. Since php functions does not contain type information for the input or output parameters, WSF/PHP obtains the type infromation
from the documentation comments.

Following is an example service with annotations.

/** BuyItem function
* @param string $item_name of the item to buy
* (maps to the xs:string XML schema type )
* @param int $amount no of items to buy
* (maps to the xs:nonNegativeInteger XML schema type)
* @return float $price total price
*(maps to the xs:double XML schema type )
*/
function getPriceFunction($item_name ,$amount)
{
global $item;
if ($item_name && $amount){
if(isset($item[$item_name])){
return array("price" => ($item[$item_name] * $amount));
}
else
return NULL;
}
return array("price" => 200043);
}

As you can see the doc comments involves the following format.

@param string $item_name
(maps to the xs:string XML schema type )
This comment says that the function parameter $item_name is of type string and is a function parameter. The second line says the corresponding XML Schema data type which is xs:string.

Similarly all the parameters and return types are annotated. Once you do that, WSF/PHP is able to process this information and automatically generate the wsdl on demand.

Manually Removing Viruses ( Part 1)

Last month, I had my machine infected with a couple of viruses and had to delete them manually. In the process I learned quite a lot of stuff about viruses. In addition I came accross some very usefull set of tools.

1. How do you know whether you system is infected by a virus. Following are the most common set of symtoms of virus infected machine.
1. Disables Task Manager.
2. Disables Command prompt
3. Diables Registry editor
4. Computer Slows down
5. Folder options menu removed
6. Show Hidden files option disabled.
7. My Computer drive now open by double click.
8. Automatic shutdown


Most of the viruses put an autorun entry when they infect a machine so that, when the system boots up next time, the virus is automatically executed. So even if we find and delete the virus from one location, next moment , the virus will be back there because the virus process is running. Therefore you will need a tool that enables you to see the running processes and autorun entries.

Process Expolrer and Autoruns are two such very usefull tools.

Since most of the viruses will have the hidden attribute set, and they disables the show hidden files option, you will need a tool that enables you to see the hidden files. One such tool is WINRAR.

Before going to to detail on how get rid of viruses, It is important to know how to stay out of viruses.

The most common way of virus spreading nowadays is through usb pen drives. When you have the autorun feature enabled ( this is the default ), the moment you plug in an
infected pen drive, your machine will also get the virus.
So the first step in preventing viruses is to disable the autorun.

You can find how to disable autorun from here.

How to install WSF/PHP on XAMPP

There were number of people who ran in to problems in installing WSF/PHP . So I created a demonstration on how to do that using Wink tool.

You can see this demonstration at http://wso2.org/library/3076.

By the way, Wink is real cool software.

Using SSL and Web Services with WSF/PHP

Sometimes , when you want to send critical information using SOAP, you need to use https protocol. WSF/PHP buildin support for this. All you need to do it to provide some simple options and configure the WSClient object.

Following is an example on how to do that.

The options used to configure ssl are
CACert, clientCert, and passphrase.

CACert is the Certificate authrity's certificate.
clientCert is the client's certificate.
passphrase is the password.

You can configure the WSClient object with these options when using ssl.

Eg

$client = new WSClient(array( "to" => "some endpoint uri",
"CACert" => "cacert.pem"));

Receiving Base64 content with in a soap message in WSF/PHP

When you receive a soap message with mtom, the receiving WSMessage object will contain the two properties using which you can extract the binary content. These two are attachments property and cid2ContentType property. But When if you want to receive the binary content received converted to base64, WSF/PHP can do that too.

All you need to do is to set the responseXOP option in the WSClient options array to FALSE.

Eg.

$client = new WSClient(
array( "to" => "some end point",
"useMTOM" => TRUE,
"responseXOP" => TRUE));

Using Tcpmon tool in implementing Web Services

Tcpmon is a open source project hosted at Apache. It is a very usefull easy to use java tool when developing Web Services. Here are some of the screen shots of tcpmon tool




















As you can see all you need to do is to set listen port and target port.




















Using tcpmon tool you can varify the soap messages exchanged effectively. When you want to capture the soap messages exchanged between the client and the server, you can use tcpmon to do it very easily.

Here is a sample senario.
Say you want to capture the soap messages sent and received by a php web service client.
Since Apache2 server runs on port 80, set the target port to 80 and Listen port to some other pot. Eg 8080.

Now open the client file and set the modify the "to" endpoint as follows.

I use the echo_client.php sample from WSF/PHP here.

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

As you can see, now I am sending the client message to the listen port I set in tcpmon which is 8080. Now when the client is run, tcpmon will capture the message, display it and also send the message to Apache2 as well. Above picture 2 shows the output captured .

Sending a binary image as base64 text using WSF/PHP

Today I will discuss how to send a binary image as base64 text using WSF/PHP.

$requestPayloadString = <<<XML
<ns1:upload xmlns:ns1="http://php.axis2.org/samples/mtom">
<ns1:fileName>test.jpg</ns1:fileName>
<ns1:image xmlmime:contentType="image/jpeg" xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime">
<xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:myid1"></xop:Include>
</ns1:image>
</ns1:upload>
XML;

Note the string myid1 given after the "cid:myid1".

Next I read a binary image to a variable.

$f = file_get_contents("axis2.jpg");

Now I can create an array with $f associated to string "myid1".

$attachment = array("myid1"=>$f);

Next step is to create a WSMessage object and set this $attachment array to it.


$requestMessage = new WSMessage($requestPayloadString,
array("to" => "http://localhost/samples/mtom/mtom_service_base64.php",
"attachments" => $attachment));

Since I want to send the image as a base64 ,I will set the useMTOM property to FALSE when creating the WSClient object.

$client = new WSClient(array("useMTOM" =>FALSE));

Now all configured and to send the message.

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

echo $responseMessage->str;

When sending the message, WSF/PHP will take out the node and put the base64 converted message in there.

Using WS-Reliable Messaging with PHP

Once you have configured WSF/PHP, you can use WS-RM for client side by adding a couple of options to the WSClient options array as follows.

$wsclient = new WSClient(array("reliable" => TRUE , "useWSA" => TRUE));

Note how I have set "reliable" options to TRUE.

Also note how the WS-Addressing is enabled by specifing the option useWSA=>TRUE.

Now your client is configured to use WS-Reliable Messaging.

Next create a massage to be sent.

$requestMessage = new WSMessage($requestPayloadString,
array( "to" => "http://test.com/rm_service",
"action" => "http://test.com/services/pingStringRM"));


$requestPayloadString is the xml payload to be sent to the destination.
"action" is the WS-Addressing action. Note that this is a must for WS-RM to work.

Now we can use the client object and send the message to the destination with WS-RM on using the send method as follows.

$client->send($requestMessage);

This becomes a one way message since we are using the send method.

I will discuss WS-RM in more detail in the next few days.

Throwing a custom soap fault from a Web Service

Today I thought of describing how to return a soap fault from a WSF/PHP service.
SOAPFault is used to carry error or status information with in a soap message. For this purpose WSF/PHP extension provideds the pre defined class WSFault with the following constuctor.

WSFault(string code, string reason, string role, string detail).

Lets implement a service with will return the fault code "Sender" with reason value "Fault Test".

WSFault constructor only needs code and reason arguements to be mandatory. The other arguments are optional.

WSFault class extends the exception class. So once you create the WSFault object ,it can be thrown from the function.

Here is the complete source code for a service returning the SOAP Fault.


function sendFault($inMessage) {
throw new WSFault("Sender", "Testing WSFault");
}

$operations = array("getFault" => "sendFault");

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

$service->reply();

?>

Detecting the OS using PHP

Sometimes it is necessary to detect the operating system on which your php code is running. PHP has number of pre defined variables and PHP_OS is one such variable which is an string containing the operating system name.
So following code checks whether the system is running on windows or not.

if (stristr(PHP_OS, 'WIN')) {
echo "Win32";
}

Sending a custom soap header to a Web Service

Sometimes Web Services require sending information through soap headers.It is quite simple and easy to send a custom soap header using WSF/PHP.

Consider we want to send a soap header "Transaction" with like in the following soap envelope.

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Header>
<t:Transaction soapenv:mustUnderstand="1" xmlns:t="Some-URI">5</t:Transaction>
</soapenv:Header>
<soapenv:Body>
<ns1:Greet xmlns:ns1="http://php.axis2.org/samples">
<text>Hello</text>
</ns1:Greet>
</soapenv:Body>
</soapenv:Envelope>

First we will create a WSHeader object to produce this header.

$header = WSHeader("ns"=>"some-URI",
"prefix"=>"t",
"name"=>"Transaction",
"data"=>"5",
"mustUnderstand"=>"true");

Now lets create a WSMessage object and set the header to the inputHeaders array.

$msg = new WSMessage($requestPayloadString,
array("inputHeaders" => array($header)));

Note that $requestPayloadString holds the payload string that will be sent to the service.


Following is the complete source code.

$requestPayloadString = <<<XML
<ns1:Greet xmlns:ns1="http://php.axis2.org/samples">
<text>Hello</text>
</ns1:Greet>
XML;

try {

$client = new WSClient(array ("to"=>"http://localhost/samples/greet_service.php"));


$header = WSHeader("ns"=>"some-URI",
"prefix"=>"t",
"name"=>"Transaction",
"data"=>"5");

$msg = new WSMessage($requestPayloadString ,
array("inputHeaders" => array($header)));

$client->request($msg);

echo "\n\n Received message \n";
echo htmlspecialchars($recvMsg);

} catch (Exception $e) {
if ($e instanceof WSFault) {
printf("Soap Fault: %s\n", $e->Reason);
} else {
printf("Message = %s\n",$e->getMessage());
}
}

Deploying PHP Web Services using XAMPP for windows

XAMPP is one of the most popular Apache destribution containing Apache, MySql , PHP and PERL. Now it is possible to deploy web services on XAMPP using WSF/PHP extension.

All you need to do is to download WSF/PHP 1.2.0 Win32 Binary release and do the following configuration steps.

1. Unzip the binary package. You will get the directory C:\wso2-wsf-php-bin-1.2.0-win32.
Add C:\wso2-wsf-php-bin-1.2.0-win32\lib directory to PATH environment variable.
( assuming that you unpacked the binary zip to C drive )

2. Copy wsf.dll located in wso2-wsf-php-bin-1.2.0-win32 directory to "C:\xampp\php\ext".
(assuming that you have xampp installed on C drive).

3. Edit the php.ini file located in C:\xampp\apache\bin directory and add following php.ini entries.

extension=wsf.dll

wsf.home=C:\wso2-wsf-php-bin-1.2.0-win32\wsf_c
wsf.log_path=C:\wso2-wsf-php-bin-1.2.0-win32\wsf_c\logs
wsf.log_level=3
wsf.rm_db_dir=C:\wso2-wsf-php-bin-1.2.0-win32\wsf_c

Append C:\wso2-wsf-php-bin-1.2.0-win32\scripts to include_path in php.ini as follows.

include_path = ".;\xampp\php\pear\;C:\wso2-wsf-php-bin-1.2.0-win32\scripts\"

Thats it. Now you are ready to try out the samples. So copy the samples directory (C:\wso2-wsf-php-bin-1.2.0-win32\samples) to C:\xampp\htdocs directory.

Now you should be able to run the samples.

Now you can write your own web services and clients using WSF/PHP.

Using Pecl command to install WSF/PHP

With WSO2 WSF/PHP 1.2.0 release, Now you are able to use pecl tool for installing WSF/PHP extension. We built this package for linux platform. I am sure that all those php developers on linux platfrom interested in using WSF/PHP will welcome this.

Following are the steps needed to install WSF/PHP on linux.

1. Download WSF/C Framework from here.
http://dist.wso2.org/products/wsf/c/wso2-wsf-c-src-1.2.0.tar.gz
2. Installing wso2-wsf-c is very simple.

tar xf wso2-wsf-c-src-1.2.0.tar.gz
cd wso2-wsf-c-src-1.2.0
./configure
./make
/make install

This will install WSO2 WSF/C Web Services Framework will be installed to /opt/wso2
directory. You will need super user previlages to install it to /opt directory.

3. Now use pecl tool to install the WSF/PHP.
pecl install http://dist.wso2.org/products/wsf/php/wso2_wsf_php-1.2.0.tgz

Now pecl tool will download and install WSF/PHP extension. It will copy the docs folder to /usr/local/lib/php/doc/wso2_wsf_php. samples and scripts folders will be installed to /usr/local/lib/php directory.

Copy the samples folder to your apache2 webserver's document root.

4. Add the following entries to php.ini file.

extension=wsf.so
wsf.home = /opt/wso2/wsf_c
log_level = 3

Uncomment the include_path entry and edit it to point to the location for scripts folder as include_path = ".:/usr/local/lib/php/wso2_wsf_php/scripts"

Please note that you need to have php_xsl extension installed on your system to run the wsdl mode samples.

Also you can check the the project home page.

WSO2 Web Services Framework for PHP 1.2.0 Released

Almost after 3 months from the previous release, we are shiping the latest WSF/PHP release with version numbers 1.2.0. It carries substantial improvement over the previous release of WSF/PHP. The WSDL support has been improved and it now support WS-Security and WS-Addressing. So if you are to write a web service client or service in PHP with the intension of consuming or providing a web service that uses WS-Security, WS-Addressing, then your life will become significantly easy with this new release.In addition, a lot of imporvements and bug fixes have been done.
This release includes binary packages for zend core as well. As usuall packages were released for fedora, ubuntu, and debian in addition to windows. So what ever the platform you are on, you have a chance of trying out this release with very few steps.


Following are the key features in this new release.

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

All of the people there are most welcomed to checkout this release.
You can download the release from http://wso2.org/downloads/wsf/php

Of course if you run in to any problems, you are most welcome to contact us
at WSF/PHP forum. http://wso2.org/forum/188