Introduction
The goals of this research were:
- Learn what a web service is.
- Learn what SOAP is.
- 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)
BibliographyAnswers.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