WSO2
CONTACT
20 Aug, 2007

WSO2 WSF/PHP – PHP Web Services Extension

WSO2 WSF/PHP is an open source project. It is distributed under the Apache License version 2.

WSF/PHP WSO2 WSF/PHP is based on WSO2 WSF/C, another open source project that implements a comprehensive Web services framework in C. WSF/C is an enterprise grade framework for providing and consuming services, based on the Apache Axis2/C family of Web services projects.

WSO2 WSF/PHP supports SOAP 1.1 and SOAP 1.2. It is also capable of supporting REST style invocations. Though it is primarily focused on SOAP style services and clients with comprehensive WS-* support, you also have the provision of using plain old XML style REST invocations. Any given service can be exposed both as a SOAP style service as well as a REST style service.

On the server side, based on the format of the request sent by the client, the services will respond either with SOAP or REST. On the client side, you can choose between the SOAP and REST style. SOAP requests use HTTP with the POST method. REST can be invoked using both HTTP POST and GET methods.

WSO2 WSF/PHP Structural Overview
WSO2 WSF/PHP Overview

 

WSDL Support

WSDL support in WSO2 WSF/PHP is two fold. It supports both contract first as well as code first methods. You can write the code for a service, and then generate the WSDL through a '?wsdl' request; this is known as the code first method. You can also use a given WSDL and implement your client or service based on that WSDL; this is known as the contract first method.

WSDL generation is supported through annotations given in doc comments. In a Web service PHP script, you can have specially formatted doc comments explaining the service interface. The WSO2 WSF/PHP engine is capable of interpreting those comments and generating the WSDL. If the doc comments are missing, WSDL generation will still happen to match the method signatures with some pre-defined assumptions.

The contract first method of service and client implementations are supported through the WSDL mode.

Attachments with MTOM

WSO2 WSF/PHP supports sending binary attachments with SOAP messages with SOAP MTOM implementation. There are two modes of operations supported when sending binary attachments with SOAP messages. One is the binary optimized mode, where the attachment is sent as it is, out of the SOAP message. For example, emails with attachments, with a reference to the attachment in the SOAP body to help locate the attachment using MIME headers. The other mode is non-optimized mode, where the attachment is converted to a Base64 string and sent embedded in the SOAP message. Both these forms are supported by WSF/PHP.

WS-Addressing

WS-Addressing is meant to address the SOAP messages. WS-Addressing is used by many other specifications. For example, reliable messaging specification. Hence it is mandatory for any Web services framework.

WS-ReliableMessaging

WSO2 WSF/PHP is the only PHP extension that supports Web services reliable messaging with PHP, and thus becomes historic in that space. Basic SOAP message reliability as well as reliable messaging with binary attachments have been tested.

WS-Security and WS-SecurityPolicy

Basic security with security tokens sent in the SOAP header, as well as signing and encrypting, is supported with the WS-Security implementation in WSO2 WSF/PHP. You can use basic security scenarios, with provision to use policy files that adhere to the WS-SecurityPolicy specification. The security API lets you use basic policy based options, and even supports providing a security policy file. WSO2 WSF/PHP creates history in this space too, becoming the first ever PHP extension to provide comprehensive WS-Security support.

Classes and Programming Model

When using WSO2 WSF/PHP, you have the option of using either an object oriented programming model or a function based procedural model.

With the object oriented model, there are seven classes, out of which, four classes can be considered as the core classes.

WSO2 WSF/PHP Class Diagram
WSO2 WSF/PHP Class Diagram

WSClient

The WSClient class can be used to consume Web services. In other words, this class is the base class that can be used to implement Web services clients. The constructor takes an array of options, that can be used to control client behavior. Some of the options include whether the service endpoint is to be consumed by the client, whether to use SOAP style invocations or REST, the SOAP version to be used, etc.

There are two methods. The member function request can be used to invoke two way operations and the member function send can be used to invoke one way operations. Both methods take the payload to be sent to the service as a parameter. For user convince, the API has been defined such that the payload can be provided in several formats. Please refer to the API documentation for more information.

WSService

The WSService class can be used to provide Web services. In other words, this class is the base class that can be used to implement Web services. Like in WSClient, the constructor takes an array of options that can be used to control the service behavior. Some of the options include an array of operations to function mappings, WS-Addressing mapping to operations, etc.

There is one method in the WSService class, named reply. This member function can be used to instruct the service to process the incoming client requests, and invoke the necessary functions in line with the provided options to formulate the response and send the response to the clients.

WSMessage

The WSMessage class represents a message passed between a client and a service. This class encapsulates the XML payload in various formats in addition to the other properties related to a message. The constructor takes this payload as a parameter and also an optional parameter representing message level options such as WS-Addressing and MTOM related options. This class is a data class, which means that there are no member functions in this class. The member variables of this class can be used to access the payload and MTOM attachment related information associated with the message.

WSFault

The WSFault class can be used to represent SOAP faults. The constructor takes the fault code, fault reason, fault role and fault detail as parameters. There are member variables to represent the fault information. You can use the __toString method to access the fault information as a string.

The above classes are the main classes in the object oriented model of WSO2 WSF/PHP. There are three more classes that can be used in special use cases.

WSPolicy

The WSPolicy class can be used to represent WSPolicy objects. The user is provided with various options to construct the policy object, using different forms of parameters to match the user's needs. This is a data class, which means that there are no methods in this class.

WSSecurityToken

This class can be used to logically represent security properties, either on the server side or on the client side. The security properties can be passed as an array of options to the constructor. The options that can be provided include username, password, various security certificates, etc. This too is a data class.

WSClientProxy

The WSClientProxy can be used on the client side as the proxy for invoking services. This class is useful in the WSDL mode of clients where the user can use the WSDL of a service to invoke the service. The WSO2 WSF/PHP engine will generate the client proxy that the user can use to invoke the operations in a given WSDL. For more information, please refer to the WSDL mode API documentation.

Procedural Model

With the procedural model, there are several functions to help achieve the objectives of providing and consuming services.

The ws_request function can be used to consume two way service operations. It takes the payload and an options array as parameters.

The ws_send function can be used to consume one way service operations. It too takes the payload and an options array as parameters.

Both ws_request and ws_send are to be used on the client side.

The ws_reply method can be used to provide services. This is to be used from the service side. This function takes an array of options as parameters, processes the request, and sends the resulting response.

Why use WSO2 WSF/PHP?

Being a PHP extension, it is very easy to use. All that a user needs to do is to put the lib files in the PHP extensions folder (which is done by the installation process), add a few lines to php.ini (again this would be done automatically, if you use an rpm or deb installation) and copy the scripts and samples to the Web root.

WSO2 WSF/PHP is an open source project. Hence it carries all the benefits of an open source project.

The people behind this project are Web services experts. Most of the developers of the project are involved with Apache Axis2/C and WSO2 WSF/C. That helps to ensure that this implementation is technically sound and also ensure that the problems encountered are solved quickly, effectively and in sync with Web services principles and specifications.

WSO2 WSF/PHP is a complete Web services stack. It is the only PHP extension that supports so many WS-* specifications. Because of the design underneath, this extension is extensibile in terms of adding new WS-* specifications support, and any new specification supported by WSF/C can be made to work with WSF/PHP. It has been tested for interoperability with .NET and Java implementations such as WSO2 WSAS and proven to inter-operate not only at basic SOAP level, but also with MTOM, WS-Security and WS-ReliableMessaging.

Being a comprehensive Web services framework, this extension enables the luxury of using PHP in SOA implementations. This would be very useful when integrating PHP legacy systems into the enterprise SOA. Hence WSF/PHP is a very useful SOA enabler in the PHP world.

There is a backward compatibility layer implemented in WSO2 WSF/PHP to support the same API as in the PHP5 SOAP extension. This is to facilitate the use of the old Web services client and service scripts with the new extension. However, it is advised that you migrate to the native API of the WSF/PHP extension because that has been designed to match the WS-* norms.

 

References

 

Author

Samisa Abeysinghe, Software Architect, WSO2 Inc, samisa at wso2 dot com

 

 

About Author