My favorites | Sign in
Project Home Downloads Wiki Issues Source
Project Information
Wiki pages


Formaldehyde (systematic name: methanal) is a chemical compound with the formula CH2O. It is the simplest aldehyde. Aldehydes can, typically in the presence of suitable catalysts, serve as partners in cycloaddition reactions.

Why Formaldehyde

PHP and Web Development are perfectly married but Ajax interactions have always been difficult to debug. Applications like Firebug are extremely useful to deploy, debug, and generally for Web Applications development. These kind of softwares are still running via browser but both JavaScript and PHP require hard test, being dynamic programming languages, as dynamic is an Ajax interaction. There are several ways to debug Ajax calls but honestly I have never found one able to be integrated without effort and easy to manage directly via JavaScript and/or Firebog or whatever console is there ... This is the reason I have created a single, well tested, widely compatible and fast Error Debugger, where all we need to do is to require_once this single file for each Ajax called page. Everything else will become so natural that you will ask yourself why on earth nobody created such simple solution before. Most advanced PHP frameworks integrate an error manager able to make deploy and debug easier. Unofrtunately, too often these frameworks are not that simple to configure or are not scalable enough, even if what we are trying to do is extremely simple. For these cases and every other, Formaldehyde could be integrated without effort, at all! To better understand how Formaldehyde will change our daily WTF during Ajax interactions, words cannot compete with code and images.

The Classic Ajax PHP Scenario

A basic or complex Ajax interaction is performed calling a server side page. Every kind of application could contain error or bugs, specially during its development. The darkest side of run-time interpreted languages, as PHP is, is the missed syntax and structure analyzer. In few words, we will never be sure if our PHP page will behave as expected until we execute it. Specially with complex applications, to reproduce exactly "that kind of call" could not be that simple, and a "silly" Fatal error could become a massive waste of time. How often in the middle of a test session we had to investigate what's happened and try to solve and then try understand if that was the error reproducing Nth times the same scenario? This first example is about this kind of situation, the most simple but the most frequent one as well!


<?php // generates a Fatal Error

echo 'Hello', iDoNotExist(), ' ', 'World';


somewhere else in the user page ...

// create the instance
var xhr = new XMLHttpRequest;

// open the channel"get", "test.php", true);

// define the handler
xhr.onreadystatechange = function(){

    // on server response
    if(xhr.readyState === 4){
        // check response status
        if(199 < xhr.status && xhr.status < 400){
            // do something *failing* if there was an error ...
        } else {
            // read the server response, if any
            console.log(new Error(xhr.responseText));

// execute the call

Above image perfectly represents a fatal error in the middle of a generic session. To understand what's happened I had to:

  • figure out that something went wrong, no error in Firebug, then open a part the error console to discover problems during evaluations even if the status was OK
  • find the right Ajax call in the console between hundreds possible calls, reading one after one, which one produced the unexpected output
  • read the produced html output which could have been any kind of content-type, and in any place of response body, if for example there are ob_functions in the middle of the page
  • add who knows how many weird control in my JavaScript in order to understand if I can manage as expected a response that suppose to be correct, and not an error
Are these points familiar and enough? I could add more if you want ...

Introducing Formaldehyde

As described before, Ajax call debug could be a massive waste of time. At least we could make things more easy, simply introducing a sort of mechanism which aim is to change the response status whenever the server generated an error. In this way rather than scroll who knows how many calls to find the one with the wrong output, I could have simply checked red lines inside the console panel. To make this happen, all we need to do is to include one file, formaldehyde.php, and this is how things will aready change.


<?php require_once 'formaldehyde.php';

echo 'Hello', iDoNotExist(), ' ', 'World';


With a single file included I have:

  • removed possible client side errors thanks to the new 500 response status
  • spot instantly that something went wrong thanks to the red line rather than a black one
  • understand the output thanks to text/plain content-type rather than whatever else
  • know general page performances thanks to X-Formaldehyde header, OK nothing special, but I had to put something in that header so why not the elapsed time

Things could be even better if we correctly manage the status 500 via JavaScript and we log directly in the console the Formaldehyde response.

Formaldehyde JavaScript

Since 10 September 2009, it is possible to simply include formladehyde.js file before every other library or script in your HTML (not the server one then, the one that will perform Ajax calls via JavaScript).

<!DOCTYPE html>
        <title>Formaldehyde JS Example</title>
        <!-- Formaldehyde JS as first script -->
        <!-- possibly only development environments -->
        <script type="text/javascript" src="formaldehyde.js"></script>

        <!-- other libraries, if any -->
        <script type="text/javascript">
        var xhr = this.ActiveXObject ? new ActiveXObject("Microsoft.XMLHTTP") : new XMLHttpRequest;"get", "test.php", false); // or true + onreadystatechange

Formaldehyde JS should be totally unobtrusive, and it should fallback for every kind of browser plus it does not require dedicated plug-ins or specific browsers to be used (tested in Chrome, Safari, Opera, IE5.5, IE6, IE7, IE8 and obviously Firefox). The difference is that we do not even need to add controls onreadystatechange event.

JavaScript Formaldehyde Scenario

// *optional* custom ServerError constructor
function ServerError(e){
    for(var key in e)
        this[key] = e[key]
// make Firebug the best friend ever
(ServerError.prototype = new Error).name = "ServerError";

// same call
var xhr = new XMLHttpRequest;"get", "test.php", true);
xhr.onreadystatechange = function(){
    if(xhr.readyState === 4){
        if(199 < xhr.status && xhr.status < 400){
            // do something without failures
        // if Formaldehyde managed the call
        else if(xhr.status === 500 && xhr.getResponseHeader("X-Formaldehyde") != null) {
            // evaluate safely the response
            // generating a proper error
            console.log(new ServerError(eval("(" + xhr.responseText + ")")));

        } else {
            // 404 or other cases
            console.log(new Error(xhr.responseText));

Thanks to 2 more lines in our JS code, plus ServerError function which is optional in any case, the error will output directly in console a red dumped object that could be clicked and surfed with the entire stack trace as array of the stack property. In few words Formaldehyde response objects are de-facto Errors represented as client side objects, but with all typical JavaScript Error properties and these could be obviously raised as well.


I develop PHP async interactions via ActionScript and LoadVars, Ajax, or Remote Scripting before, since year 2000 but for some reason I have never thought about a portable, scalable, simple, and complete debugger file as Formaldehyde is. I hope you'll appreciate its simplicity, its basic and useful features, and I am waiting for your feedback in WebReflection

Best Regards, Andrea Giammarchi

Powered by Google Project Hosting