Building AJAX Applications with PHP and HTML_AJAX

The Need For Speed

Unless you’ve spent the past couple of years down a rabbit hole, you’ve already heard about AJAX: it’s a technique that combines asynchronous client-server communication with a set of existing toolkits (JavaScript, CSS, the DOM) to selectively update parts of a Web page, instead of the traditional “full page reload”. This produces applications that are quicker and more responsive to user input, resulting in a better user experience.

But what does all this have to do with PHP, you ask? Well, PHP is commonly used on the server end of the connection, to handle AJAX requests and send back responses. But that isn’t all it can do – with a little PEAR package called HTML_AJAX, you can use PHP to significantly simplify the work that goes into building and deploying an AJAX application.

That’s where this article comes in. Over the next few pages, I’m going to give you a quick run-down on the PEAR HTML_AJAX class, together with a few examples of how you can use it to AJAX-ify various Web applications. Keep reading, and be prepared to be amazed!

Getting Started

HTML_AJAX works by providing a well-defined API for creating, processing and handling AJAX requests and responses. This API (which has both JavaScript and PHP components) insulates you from the nitty-gritty of working with a browser’s XMLHttpRequest object, thereby offering significant time-saving benefits over the “roll your own” approach.

Before we get started, it’s important to state the assumptions this tutorial makes:

  • First, it assumes that you understand HTML, know the basics of JavaScript and DOM programming, and are familiar with basic AJAX concepts.
  • Second, it assumes that you have an Apache/PHP/MySQL development environment already set up, know the basics of PHP scripting, and are familiar with retrieving and processing SQL result sets in PHP.
  • Third, it assumes that you’ve managed to successfully install the HTML_AJAX package. For your reference, this package is freely available from, and is currently maintained by Elizabeth Smith, Arpad Ray, Joshua Eichorn and others. To install the package using the PEAR installer, use the following command:

This article uses v0.5.6 (beta) of HTML_AJAX.

I should mention at this point that this tutorial is intended mainly for users new to HTML_AJAX. As such, it includes a general introduction to the package and how it works, but shies away from very complex examples. Once you’ve worked your way through this tutorial, you’ll find many more sophisticated applications for HTML_AJAX in the package documentation and on the HTML_AJAX home Web site.

The Bookworm Turns

Let’s begin with a simple example that demonstrates how HTML_AJAX works. Assume for a moment that you have a MySQL database containing the following book and author records:

Here’s a PHP script that accepts an author ID as input (as a GET parameter) and executes an SQL query to return a list of all the books written by that author, by joining the author_title and title tables:

This is all pretty simple so far. Now, how about adding some AJAX to the mix? Let’s say we want a Web page that lets the user click an author’s name, and have the page updated with the books written by that author. With HTML_AJAX, this is simplicity itself. The first step is to create an instance of the HTML_AJAX server, which is responsible for delivering the JavaScript components to the client. Here’s the code:

Next, build an HTML page that requests the necessary JavaScript components from the server, and then uses those components to make an AJAX call. Here’s the code:

The first <script> element in this page sends a request to the server, which responds with the JavaScript client files needed for HTML_AJAX to work. This code produces a client-side HTML_AJAX object, which makes a bunch of important methods available to the client. The simplest of these is the grab() method, which performs a GET request to a specified URL and returns the result. In the script above, this method is invoked when the user clicks an author name; it then transmits a GET request to the PHP script with the author identifier and writes the output (as an unordered HTML list) to a <div> on the page.
Here’s what the output looks like:

Going POST-al

If you prefer POST to GET, replace the call to grab() with a call to post(), which accepts both a target URL and a payload object containing the data to be POST-ed. Here’s the revised code:

Remember that you’ll need to update the server-side script to use POST variables instead:

For asynchronous calls, both post() and grab() allow you to specify a callback method as optional third argument. Consider the following revision of the previous example, which demonstrates this technique:

Form and Function

An alternative approach, especially when working with forms, is to instead use HTML_AJAX’s formSubmit() method. This method needs only two arguments: the source form object, and the destination for the result. It then automatically detects the form’s action URL and method, transmits the form data, and writes the return value to the destination. Note that the destination argument to the method can be either a callback function, or an element on the page.
Here’s an example, which generates a form to calculate simple interest:

Here’s what the form looks like:

Here’s the server-side script, which receives and processes the form input:

Once the user enters values into the form and submits it, the formSubmit() method submits the form data to the above script and writes the result to the aptly-named ‘result’ element. Here’s an example of the output after a sample run:

If you’d prefer, you can pass formSubmit() a callback method, as in the following revision (which produces equivalent output):

Time Travel

Another interesting method in HTML_AJAX is the replace() method, which allows you to replace the content of a destination element. To illustrate this, consider the following HTML page, which dynamically generates a monthly calendar using AJAX:

Here’s what this form looks like:

Once the form is submitted, the displayCalendar() method retrieves the selected values and formulates them into a GET request for a server-side script. The output generated by the script is a calendar for the specified month and year, and the replace() method is used to place this output in the ‘calendar’ element on the page. If the user re-submits the form with a new month and year, a new calendar will be generated and written to the element, overwriting the previous one.
Here’s the server-side script which generates the calendar:

This script makes use of the PEAR Calendar class (read more about it at to produce a monthly calendar, using the data provided in the GET request string. Here’s an example of what the output looks like:

An alternative to the replace() method is the append() method which – as you might guess – adds new content to the specified element instead of overwriting it. If you were to alter the code in the previous example to call append() instead of replace(), you’d end up with something like this:

The replace() method can come in handy when you need to rewrite specific sections of a page with new content – for example, when paging through a data set. For a good example of this technique in combination with PEAR’s Pager class, take a look at Lorenzo Alberton’s tutorial on the topic.

An Object Lesson

HTML_AJAX also supports calling PHP object methods from JavaScript – an interesting feature, and one that comes in particular handy when your server-side application is object-based. To do this, it’s necessary to first create an instance of the object and register it with the HTML_AJAX server, as below:

Here’s what the output looks like:

You can also use HTML_AJAX’s call() method for this purpose. This method accepts, as arguments, the class name, method name, local callback function name, and one or more method arguments. It then invokes the corresponding class method on the server and returns the output to the callback function.
To see an example of this in action, modify the class definition on the server to return true or false, instead of a string value:

Then, update the Web page to use call() instead of replace(), and define a callback function that reads the result of call() and adjusts the output accordingly:

A Proxy War

HTML_AJAX has the capability to automatically generate “proxy objects” in JavaScript, that serve as stubs to your PHP objects. You can then call proxy object methods inside your JavaScript code, and these will be translated into calls to the corresponding “real” methods in your PHP objects.
To illustrate how this works, let’s consider a simple AJAX-based login form. Assume that you have a MySQL table containing the following usernames and passwords:

Assume also that you have a simple Auth class that interacts with this table and checks user credentials. Here’s what the code might look like:

This class should be registered with the HTML_AJAX server, as explained previously:

On the client side, we need a login form that asks the user for his/her username and password, and then calls Auth->login() to verify these. One way to do this is with HTML_AJAX’s call() method. Another is to use a JavaScript proxy object:

This isn’t as complicated as it looks, I promise! As usual, the first step is to load all the necessary JavaScript code. But there’s a twist here: look at the second <script> element, which uses the ?stub=Auth argument to auto-generate a “local” JavaScript object with the same methods as the remote PHP object. This local object, or proxy, serves as an entry point to all the methods of the remote object.
Here’s what the auto-generated proxy looks like:

With this, client scripts can reference the login() method of the local Auth proxy, rather than using call() to invoke the login() method of the remote PHP class. The value returned by login() is passed to the method’s callback function, which responds by using the DOM to display an appropriately color-coded message (red for failure, green for success) to the user.
Here are some screenshots illustrating the output (try logging in as ‘santa’ with password ‘northpole’):

Lights! Camera! Action

The HTML_AJAX package also provides “actions”, which help you manipulate elements on your Web page by writing the necessary JavaScript code for you. Actions expose methods, such as assignAttr(), insertScript() and insertAlert() which, respectively, deliver client-side code to dynamically access and manipulate element properties, insert script blocks or set up JavaScript alerts.
To illustrate, consider the following revision of the PHP Auth class, which uses Actions to accomplish the same result as the JavaScript code in the earlier example:

Within the Web page, now, the callback function has no work to do:

HTML_AJAX also includes another class of helpers, called “behaviors”. Behaviors work like CSS, in that they allow you to attach JavaScript code to particular elements using CSS-type selectors. These helpers come in handy to ensure that, in the author’s words, “you don’t pollute your HTML with a ton of inline JavaScript.”

To illustrate how Behaviors work, consider a further revision of the login form – in this case, with the actual call to doLogin() nestled inside a Behavior instead of the submit button’s ‘onClick’ handler:

In this case, a Behavior is registered for the ‘login_btn’ class, such that the doLogin() function is invoked when elements of that class receive a mouse click. The end result remains the same as before, but this approach can help produce more structured code, as well as allow you to apply a particular behavior to multiple elements without unnecessary duplication of code.
As these examples illustrate, using HTML_AJAX can significantly reduce the drudge work involved in AJAX-ifying your application. As such, it’s a valuable addition to any programmer’s toolkit, and one that you should definitely take some time out to experiment with. Play with it sometime, and see what you think!

Copyright Melonfire, 2009. All rights reserved.