A comet over PHProjekt 6

So far PHProjekt 6 (P6, see http://phprojekt.com) is already enhanced with nice AJAX workflows and snappy user-experience. Nevertheless, we discussed a way to provide synchronous communication and direct information within the application.

Everybody knows GoogleMail with its easy to use frontend. Maybe you use it for your daily work. In GoogleMail, there is no need to refresh the page to receive a new mail, Google informs you automatically whenever a new mail is available. But how is this possible? The answer to this question is really simple: The server triggers a signal informing that a new mail is available. This technology is called Comet and describes a way how the server communicates with the client [see http://en.wikipedia.org/wiki/Comet_(programming) ].

Is there a way to use Comet for P6? As P6 works with a lot of users, it is important for me as a user to be informed when somebody has changed something in my projects or has added an urgent todo. The list where a notification could be triggered is long, but at the moment, only email notifications are sent immediately. So, what we need in P6 are real-time notifications. With real-time notifications, for example, every time somebody changes something in my project, I receive a message in form of a highlighted info box. This looks like a typical use case for using Comet. And yes, Comet would be great for realizing this kind of real-time notification! But since the users love the handy system requirements (Apache Server and MySQL) and the ease of installation, something different is needed than a real Comet architecture, because all the Comet magic is based on a so called application server, e.g. Jetty, Persevere. Therefore, I decide to implement another (Comet-) technology, called Long Polling. You can find the name AJAX Polling for this technology, too.

The technology behind Long Polling is to open a connection from the client to the server and not to close this connection immediately. Ok, that´s fine, but how to open a connection and „hold“ it? Opening a connection to the server is easy, a simple AJAX will do the trick. P6 uses the Dojo Toolkit for all its AJAX, so in this case I used the Dojo.xhrPost.

dojo.xhrPost({
  url: myUrl,
  error: function(error, handle) {
    handleError(myUrl, error);
  },
  load: function(response) {
    if (false != response.data) {
    showToaster(response.data);
  }
},
  handleAs: 'json'
});

Since the HTTP protocoll is connection-based, at the server-side, a process is also needed that holds the connection and does not return . So, what I do to hold this connection open is to set a simple timeout during the execution of the server-side script, in my case I use sleep(). This is the basic idea of long polling, but the gimmick of this approach is to return earlier if something happens on the server-side. In other words, I open a connection to the server and check whether there are any changes, if not, the connection stays open for the maximum polling time. If yes, the response will be returned to the client immediately.

This diagram shows the basic workflow, and the lines below show the possible solution in PHP:

$counter = 0;
$maxLoops = 4;
$data = array();

while ($counter != $maxLoops) {
  $counter++;
  $data = $this->getMessage($userId); // get data from database
  if (false === empty($data)) {
    return $data; // there is something new, return immediately
  }
  sleep(5); // nothing is new, sleep for 5 sec.
}

return $data; // return the empty array

For P6 this means that I always save the following: the person who triggers an event, the event itself (e.g. somebody adds a new note), the item, the project, the creation time, the time until this message is valid, and the persons who should receive a frontend message from the database. The long polling loop checks whether there is anything new. If yes, it returns the data. If not, the polling loop starts again. Every event is saved in the database for a maximum of two minutes, except events in the future. Itis real-time – so itis possible to miss a message ;-)

One word about the Dojo Toolkit. The AJAX API of Dojo provides several functions to communicate with the server. The easiest way is to use dojo.xhrGet or dojo.xhrPost. I decided to use the Post version. Although the function has a property setTimeout, which allows you to set the time to wait for a response from the server, this is not needed, because of the sleep loops at the server side.

Now, let’s look at the downsides of the long polling approach. Yes, I partly agree with everybody who says that the permanent polling to the server causes massive traffic and server load, especially with an increasing number of users. But in the special case of P6 this is OK, because the number of users is manageable and in most cases, P6 runs in a local network. In addition, the frontend messages are configurable, You can set the polling loop and the number of requests to the database.

Considering all the facts and keeping in mind that P6 is designed to be a lightweight open source groupware, I am positive to say that the Long Polling technology is the right choice for P6.