Developing SOAP Web Services with PHP

Introduction

The goals of this research were:

1. Learn what a web service is.
2. Learn what SOAP is.
3. Learn how to consume PHP/SOAP web services from a PHP website and from a Windows desktop application.

Implementation Notes

The NuSOAP/PHP implementation (Web service) can be found here: http://www.jpreece.com/customerswebservice/index.php

The WSDL document for the web service can be found here: http://www.jpreece.com/customerswebservice/index.php?wsdl

1.0 What is a web service?

"A web service is defined by the W3C as "a software system designed to support interoperable machine-to-machine interaction over a network".

"Web services are frequently just Internet Application Programming Interfaces (API) that can be accessed over a network, such as the Internet."

A web service is simply a standard means of communication between two machines over a local or wide-area network (such as the Internet), regardless of host platform or software language. A web service is a set of API's that provide data to a client application in a standard way. This data can be transferred over the network using a combination of (typically) HTTP, a supporting hypertext processor (such as PHP), and a communications protocol such as SOAP.

2.0 What is SOAP?

SOAP is a standardized means of transferring data between two machines in a client-server configuration. SOAP is a W3C standardized (W3C, 2004) means of communicating with a web service across a network (local or Internet).
"SOAP is an XML-based messaging protocol."

SOAP messages (envelopes) are formed in XML, itself an open W3C standard. The client must haves an XML parser to interpret the document. XML is platform and programming language independent so it can be used by a wide range of computer systems. As SOAP is just a standard and not a process, it is not limited to any particular protocol (although HTTP is commonplace).

2.1 SOAP envelopes

A SOAP envelope is an XML document that is sent between the client and the server, which contains the request/response data. The document has 3 main elements: (w3schools, 2009)

• Envelope

Contains scheme and encoding data
 
• Header
  
  Contains ID, source, destination data
   
• Body
  
  Contains request/response data (Silver Spoon Sokpop, 2009)

One of the main goals of implementations of SOAP (like NuSOAP) is to encapsulate the process of creating SOAP envelopes to ensure compatibility and compliance with the SOAP specification.

2.2 What is WSDL and why is it important to SOAP/Web Services?

"WSDL is a document written in XML. The document describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes."

WSDL (Web Service Description Language) defines the web service and available methods to the client. This applies to all clients no matter from what context they are consuming the application.

The WSDL document also defines the following:

• The methods arguments
• The arguments data types
• Return value data type
• Port and binding data.

Example structure of a WSDL document:

<definitions>
 
<types>
definition of types
</types>

<message>
definition of a message
</message>

<portType>
definition of a port
</portType>

<binding>
definition of a binding
</binding>

</definitions>

WSDL documents are very important to web services (and SOAP) because it is effectively a protocol that defines in very clear detail how the client will interact with it. A WSDL document also eliminates guess work and long laborious documentation. WSDL language is not easily readable by humans (despite being written in XML), especially when they get long. There are now several implementations of SOAP that ease the process and enable rapid application development. One example of this is NuSOAP.

2.3 What is NuSOAP?

The most viable PHP implementation of SOAP seems to be Dietrich Ayala's SOAPx4, also known as NuSOAP" (Apple Inc, 09)
NuSOAP is a collection of classes that allows for rapid development of SOAP enabled PHP web services. NuSOAP is not a technology in itself, in the sense that it does not require any reconfiguration on the server, but rather acts as a middle man to ease the application development process.

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the server instance
$server = new soap_server;
// Register the method to expose
$server->register('hello');
// Define the method as a PHP function
function hello($name) {
    return 'Hello, ' . $name;
}
// Use the request to (try to) invoke the service
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
$server->service($HTTP_RAW_POST_DATA);
?>

The above example demonstrates a NuSOAP server with one method that returns the same value that was passed to it (as a string).

Walkthrough:

• Reference the NuSOAP implementation
• Create a new instance of the server object, and name it.
• Register the method "hello" with the server object.
• Write the corresponding method and make it do "something". (In this case, return the same string that was originally passed to it).
• If [when] there is post data, pass it to the server object and do something with it.

The code above is as basic as a NuSOAP example gets, but it shows clearly the steps required to start making use of SOAP without having to write (or even fully understand) the implementation yourself.

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the client instance
$client = new soapclient('http://localhost/phphack/helloworld.php');
// Call the SOAP method
$result = $client->call('hello', array('name' => 'Scott'));
// Display the result
print_r($result);
?>

The client code is similar by design. Even though this example uses only PHP, it is possible to access the server using virtually any other language.

Walkthrough:

• Reference the NuSOAP implementation
• Create an instance of the SOAPClient and specify the remote path of the web service.
• Call the desired method and pass an argument (called 'name').
• The web service responds (if request is valid) and prints the result to the screen.

The disadvantage of using third party implementations is that debugging and error handling is more difficult, as you have no knowledge of the underlying code.

3.0 Consuming SOAP/PHP web services

There are many ways to consume SOAP/PHP web services. This section focuses only on consuming a web service through a Windows Forms (C#) application, although any programming language that supports XML Soap web services is compatible.

3.1 Windows Forms Application

Microsoft Visual Studio has extensive support for SOAP/XML web services. The Microsoft .NET framework (version 1.1 and higher) has a built in object that can be inherited to provide access to the web service without need for understanding XML or reading XML documents.
Object: SoapHttpClientProtocol (Microsoft MSDN, 2010)

3.1.1 How to consume a web service in Visual Studio 2008

To connect to the web service:

• Open Visual Studio 2008
• Create a new project (C# or VB.NET, the process is the same)
• In the solution explorer, right click References, then click "Add Web Reference"
• Type the address to the Web Services Descriptor Language (WSDL) document. I.e;
  
  http://www.jpreece.com/customerswebservice/index.php?wsdl
   
• Click 'Go'
• Visual Studio will now retrieve the WSDL document and display the available methods to you.
• Give the reference a sensible name, such as "CustomersLookup"
• Click "Add Reference"

To invoke the service:

• Go to your code, i.e. the load event.
• Create a new instance of the CustomerLookup class (generated automatically for you) 

CustomersLookup.CustomerLookup cl = new CustomersLookup.CustomerLookup();

  

• Invoke a method as provided by the WSDL
  
  Customer[] c = cl.GetAllCustomers();

Note: This is an example; the code you type is dependent on the methods exposed by your web service.

4.0 Brief Critique

The objectives of this research were to learn what PHP/SOAP was and how it can be consumed from a Windows desktop application.
Two projects have been produced to support this research. (See Implementation notes at the start of this document for the web service details)
The applications support the research because of the following;

Web service:

• The web service implements NuSOAP, which itself is an implementation of SOAP
• NuSOAP is written in PHP, as is the code that makes use of the NuSOAP implementation

Desktop application:

• Consumes all features of the web service itself, and makes use of all data retrieved by making calls to the web service
• Desktop application makes use of the WSDL to describe classes and variables within the code.

The desktop application fully implements the web service. However, the web service could be expanded to provide more methods that return simple and complex types, as well as requiring simple/complex types as arguments. The web service could be improved by writing more supporting documentation within the WSDL as to what each method does, what arguments it requires and what it returns. The desktop application could be improved in the same way.

The web service is very relevant to developers because it provides a cross platform/browser means of communication between an application and a server.

The concept of using a web service to provide an application with data is one that most developers can find useful. Web services can be used, for example, to synchronize data across all of the user's devices regardless of type (laptop, desktop, mobile, smart) or operating system (Windows mobile, android, Symbian)

Bibliography

Answers.com. (2009, Nov 21). Web Services: Definiton from Answers.com. Retrieved Nov 21, 2009, from Answers.com:

http://www.answers.com/topic/web-service

Apple Inc. (09, Nov 21). Using SOAP with PHP. Retrieved Nov 21, 09, from Apple Developer Connection:

http://developer.apple.com/internet/webservices/soapphp.html

Microsoft. (2009, Nov 21). Anatomy of an XML Web Service Lifetime. Retrieved Nov 21, 2009, from Microsoft MSDN: http://msdn.microsoft.com/en-us/library/x05s00wz%28VS.80,loband%29.aspx

Microsoft MSDN. (2010, 01 01). SoapHttpClientProtocol Class (System.Web.Services.Protocols). Retrieved 01 12, 2010, from MSDN:

http://msdn.microsoft.com/en-us/library/system.web.services.protocols.soaphttpclientprotocol.aspx

Nichol, S. (2004, Nov 03). Introduction to NuSOAP. Retrieved Nov 21, 2009, from Scott Nichol: http://www.scottnichol.com/nusoapintro.htm

Silver Spoon Sokpop. (2009, Oct 9). File:SOAP.svg. Retrieved Nov 22, 2009, from Wikipedia: http://en.wikipedia.org/wiki/File:SOAP.svg

SoapUser.com. (2009, Nov 21). SOAP Basics 1: What is SOAP? Retrieved Nov 21, 2009, from SoapUser.com:

http://www.soapuser.com/basics1.html

W3C. (2004, Jan 01). SOAP Specifications. Retrieved Nov 22, 2009, from W3C: http://www.w3.org/TR/soap/

w3schools. (2009, Nov 21). Introduction to WSDL. Retrieved Nov 21, 2009, from w3schools: http://www.w3schools.com/WSDL/wsdl_intro.asp

Zend.com. (2004, March 16). PHP SOAP Extension. Retrieved Nov 21, 2009, from Zend.com: http://devzone.zend.com/article/689