PHP Web Services: Getting Started

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Samisa Abeysinghe
  • 6 Jan, 2008

Introduction

phpService Oriented Architecture (SOA) is popular in the enterprise, as it simplifies connecting systems. One of the preferred technologies used to implement SOA is Web services, other contenders being traditional messaging systems and plain old XML (POX) techniques. Web services technologies are capable of enabling machine-to-machine interactions, ensuring interoperability among heterogeneous systems. This helps realize loose coupling, a key characteristic of SOA. The machine processable interface, defined using WSDL, message based interactions, using SOAP, and the use of other Web related standards such as HTTP and XML, are the key pillars on which Web services are built.

Applies To



WSO2 WSF/PHP 1.2.0
Environment Windows or Linux

 

Table of Contents

Background

The set of Web services standards, widely known as WS-*, is a comprehensive set of specifications that cover various aspects required to form a complete framework for an enterprise middleware platform.

WS-* Architecture

Given the importance of Web services in the SOA era, it is a must that any programming language has provision to leverage the power of this technology and be able to play its role in a SOA implementation. PHP too has several options when it comes to working with Web services, however, one of the problems till recently was that the level of support for Web services in PHP was limited to SOAP interactions with some level of WSDL coverage. There was hardly any support for the full Web services stack, including addressing, binary attachments and security.

With WSO2 Web Services Framework for PHP (WSO2 WSF/PHP), the WS-* support in PHP has been given a new life.

Introducing WSO2 WSF/PHP

WSO2 Web Services Framework for PHP improves PHP user’s ability to provide and consume Web services. The framework is capable of dealing with binary attachments, WSDL generation, Web services addressing, policies, security and reliable messaging. It is an open source project, with Apache 2.0 license, there are forums, user and developer mailing lists and an issue tracker.

The framework is inter-operable with non-PHP implementations such as .NET and Java, allowing it to be integrated with enterprise applications seamlessly, hence making PHP a viable option to be used in SOA implementations.

WSO2 WSF/PHP is a PHP extension that is written in C programming language. It is built on WSO2 Web Services Framework for C, which in turn is built on Apache Axis2/C Web services engine and the related family of projects.

 

WSO2 WSF/PHP Architecture 

The service and client APIs are analogous to PHP5 SOAP extension, however, they not the same given that it supports more Web services specifications compared to the basic SOAP and WSDL support in the PHP5 SOAP extension. Ability to send binary attachments and WS-Security are the most sought after features in today's Web services stacks; WSO2 WSF/PHP is the only option available in PHP when it comes to those features.

 

 

Installation

 

There are various options available when installing WSO2 WSF/PHP. Linux and Microsoft Windows platforms are supported and you have the option of installing either form the binary or building form source distribution.

Windows binary distribution is available as a zip archive. For Linux binaries, based on the flavor of your distribution, you can choose to install form deb packages or rpm. If there is no binary package for your preferred Linux distribution, you can choose to install form source package. Starting form WSO2 WSF/PHP version 1.2.0, released January 2008, in addition to the binaries build for open source PHP5 distribution, binaries for Zend Core 2.5 are also available. For those pecl fans, there is also a pecl compatible source package available. You can download the distribution package to suite your platform and taste form the download page.

There is a comprehensive installation guide available for both on line and packaged distributions. Please refer to this guide on specific information in installing WSO2 WSF/PHP.

 

Configuration and Deployment

Configuration parameters and deployment information are also available in the installation guide. The following table lists the configuration parameters of WSO2 WSF/PHP, that are to be added to the php.ini file:

php.ini entry

Description

Default value

wsf.home

Path where WSO2 WSF/C is installed.

INI_STR ("extension_dir")/wsf_c

wsf.log_path

Path to the folder into which log files are to be written.
For services, the log will be written to a file named “wsf_php_server.log” and for clients “wsf_php_client.log”.

“/tmp”

wsf.log_level

Log level. The available log levels and their respective meaning are as follows:

0 - critical errors

1 - errors

2 - warnings

3 - information

4 - debug

5 - user

4

Note, that if you are a Windows user, you must set the log_path because the default folder “/tmp” would not be available on Windows.

There are few simple deployment steps required to get WSO2 WSF/PHP up and running. As mentioned earlier, they are detailed in the installation guide. However, here's a brief on the steps required:

  1. If not already set, make sure entension_dir entry is set in php.ini
    extension_dir ="./ext"

  2. Enable php_xsl extension in php.ini (This is required for WSDL generation)
    extension = php_xsl.dll

  3. Add the wsf extension entry in php.ini
    extension=wsf.dll

  4. Add the scripts folfder to include_path in php.ini (scripts folder comes with your package, look inside the folder where you extracted your WSO2 WSF/PHP package)
    include_path = ".;/path/to/scripts/folder"

  5. Copy the samples folder to your Web server's document root (samples folder also comes with your package).

     

First PHP Web Service

There is a "Hello world" sample given in the quick start section of the WSO2 WSF/PHP manual. Hence, this section would introduce you to a new simple service as your first service, namely “Who is there?”.

The concept is very simple, well, too simple. The client says “Knock, knock!!!” and the service responds asking “Who is there?”.

 

 

 

The above diagram depicts the messages exchanged. The following code implements the Web service:

 

  1. <?php
  2.  
  3. function knock($message) {
  4.  
  5. $responsePayloadString = <<<XML
  6.         <knockResponse>Who is there?</knockResponse>
  7. XML;
  8.  
  9. return $responsePayloadString;
  10. }
  11.  
  12. $service = new WSService(array("operations" => array("knock")));
  13.  
  14. $service->reply();
  15.  
  16. ?> 

This code could be broken down to three main logical parts:

  1. Function implementing the service operation (lines 3 to 10)

  2. Creating service instance (line12)

  3. Replying to client requests (line 14)

We are implementing a Web service with this code. Each service should have at least one operation exposed to be consumed by clients (otherwise, it is not a service). Operations can be implemented as functions and then mapped to service operations.

In this Web service, we have one operation named knock. As you can see on line 12, when the WSService instance is created, the set of operation could be given as an array. In this example, we have only one operation, hence there is only one element given in the operation's array.

In this example, the function that implements the operation knock is function knock. This function takes an input parameter (line 3). This input parameter contains the request sent by the client, however, in this example, we are not interested in the content of the request hence are not looking into incoming message parameter. The logic implemented in the knock is very simple, we define the XML string to be returned as response (lines 5 to 7) and return the response XML string (line 9).

The call to reply() method of the WSService instance (line 14) triggers processing when there is a request form a client. It will locate the function implementing the invoked service operation, call the function with incoming request content and prepare a response using the value returned by the function called. All these happen transparent to the user.

To deploy the service, name the service script service.php and copy the service script to your Web server's document root. To make things tidy, rather than just copying to the top document folder, lets create a folder structure “tutorial/first” and copy the service to that folder. This means that the endpoint address of the service would be http://localhost/tutorial/first/service.php

To test your service to see if it works, you can access the endpoint address of the service with the Web browser. You will get an output like the following:

 

Deployed Services

tutorial|first|service.php

Available Operations

  • knock

You can also test the service by accessing the WSDL for the service. For example, access the following URL with the Web browser: http://localhost/tutorial/first/service.php?wsdl

 

Consuming First PHP Web Service

Now we have a working service, the next step would be to write a PHP client to consume this Web service. As mentioned in the earlier section, the client is going to invoke the knock operation of the service. Here is the code for the client:

 

  1. <?php
  2.  
  3. $reqestPayloadString = <<<XML
  4. <knock>Knock, knock!!!</knock>
  5. XML;
  6.  
  7. $client = new WSClient(array("to" => "http://localhost/tutorial/first/service.php"));
  8.  
  9. $response = $client->request($reqestPayloadString);
  10.  
  11. echo "Service replied asking: '".$response->str."'\n";
  12.  
  13. ?>

As in the case of the service, the client code too is very simple. The steps used in the client when consuming the service could be summarized as follows.

  1. Create the client instance with the service endpoint address (line 7)

  2. Send the request with the request message (line 9)

  3. Process the received response (line 11)

In this Web service client, when the WSClient instance is created, in line 7, we provide the endpoint address of the service we want to consume as the to option. The address used in this sample is the address of the service that we deployed in the previous section.

Form lines 3 to 5, we define the XML string to be sent as the request.

On line 9, the call to request() method of the WSClient instance, with the request XML string as a parameter, triggers the service invocation. Upon the call to request() method, Web service client forms the request message with the given XML string, sends the request to the service given in the to address and receives the response and stores the response in the WSMessage instance named response. You can access the incoming response as an XML string using the str member variable of the WSMessage instance.

To deploy the client, name the client script client.php and copy the script to your Web server's document root. To make things tidy, as in the case of the service, lets place the client in the folder structure “tutorial/first”. This means that the URL of the client would be http://localhost/tutorial/first/client.php

To test the client, you can access the above URL with the Web browser. The output would look like the following:

Service replied asking: 'Who is there?'

Now you have learned how to provide Web services and consume those Web services with clients. I will discuss more information on clients and services in a future tutorial. In the mean time, for more information on WSService, WSClient and WSMessage APIs, you can refer to the WSO2 WSF/PHP API documentation.

 

Summary

This tutorial introduced WSO2 WSF/PHP, the most comprehensive Web services extension for PHP available today. Web services can be implemented using the WSService API and consumed through WSClient API. The service and client examples given in this tutorial are the simplest forms of client and service implementations possible with WSO2 WSF/PHP. This tutorial introduced the minimal steps required to get a service and a client up and running.

 

Resources

Download source code for the factorial sample.

 

Links

 

Author

Samisa Abeysinghe is a Software Architect at WSO2. He is a member of Apache Software Foundation and a project management committee member of the Apache Web services project. He is one of the pioneering members of the Apache Axis2/C project.

samisa at wso2 dot com.

 

About Author

  • Samisa Abeysinghe
  • VP, Training
  • WSO2 Inc.