WSO2 PHP’s WSF Library (or whatever the damn it is called…) and Turmeric SOA

The title of this post is verbose enough about the feelings I have regarding the naming of this library. It’s as if WSO2 took a page from Microsoft’s book regarding names. What’s next? A Home Edition? Maybe throw in Professional, Business and Ultimate versions too for good measure.

Don’t take me wrong, I have no special feelings towards names themselves, it’s just how difficult it makes to search for people working on the same things and facing the same problems. What do I Google for? WSO2? WSF? PHP? Any combination of these? It’s only made worse by these guys developing frameworks in several platforms, which means I end up finding completely unrelated results from a different implementation, in a different technology.

But, naming rants aside, I thought it would be a good idea to share my experience with getting this library up and running on PHP. I came across this library when converting Apache Stonehenge’s web application to use Turmeric’s instances of Stonehenge’s web services, and it gave me quite some headaches. For this reason, and so that other people in the future don’t have to go through the same painful experiences, I decided to write this blog post. Keep reading if I got your attention…

First and foremost, I should warn that I’m also gonna write the Linux walkthrough and it does expect you to have some basic Linux knowledge. Nothing too advanced, you just need to know your way around a Linux system in a command line. If you meet this criterion, this walkthrough should be a walk in the park (no pun intended there).

Setting up the library

To begin with, you must download the WSF PHP library sources. You should be able to find it here somewhere. At the time of writing, the latest version is 2.1.0. Make sure you download the sources. Sadly, the binaries only include DLL’s for the Windows installation, which means that us, Linux users, must compile our own binaries by hand. No biggie though, it’s easier than it sounds.

After you’ve downloaded the library, the next thing you should do is “cd” into the directory. Then, normally you’d just do ./configure followed by a make and make install, but there’s a caveat: it’s VERY recommended that you specify a prefix when you do ./configure. The prefix will tell WSO2 where to place the binaries after you compile and “install”, and this is extremely useful for WSF as you’ll need a clean directory featuring only the binary files of this library. You’ll understand why in a minute.

In sum, you should do:

./configure --prefix=/usr/local/bin/apache2/php/wsf-php/
 make
 [sudo] make install

In my example you’ll see that I’m telling “make” to install the library in /usr/local/bin/apache2/php/wsf-php/ and in the last step I’ve also accounted for those of you who, like me, use Ubuntu. If you use Ubuntu, make sure you add the sudo before the make install command (without brackets).

Troubleshooting: If you installed PHP through Ubuntu’s packages, it is possible that everything went fine at this point. If it did (i.e. if you got no errors in neither of the stages) then excellent. Move on. Skip this section. If, on the other hand, you got an error about a missing php-config, then you need to specify the path to this binary in the ./configure step. First you should know where your PHP installation lies (and you’re entirely on your own for this one) and once you know where it is, your php-config binary is inside /bin/. Once you figured out where that is, you should go back to those three steps above, except your ./configure should look like: </p> >

./configure --prefix=/usr/local/bin/apache2/php/wsf-php/ --with-php-config=<path_to_php>/bin/php-config

After this, don’t forget of course, to do the make and make install steps.

With that done, you should now have the compiled library in /usr/local/bin/apache2/php/wsf/ (or in whichever folder you specified as prefix). You also want to have a look at the final lines of the “make install” step and look for a reference to a wsf.so file. That’s THE library that PHP will load and you’ll need to know exactly where it is. In my case, the library sits in /usr/local/bin/apache2/php/lib/php/extensions/no-debug-non-zts-20090626/wsf.so . My guess is that the make install step is smart enough to put it in the equivalent folder inside your PHP’s installation. Anyhow, copy this directory.

The next step involves editing your php.ini file. Again, you should know where this is. After you found it, add the following lines to it:

>

extension=/usr/local/bin/apache2/php/lib/php/extensions/no-debug-non-zts-20090626/wsf.so
wsf.home="/usr/local/bin/apache2/php/wsf-php/"

From that you can see that I put the path to the .so file as an extension that PHP must load, and I specified an entry called “wsf.home” that will tell WSF where its “auxiliary” files are. This is the path you used as the prefix during the compiling process. These are the two most essential parameters that need to be configured to get WSF up and running, there’s more but I’m aiming at the quickest way possible to get it running, with as little configuration as possible.

After you’ve added those lines, you should restart your Apache et voilà! Your PHP installation should now have loaded the WSF library. If you want to be sure that everything is up and running, you can check the contents of /tmp/wsf_php_server.log . If everything went well, this log should have no errors.

Creating a client and using it

Now comes another tricky part. Great, now your library is up and running, but how do you use it?

I’m gonna provide another quick and simple explanation of how to get a client up and running for an existing service. This assumes, of course, that you already have a service running somewhere which provides you with a WSDL file and SOAP ports that you can invoke.

Provided you have that, you need to copy a folder in the WSF sources to somewhere safe and accessible by PHP (by accessible, I mean, PHP/Apache should have at least read and execute permissions). The folder you need is /scripts/. Copy it somewhere you know it won’t get deleted by an overzealous system administrator and keep it accessible. I would keep it out of public access via Apache but that’s entirely up to you. It’s the next step that is important. </p>

Now that you copied this folder (and all its contents) to somewhere safe, you need to go back to your php.ini and add the folder to its include_path definition. In my case, I just uncommented the already existing line and added my scripts folder to it. In the end it looked like:

>

include_path = ".:/php/includes:/usr/local/bin/apache2/php/scripts/"

After you’ve added/uncommented this line, be sure to restart Apache once more. This line will just tell PHP where it can find scripts that WSF will need whenever you’re using its libraries.

With that out of the way, the next step consists of creating a PHP classmap of all the operations and types you have in your WSDL file. My advice is that you obtain the WSDL file in advance and store it somewhere in your hard-drive. After you’ve done this, just go to the scripts folder and do:

>

php wsdl2php.php <path_to_your_wsdl_file>

It can happen at this step that Linux will tell you it can’t find PHP. If that’s the case, instead of starting off with just “php”, use the full path instead.

By doing this step, you’ll see a bunch of PHP code scrolling through your console. If that was the case, repeat the command and redirect the output to a file, e.g. > somefile.php.

This somefile.php is now your client. It includes a PHP class for every type in your WSDL and an action for every SOAP port. It also includes, at the very end, a sample of how you’d invoke every action. By looking at that you can probably get a good idea of how WSF works, and that’s pretty much it. I assume that if you’re messing around with PHP, you do have enough knowledge to get rid of these sample invokations and just use this file as something you import and use in your PHP application. That’s not going to be covered in this tutorial.

If you do have questions or ran into trouble while following these steps, please do leave me a comment and I’ll try to answer as soon as possible. I hope this has somehow helped you, reader. I know I wish I had found something like this post when I first started messing around with WSF!

Till the next post!