What is WSDL?

Before we start, let’s talk a bit about what WSDL is. (Warning: I am very new to WSDL, SOAP and web services in general, so feel free to correct me if I get any of these details wrong).

WSDL stands for Web Service Description Language. As the name suggests, it is an XML language used for describing web services. By describe, I mean a WSDL file contains information like the functions that a client can call, and data types it uses, and what exceptions it might throw. This is useful for clients that might contact the web service. Exactly why that information is useful will become evident in examples below.

What is SOAP?

At one point, a long time ago, in a web far far away, SOAP stood for Simple Object Access Protocol. Now it stands for nothing. SOAP is a protocol for exchanging structured information on the web. Like WSDL, SOAP uses XML. In fact, SOAP is a protocol often used to exchange WSDL information, although one can also use straight HTTP to do it as well.

All we really need to know (right now) is that a SOAP library permits us to communicate with a WSDL web service that has SOAP bindings (which would be almost any we would encounter in the wild).

Which library/module to use?

In order to determine which library to use, I did some googling. What I found were two options: the NuSOAP library and the PHP SOAP module.

So which one should we use? I initially leaned towards NuSOAP due to the fact that it was an external library, and thus would probably work with almost any PHP installation. Unfortunately, after perusing the NuSOAP Sourceforge website, I noticed the library hadn’t been updated since 2005 (a bad sign). In fact, after further reading, I discovered that, as of PHP 5, the NuSOAP namespace also conflicted with the PHP SOAP module namespace (and hadn’t yet been fixed). As a result, I decided to go with the PHP SOAP module.

The Code

The first thing anyone needs to do when consuming a WSDL service with PHP is to create a new client object. By creating a client object, PHP basically reads the server’s WSDL file and determines which functions are available to us. A SoapClient is created using the following code:

1
2
3
4
5
6
7
8
9
10
11
12

<?php
  // The path to the WSDL web service.
  $wsdl = "http://path/to/webservice.wsdl";
 
  // The connection options.
  $options = array('features' => 
    SOAP_USE_XSI_ARRAY_TYPE + SOAP_SINGLE_ELEMENT_ARRAYS);
 
  // Create a new SoapClient.
  $client = new SoapClient($wsdl, $options);
  echo "SoapClient creation successful<br>\n";
?>

So what’s going on at line 7? Those two features are basically used to make the SoapClient act as we’d expect. For example, if you don’t include the SOAP_USE_XSI_ARRAY_TYPE feature, then you’ll find you get a lot of casting exceptions when dealing with a Java-based webservice that uses any complex data structures. If you don’t include the SOAP_USE_XSI_ARRAY_TYPE feature, then PHP will turn 1-element arrays return types into objects, which is not what you want 90% of the time and often gives confusing results.

Now let’s actually consume a web service. Let’s pretend we’re using the J2EE service provided by this article. Here are the contents of the WSDL file from that article:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="MyFirstService" targetNamespace="urn:Foo" xmlns:tns="urn:Foo"
    xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <types/>
  <message name="MathFace_add">
    <part name="int_1" type="xsd:int"/>
    <part name="int_2" type="xsd:int"/></message>
  <message name="MathFace_addResponse">
    <part name="result" type="xsd:int"/></message>
  <portType name="MathFace">
    <operation name="add" parameterOrder="int_1 int_2">
      <input message="tns:MathFace_add"/>
      <output message="tns:MathFace_addResponse"/>
    </operation>
  </portType>
  <binding name="MathFaceBinding" type="tns:MathFace">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
    <operation name="add">
      <soap:operation soapAction=""/>
      <input>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
		    use="encoded" namespace="urn:Foo"/>
      </input>
      <output>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
		    use="encoded" namespace="urn:Foo"/>
      </output>
    </operation>
  </binding>
  <service name="MyFirstService">
    <port name="MathFacePort" binding="tns:MathFaceBinding">
      <soap:address location="http://localhost:8080/math-service/math"/>
    </port>
  </service>
</definitions>

What can we tell about the web service by looking at this file? Well the first thing you should notice is lines 12-14. In those lines, the web service defines an operation (“add”) that takes two arguments (“int_1 int_2″). As a result, we know that the web service exposes an add operation that takes two integer arguments. Let’s use that knowledge to invoke the add operation in PHP using the SOAP module:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<?php
  // The path to the WSDL web service.
  $wsdl = "http://localhost:8080/math-service/math?wsdl";
 
  // The connection options.
  $options = array('features' => 
    SOAP_USE_XSI_ARRAY_TYPE + SOAP_SINGLE_ELEMENT_ARRAYS);
 
  // Create a new SoapClient.
  $client = new SoapClient($wsdl, $options);
  echo "SoapClient creation successful<br>\n";
 
  // Call the add operation.
  $response = $client->add(2, 2);
 
  // This should print 4.
  echo $response . "<br>\n";
?>

How’d the PHP object $client know to have an add method? It simply read the WSDL file the same way we did, and realized that the web service exposed that operation.

As you can see, consuming a J2EE web service from a PHP client is not too complicated. Once you understand the rudiments of a WSDL file and the PHP SOAP module, calling remote functions becomes a snap.

The String Concatenation Approach

Whatever your reason is for generating HTML, the best bet is your first prototype looked something like this:

(Aside: All this code is in VB.NET… the original VB.NET (i.e. not 2005 or later). It also assumes ASP.NET 1.1. This is because the client I work for still uses this technology, so all my experience is with it. The code should still be fine though, as all versions of .NET after 1.1 are more or less backwards compatible.)

' Run some query on the database.
Dim dataTable As DataTable = Query()
 
' Dump it into an HTML document.
Response.Write("<html>" + Environment.NewLine)
Response.Write("<head><title>Database Table</title></head>")
Response.Write(Environment.NewLine)
Response.Write("<body>" + Environment.NewLine)
Response.Write("<table>" + Environment.NewLine)
 
' Print the rows.
For Each row As DataRow In dataTable
  Response.Write("<tr>")
  ' Print the cells.
  For Each item As Object In row
    If IsDBNull(item) = False Then
      Response.Write("<td>" + CStr(item) + "</td>")
    Else
      Response.Write("<td>&nbsp;</td>")
    End If
  End For
  Response.Write("</tr>")
End For
 
Response.Write("</table>" + Environment.NewLine)
Response.Write("</body>" + Environment.NewLine)
Response.Write("</html>" + Environment.NewLine)

Now don’t get me wrong, this code will do the trick. But as you write it, you start to feel a bit dirty. HTML is a language for representing hierarchies, yet you’re concatenating strings. You start to feel like there’s a more elegant way to do it, a way that takes advantage of the structure of HTML.

And there is.

The Programmatic Approach

Ok, so we want to take an approach that has some knowledge of the HTML we’re writing. Enter XML. .NET uses XML for, among other things, it’s Javadoc-like documentation generator and it’s ASP.NET config files. With XML so prevalent in .NET, it’s not surprising to discover that it’s part of the standard library, in the namespace System.Xml.

So you’re thinking “Cameron, who cares about XML, I want to make an HTML document!” Gear down, sugar plum, XML can still help! As you may or may not know, HTML (at least the XHTML dialects) is a reformulation of XML. That is, an XHTML document is an XML document. As a result, we can use .NET’s built-in XML support to generate an HTML document.

Thus, if we want to write the same code in previous example in .NET XML, we would do the following. First, we would need to make a new XML document. That’s easy enough:

Imports System.Xml
 
' Create a new XML document.
Dim xmlDoc As XmlDocument = New XmlDocument

Now we want to start writing some HTML. So let’s create our html tag and add some headers.

' Create the html tag.
Dim xmlRoot As XmlElement = xmlDoc.CreateElement("html")
xmlDoc.AppendChild(xmlRoot)
 
' Create the head tag and append it under the html element.
Dim xmlHead As XmlElement = xmlDoc.CreateElement("head")
xmlRoot.AppendChild(xmlHead)
 
' Create the title tag, set it's text to "Database Table"
' and append it under the head element.
Dim xmlTitle As XmlElement = xmlDoc.CreateElement("title")
xmlTitle.AppendChild(xmlDoc.CreateTextNode("Database Table"))
xmlHead.AppendChild(xmlTitle)

Wow, that’s a lot of code. What’s going on there? First, let’s look at the XmlDocument class. This is important when we’re generating XML documents. It’s what we use to create new elements. However, even though it creates new elements, it doesn’t add them to the document. Thus, we need to use the AppendChild method of the appropriate element to add it to the document. As you can see above, we created a root element (html) and added that to the XML document (xmlDoc) first. Then we created a head element, and added that to the root element, not the xmlDoc. This was done in order to form a hierarchy, which is, in essence, what a XML (and by extension HTML) document is.

Here is what the resulting XML/XHTML document would look like so far:

<html>
  <head>
    <title>Database Table</title>
  </head>
</html>

So far so good, let’s finish it off. Here’s the rest of the code we’d need to make our simple HTML document:

' Create the body element and append it to the root.
Dim xmlBody As XmlElement = xmlDoc.CreateElement("body")
xmlRoot.AppendChild(xmlBody)
 
' Create the table and append it.
Dim xmlTable As XmlElement = xmlDoc.CreateElement("table")
xmlBody.AppendChild(xmlTable)
 
' Create the rows.
For Each row As DataRow In dataTable
  Dim xmlRow As XmlElement = xmlDoc.CreateElement("tr")
  xmlTable.AppendChild(xmlRow)
 
  ' Create the cells.
  For Each item As Object In row
    Dim content As String = ""
    If IsDBNull(item) = False Then content = CStr(item)
    Dim xmlCell As XmlElement = xmlDoc.createElement("td")
    xmlCell.AppendChild(xmlDoc.createTextNode(content))
    xmlRow.AppendChild(xmlCell)
  End For
End For
 
' Write the XML/HTML document.
Response.Write(xmlDoc.OuterXml)

And there you have it: a programmatic way to generate an HTML document. So why bother? Here’s a few reasons:

Safety. If you generate your HTML document by concatenating strings, there’s a chance you might forget to close a tag. If you generate the document programmatically, you can ensure that all your tags will always be closed.

Maintainability and readability. I’ve had to deal with code where the HTML is generated by concatenation. It’s confusing and frustrating. If you generate your HTML documents programmatically, it’s a lot easier for a future programmer to follow what’s going on (especially if you, y’know, document it).

Reusability and modifiability. If you create your HTML document as a flat string, it makes it really hard to modify and reuse elsewhere in your code. For example, if you wanted to add a tag in the middle of your HTML document using the string concatenation method, you will have to do a lot of painful string manipulations. With the programmatic approach, it’s as simple as just calling AppendChild on the appropriate XmlElement.

Using an XmlDocument to represent an XML document just makes sense. It’s less crude and more versatile.