This article assumes you have read the first part of this series.

Before we start, we should take a step back and consider what we’re about to do. Our Searcher app has three parts:

• the client-side jQTouch UI,
• the client-side jQuery AJAX calls,
• the server-side PHP script (that could easily be backed by a database)

At this point we have finished the jQTouch UI. However, instead of immediately moving on to writing the jQuery AJAX calls, let’s start with the PHP script instead. This will help us understand our AJAX calls when it comes time to write them.

The PHP Script

Since our PHP script will be performing a search, let’s create a file called search.php and add a single line of boilerplate:

<?php

There’s no need for an end tag. In fact, in files containing only PHP, it is recommended that you do not include an end tag:

For files that contain only PHP code, the closing tag (“?>”) is never permitted. It is not required by PHP, and omitting it prevents the accidental injection of trailing white space into the response.

Our Searcher app needs to search for something, so let’s pretend it’s an interface for a music player and we’re searching for songs. In order to express that idea into PHP code, we need the following elements:

• a Song class to hold the artist name and the title,
• an array holding a bunch of Song objects,
• a function for searching the Song array,
• a way to get a search value from the AJAX request,
• a way to set the MIME type to JSON,
• a way to encode our Song array as JSON

First, we’ll need a class to hold the songs (place this starting at line 3 in search.php):

3
4
5
6
7
8
9
10
11

class Song {
    public $artist;
    public $title;
 
    public function __construct($artist, $title) {
        $this->artist = $artist;
        $this->title = $title;
    }
}

Let’s break it down for those not familiar with PHP classes:

• at line 3, we declare the class name
• at lines 4-5, we declare two public fields to represent the artist’s name and the title of the song,
• at lines 7-10, we declare the class constructor that we use to initialize the two fields of a Song object

Now that we have a way to model songs in our PHP script, we need to make an array of some dummy songs that we can query using AJAX:

13
14
15
16
17
18
19

$songs = array(
    new Song("Weezer", "Say It Ain't So"),
    new Song("Weezer", "Undone"),
    new Song("Cake", "Meanwhile, Rick James..."),
    new Song("The Stars", "Ageless Beauty"),
    new Song("Roy Orbison", "In Dreams")
);

Now we have something of a faux database setup. How will we search it? Why, with a search function, of course! Let’s write that now:

21
22
23
24
25
26
27
28
29
30
31
32
33
34

function search($songs, $value) {
    if (empty($value))
        return $songs;
 
    $matches = array();
    foreach ($songs as $s)
    {
        $matchArtist = stripos($s->artist, $value) !== false;
        $matchTitle = stripos($s->title, $value) !== false;
        if ($matchArtist || $matchTitle)
            $matches[] = $s;
    }
    return $matches;
}

So what does this function do? Let’s take a look line-by-line:

• at lines 22-23, we check to see if the search value is empty (i.e. an empty string or null). If that’s the case, then we just return all the songs
• at line 25, we declare the $matches array. This will contain all the songs that match the search value $value
• at line 26, we use a foreach loop to iterate through all the Song objects in the $songs array
• at lines 28-29, we check to see if the artist name or song title contain the search value $value
• at line 30-31, we add the Song object to the $matches array if it matches the artist name or song title
• at line 33, we return whatever matches (if any) we have found

Ok, so now we have a Song class, an array of Song objects, and a function that searches that array. What’s left in our PHP script? Well, as it stands, we have no way to interface with it. What we need to do now is have some sort of way to respond to the AJAX GET request that our Searcher app will send. To do that, we harness the awesome power of the $_GET superglobal:

36
37

$value = $_GET['value'];
$matches = search($songs, $value);

On the first line, we extract “value” parameter from the $_GET superglobal and assign it to the $value variable. The second line runs our search function on the $songs database and searches for songs that have an artist or title that contains the $value string.

We’re almost there! At this point we’ve managed to get an array of Song objects that match the passed search value. All we need to do now is return that PHP array of objects as a JSON-encoded array of objects. Let’s do that now:

39
40

header('Content-Type: application/json');
echo json_encode($matches);

The first line sets the the MIME type of an HTTP response. MIME types are a sort of meta data that is used to describe what sort of content is being returned. In this case, we are telling jQuery (or whatever client that issued the request) that we are returning content that is JSON formatted. The second line is a built-in PHP function that converts PHP types into a string containing their JSON counterparts. Basically, it allows us to encode our PHP objects into JavaScript and allow us to access them in a nearly identical way:

// PHP
array(
    new Song("Artist 1", "Title 1"),
    new Song("Artist 2", "Title 2")
);
 
// Becomes... (after json_encode)
// JavaScript
[
    { artist: "Artist 1", title: "Title 1" },
    { artist: "Artist 2", title: "Title 2" }
];

And we’re done the PHP script! If we want to test it, we can load execute the PHP file on our server and try different search values. For example, entering this URL should return a JSON array with two Song objects:

// URL
http://example.com/jQTouch-ajax-search/search.php?value=Weezer
 
// Response
[{"artist":"Weezer","title":"Say It Ain't So"},{"artist":"Weezer","title":"Undone"}]

The jQuery AJAX calls

The finish line is now in sight. We’ve successfully written our jQTouch UI and our PHP script. The last thing we need to do is write some jQuery AJAX calls to execute our search and load the results into our UI. In order to do that, we need to do the following:

• listen for the submission of the search form in the jQTouch UI
• when the submission happens, get the search value from the form and set it as a parameter in an AJAX call to search.php
• register a callback that will populate the jQTouch search results when the AJAX call completes

Let’s start with listening for the submit event on the search form. First, we’ll need to create a new JavaScript source file search.js and fill it with the following boilerplate:

(function($){
 
    // Put code here.    
 
})(jQuery);

What this boilerplate does is give our JavaScript script its own context so that can minimize leaking variables into the global JavaScript namespace. It also gives us access to the jQuery object in the convenient $ form, regardless of whether or not “no conflict” mode is enabled.

Recall in part 1 we defined an HTML search form that looked like this:

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

<form id="search" action="">
    <div class="toolbar">
        <h1>Search</h1>
        <a href="#" class="back">Back</a>
    </div>
    <ul class="rounded">
        <li><input type="text" name="search-text" placeholder="Search" id="search-text" /></li>
    </ul>
    <ul class="edgetoedge" id="search-results">
        <li class="sep">Results</li>                
    </ul>
</form>

Note that on line 1 we defined the id of the form as search. We’ll use that to find the form and register a handler for its submit event so that we can take action when someone tries to perform a search using the jQTouch UI.

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

(function($){
 
$(function(){
 
    $("#search").submit(function(event, info) {
        var text = $("input[id=search-text]", this);
        text.blur();
 
        var results = $("#search-results", this).empty();
        results.append($("<li>", {
            "class": "sep",
            text: 'Results for "' + text.val() + '"'
        }));
 
        $.get("search.php",
            { value: text.val() },
            function(data) {
                $.each(data, function(i, song) {
                    var str = song.artist 
                        + " - "
                        + song.title;
                    $("<li>")
                        .text(str)
                        .appendTo(results);
                });
            }
        );
 
        return false;       
    });
 
});
 
})(jQuery);

There’s a lot there, so let’s break it down line-by-line:

• starting at line 3 and ending at line 32 we have the jQuery ready handler which is run once the DOM has finished loading
• starting at line 5 and ending at line 30 we bind a submit event handler to the submit event for the #search form
• at lines 6-7, we retrieve the search-text element, assign it to a variable (for later use on line 16), and then blur (i.e. deselect) the element so that the iPhone keyboard will go away
• at lines 9-13, we clear any previous items in the list that may be hanging around from a previous search and then load in a new separator (“sep”) that contains the search value
• at line 15-27, we perform our AJAX GET request to search.php with the value of the search text field as our value parameter (line 16) and a callback that adds the results to the list (lines 17-26)
• finally, at line 29, we return false to prevent the default form behaviour (i.e. submitting the form) from being carried out

And we’re done. All we need to do now and include search.php in the header of index.html so that it’ll be run:

12

<script src="search.js" type="application/x-javascript" charset="utf-8"></script>

Conclusion

In this, the final installment of How to do an AJAX search with jQTouch, we finished off the example application we started in the first part of this series.

In part 1, we covered building a UI using jQTouch. In part 2, we helped visualize our problem by pretending that we were writing a front-end UI to a server-side music player. To do that, we jumped into server side programming with PHP to write a script to serve us JSON-encoded Song objects. Once we had that setup, we moved back into JavaScript. In order to make use of the PHP script, we wrote a jQuery handler to respond to a jQTouch form submission. The handler, once triggered, issued an AJAX call to the PHP script to pull down the appropriate Song objects for display in our UI.

What Now?

With respect to the goals of this tutorial, nothing. However, if you want to pimp up the application a bit more, some things you could do are:

• Add genres and albums to the PHP Song object and then make the jQTouch UI menu have two additional options: Genres and Albums
• Try to make a Now Playing sub-menu that is activated when a Song is picked from the Search screen

Source

The source code I have written in this article is public domain, and you are free to do what you will with it. Here is a zip of the source, along with the required jQTouch source. It should work pretty much right out of the box.

Let’s start with a question: how does WordPress associate templates? The answer: as a secret custom field. What’s a custom field, you ask? They’re those useful little suckers under the content area in the WP editor:

But if the template is a custom field, you ask, then how come I don’t see it down there? Well, I just said they’re secret. After poking around WP database, I discovered the template for a page is determined by the custom field name _wp_page_template. My suspicion is that anything with the prefix _wp is hidden from the WP admin area and therefore secret.

Harnessing the awesome power of custom fields

On the bright side, even if you can’t see the _wp_page_template in the custom fields area, I can assure you it’s still there. And if it’s there, you can use it in any of your nefarious schemes.

Query_posts provides 3 parameters relating to custom fields: meta_key, meta_value, and meta_compare. With those in mind, imagine you have a template called Profile (profile.php), and you want to exclude any page that is a Profile from our query. In order to do that, you’d would make a query_posts call like so:

query_posts(array(
    'post_type' => 'page',
    'meta_key' => '_wp_page_template',
    'meta_value' => 'profile.php',
    'meta_compare' => '!='
));

The main thing to note here is that the template is identified by the name of the PHP file (profile.php) and not by the the name of template (Profile).

Wrap-up

Filtering your query_posts query by template is as easy as filtering by any custom field. No plugin required. Just remember: use the PHP file name as the template identifier, not the template name.

Consider a simple interface for making objects comparable:

interface IComparable {
     public function compareTo($object);
}

Normally, in Java and C# (before 4.0) the only way to implement this interface would be to make a carbon copy of the method signature (save for the name of the parameter) and then fill in the method body.

class NetString implements IComparable {
     public function compareTo($object) {
          ...
     }
}

This satisfies the interface requirements because we need to have a method that responds to a method named compareTo with a single argument. However, things get interesting when we introduce optional parameters. That’s because we can write a method signature that is different from that found in the interface but still satisfies the requirement that the method have the correct name and accept only 1 parameter.

How is that possible? Well, imagine we wanted our NetString class to optionally ignore case when comparing:

class NetString implements IComparable {
     public function compareTo($object, $ignoreCase = false) {
          ...
     }
}

Notice how we slipped in another (optional) argument $ignoreCase? Does this code still satisfy the IComparable interface? Absolutely. Why? Because we can still call compareTo($object) in a meaningful way, and that’s all the matters.

Extension methods enable you to “add” methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. Extension methods are a special kind of static method, but they are called as if they were instance methods on the extended type. For client code written in C# and Visual Basic, there is no apparent difference between calling an extension method and the methods that are actually defined in a type.

In this article, I will show you how to write a base class that will allow you to add methods to any PHP class that inherits from it at runtime. You will be able to call these methods transparently, without any special syntax.

For those unfamiliar with .NET, I’ll explain extension methods in a PHP context. For example, consider the following code for a limited .NET-style string class in PHP:

final class NetString {
   private $value;
   public function __construct($str)  {
      $this->value = $str;
   }
   public function toUpper() {
      return new NetString(strtoupper($this->value));
   }
   public function string() {
      return $this->value;
   }
}
 
$str = new NetString("foo");
$upper = $str->toUpper()->string();
// $upper now contains "FOO"

What if, at some point in the future, we wanted to add a toLower method and we didn’t have access to the source code? The first thing that probably comes to mind is to use inheritance. Unfortuantely, NetString is a final class, so that’s out of the question. So what else?

All we’re left with is using a function or a static method. Wouldn’t it be nice if we could do something like this?

NetString::addMethod("toLower", function($str) {
    return new NetString(strtolower($str->string()));
});
 
$str = new NetString("foo");
 
$upper = $str->toUpper()->string();
// $upper now contains "FOO"
 
$lower = $upper->toLower()->string();
// $lower now contains "foo"

Starting with PHP 5.3, this is possible thanks to closures and some other new features. The rest of this article will be dedicated to explaining how to setup extension methods in PHP.

How It Works

In order to add extension methods to PHP, we need to do a couple of things. First off, since an extension method is basically a missing method, we need to find some way to catch any calls to missing methods. Fortunately, PHP provides a mechanism for doing this. It’s a magic method called __call.

What we need to do is make sure any class that we want to have extension methods have it’s __call method rerouted to a method dispatcher. This dispatcher will have to be static so all instances of a class can access it. In order to ensure that these calls are rerouted to the dispatcher, we’ll create a common base class that does that automatically for us. We’ll call this base class Extensible.

class Extensible {
    public function __call($name, $args) {
        self::methodDispatcher($this, $name, $args);
    }
 
    public static function methodDispatcher( 
            $instance, $name, $args) {
    }
}

Now that we have our missed calls rerouted to our dispatcher, we need two more things. We need a way to add methods to the object (addMethod) and we need somewhere to store them to look them up with the dispatcher ($methodTable).

class Extensible {
    public function __call($name, $args) {
        self::methodDispatcher($this, $name, $args);
    }
 
    private static $methodTable = array();
 
    public static function methodDispatcher( 
            $instance, $name, $args) {
    }
 
    public static function addMethod($methodName, $method) {
    }
}

We’re almost there. How can we store a method so that we can uniquely identify it? The easiest way would be in an associative array indexed by class name. Each value in the that associative array would be another associative array holding all the extension methods (i.e. the closures) for that class.

class Extensible {
    public function __call($name, $args) {
        self::methodDispatcher($this, $name, $args);
    }
 
    private static $methodTable = array();
 
    public static function methodDispatcher( 
            $instance, $name, $args) {
    }
 
    public static function addMethod($methodName, $method) {
 
        $class = get_called_class();        
        $table =& self::$methodTable;
        if (!array_key_exists($class, $table))        
            $table[$class] = array();                
 
        $table[$class][$methodName] = $method;
    }
}

Now that we have all the extension methods stored, how do we invoke them? Well, if they’re going to be useful at all, they’ll need to have access to the instance they’re attached to. Like .NET, we’ll provide that automatically as the first argument. We also need to pass the arguments that were passed in the call.

class Extensible {
    public function __call($name, $args) {
        self::methodDispatcher($this, $name, $args);
    }
 
    private static $methodTable = array();
 
    public static function methodDispatcher( 
            $instance, $name, $args) {
        $table =& self::$methodTable;        
        $class = get_class($instance);
        do {
            if (array_key_exists($class, $table) 
                    && array_key_exists($name, $table[$class]))
                break;
 
            $class = get_parent_class($class);
        } while ($class !== false);
 
        if ($class === false)
            throw new Exception("Method not found");
 
        $func = $table[$class][$name];
        array_unshift($args, $instance);
 
        return call_user_func_array($func, $args);
    }
 
    public static function addMethod($methodName, $method) {
 
        $class = get_called_class();        
        $table =& self::$methodTable;
        if (!array_key_exists($class, $table))        
            $table[$class] = array();                
 
        $table[$class][$methodName] = $method;
    }
}

And we’re there. Now, in order to add extension methods to a class, we just have to ensure that inherits from our Extensible class. I’ll admit this is kind of a crappy requirement, but it’s the best we can do for now.

Here’s an example:

final class Bug extends Extensible {
    private $name;
    private $arms;
    public function __construct($name, $arms) {
        $this->name = $name;
        $this->arms = $arms;
    }
    public function getName() { return $this->name; }
    public function getArms() { return $this->arms; }
}
 
Bug::addMethod("hug", function($bug, $otherBug) {
    echo $bug->getName() . " hugs " . $otherBug->getName();
});
 
Bug::addMethod("punch", function($bug, $otherBug) {
    echo $bug->getName() 
       . " punches " . $otherBug->getName()
       . " with " . $bug->getArms() . " fists ";
});
 
$doug = new Bug("Doug", 10);
$fred = new Bug("Fred", 4);
$fred->hug($doug);
$doug->punch($fred);

Limitations

This implementation of extension methods in PHP isn’t all puppy dogs and ice cream. It has its share of drawbacks:

• Classes must inherit from Extensible to be capable of having extension methods. This sucks, but you can get around it in existing classes by using composition.
• Speed. Although I have not tested it myself, magic methods like __call are apparently quite slow.
• Ignores inheritance. This particular implementation does not follow the inheritance chain to see if any parent classes have extension methods for a given method call. This could be easily remedied with a bit of code. See the update below.

Source

The source code I have written in this article is public domain, and you are free to do what you will with it. Here is the source file.

Update

I’ve updated the code so that methodDispatcher will search the inheritance chain for a suitable extension method. This behaviour is illustrated by this example:

class Foo extends Extensible { }
class Bar extends Foo { }
Foo::addMethod("customMethod", function($object) {
    return "Foo";
});
 
$bar = new Bar();
$result = $bar->customMethod();
// $result contains the string "Foo"

We’ll start with something fairly straightforward by making a jQTouch app that makes an AJAX call to a PHP script to search a database. It then displays the results of that search in the jQTouch app. This article is split up into two parts. The first part deals with the jQTouch UI and the second part deals with the PHP script and the supporting JavaScript.

This is part 1 of a two part series.

jQTouch UI

Let’s start with our jQTouch UI code. First, we’ll need to grab the jQTouch distribution. Use your favourite archiver to extract two folders: jqtouch and themes and put them in our document root.

Next, we need to create an index page, index.html, in our document root. We’ll need some boilerplate to get things started:

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <meta name="viewport" content="width=device-width; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;" />
        <script type="text/javascript" src="http://www.google.com/jsapi"></script>
        <script type="text/javascript"> google.load("jquery", "1.4.2"); </script>
        <script type="text/javascript" src="jqtouch/jqtouch.min.js" charset="utf-8"></script>
        <script type="text/javascript"> $.jQTouch(); </script>
        <style type="text/css" media="screen">@import "jqtouch/jqtouch.min.css";</style>
        <style type="text/css" media="screen">@import "themes/jqt/theme.min.css";</style>
        <title>Searcher</title>
    </head>
    <body>
    </body>
</html>

Here’s the breakdown:

• on line 5, we tell the iPhone not to allow zooming,
• on lines 6-7, we load jQuery from the Google CDN,
• on line 8, we load the jQTouch JavaScript source,
• on line 9, we initialize jQTouch,
• on lines 10-11, we load the jQTouch core stylesheet and the theme stylesheet.

The Home Page

Now that we have the boilerplate setup, it’s time to start adding some UI elements. jQTouch makes this extremely simple by handling most of the heavy lifting (add this between the body tags):

1
2
3
4
5
6
7
8

<div id="home" class="current">
    <div class="toolbar">
        <h1>Searcher</h1>
    </div>
    <ul class="rounded">
        <li class="arrow"><a href="#search">Search</a></li>
    </ul>
</div>

Woah, that’s a lot packed into these 8 lines. Let’s break it down:

• on line 1, we have a div with the id “home”. This is a special id for jQTouch that indicates the entry point (i.e. the first page shown).
• on line 2-4, we have the toolbar. This is something that is repeated for every jQTouch page. It’s the part that is shown at the top of any iPhone GUI app and, consequently, any jQTouch app.
• on line 5-7, we have the content of this page. Basically, we are telling jQTouch that we want a list of rounded buttons, one of which is “Search”. The #search href in the anchor tag tells jQTouch what page we want to load when that button is clicked.

Before I move on, let’s look at a screenshot of what we have so far:

Not too shabby considering we’ve written all of 8 lines of HTML to make that happen! Unfortunately, as you’ve probably noticed, clicking the Search button does nothing but make it turn green.

The Search Page

Let’s hook up the Search button from the previous page to a search page. This will be where we enter our search text. Here’s the code for the search page (it goes right after the code in the last listing):

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

<form id="search" action="">
    <div class="toolbar">
        <h1>Search</h1>
        <a href="#" class="back">Back</a>
    </div>
    <ul class="rounded">
        <li><input type="text" name="search-text" placeholder="Search" id="search-text" /></li>
    </ul>
    <ul class="edgetoedge" id="search-results">
        <li class="sep">Results</li>                
    </ul>
</form>

• on line 1, we have the id “search”. This corresponds to the href we had in the link on the home page.
• on lines 2-5, we have the toolbar again, this time for the search page. Of particular note here is the addition of the back button. A div with class “back” is another special case for jQTouch. It will automatically be linked back to the previous page.
• on lines 6-8, we have another familiar face, the unordered button list. However, this time we have an input with a special name “search-text”. In jQTouch, any text input element that has a name that starts with “search” will act as a search input.
• on lines 9-11, we have another unordered list of buttons, this time using a different visual class “edgetoedge”. In this list we have one item, a separator (class “sep”), that we use to label the list as our results. Later on, in part 2, we’ll place our search results in this list.

After we add this code to our index.html file, let’s reload the web page in our iPhone or iPad and try clicking the Search button again. You’ll see it brings you to a screen like this:

You’ll also notice that if you click the “Back” button at the top, it’ll bring you back to the “home” page.

Conclusion

In this tutorial we made a jQTouch UI that looks like an iPhone app. We touched on a few jQTouch concepts:

• Pages are linked together using ids.
• All jQTouch pages have toolbars (which is a div with class “toolbar”). The toolbar contains an h1 element that represents the title of the page and two optional buttons, one of which can be a back button by using the class “back”.
• Lists of buttons are created by using unordered lists (“ul” elements) with special classes like “rounded” and “edgetoedge”.
• Text input elements will act differently based on their name attributes. For example, a search text input element is defined as such by having a “search” prefix in it’s name attribute.

However this is only scratching the surface of jQTouch. If you want to learn more I highly recommend your check out the demos directory in the jQTouch distribution. There is also a Google Code page that has a Wiki and links to other tutorials.

What Now?

With respect to the UI, we’re done. All that remains to be done now is to write a PHP script that we’ll query with an jQuery AJAX call. This is covered in part 2 of this tutorial.

Source

The source code I have written in this article is public domain, and you are free to do what you will with it. Here is a zip of the source, along with the required jQTouch source. It should work pretty much right out of the box.

It would’ve been a helluva lot faster to have had some sort of conversation table. After a little searching on Google, I found nothing so I decided to make one myself. Behold, the fruits of my labour!

To use a PHP date format string:
$time = date("g:i a")

To use a .NET date format string (in C#):
string time = DateTime.Now.ToString("h:mm tt")

(Please note that just because I have no entry for the DateTime version of one of the PHP date strings, it doesn’t mean you can’t get that information using .NET easily. It just means that it’s not in DateTime or not a one-liner.)

This table highlights some pretty interesting differences between the .NET API (i.e. a carefully designed API) and the PHP API (i.e. an ad-hoc API). For example, if I asked you what g stood for in a PHP date format string, would you be able to say (without looking at a chart) “hours with no leading zeroes?”

What’s cool about the .NET API is that they try to make the format strings mean something. For example, d means “day number with no leading zeroes”, dd means “day number with leadings zeros”, ddd means “short form day name”, dddd means “long form day name”. That is, as you add d’s, you get progressive larger date string as a results.

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.