./configure --prefix=/usr/local --mandir=/usr/share/man --infodir=/usr/share/info --sysconfdir=/private/etc --enable-cli --with-config-file-path=/usr/local/php/etc --with-libxml-dir=/usr --enable-xml --enable-exif --enable-ftp --with-gd --with-jpeg-dir=/usr/local/lib --with-png-dir=/usr/local/lib --enable-gd-native-ttf --with-imap=/usr/local --with-imap-ssl --enable-magic-quotes --enable-mbstring --enable-mbregex --enable-json --with-mysql=mysqlnd --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd --with-mysql-sock=/tmp/mysql.sock --with-iodbc=/usr --enable-shmop --enable-sockets --enable-fpm --with-mhash --with-mcrypt --with-xmlrpc --enable-xmlwriter --enable-xmlreader --with-xsl=/usr --enable-zend-multibyte --enable-zip --with-pcre-regex=/usr/local --with-pdo-sqlite --enable-pdo --with-freetype-dir=/usr/local --enable-dom --enable-fileinfo --with-kerberos --with-pgsql=/Applications/Postgres.app/Contents/MacOS --with-pdo-pgsql=/Applications/Postgres.app/Contents/MacOS --with-curl --with-gettext --with-zlib --with-tidy --enable-pcntl --enable-hash --enable-mbregex --with-regex=php --enable-bcmath --enable-sqlite-utf8 --enable-intl

Otherwise I had errors with Intl (ICU) and cUrl together, something like :

Undefined symbols for architecture x86_64
_res_9_dn_expand etc...

This was on OSX Mountain Lion.
Coworker reports it also works on old Lion :p

That’s why tools like Twitter’s Bootstrap and PEAR’s HTML_QuickForm2 can help with this part of our job.

Wouldn’t it be nice to have QuickForm2 generate a markup compatible with Bootstrap CSS, so that you could get a nice looking form without to much efforts? Well, that’s what I plan to do here.

Bootstrap is a toolkit from Twitter designed to kickstart development of webapps and sites. It includes base CSS and HTML for typography, forms, buttons, tables, grids, navigation, and more. In this post, I will concentrate on the form stuff.

QuickForm2 on the other hand is a PHP library dedicated to make building HTML forms easier, faster and less error-prone. It is hosted in PEAR and has been extensively tested.

First, I will try to build the same form as shown on Bootstrap’s website, with QuickForm2. Except for the three elements with appended and prepended things, it was easy. I will come back to these elements later, just know it is not difficult to render them neither.

So here is the result :
Step 1 : Bootstrap with QuickForm2 and no renderer

The most obvious problem is that QuickForm2 doesn’t use the same markup to build forms as what Bootstrap expects. To solve this, we can use the Callback renderer that comes with QuickForm2 and define our own callback to render our elements the way Bootstrap likes them.

The Callback renderer associates PHP callbacks with form elements using either their type (text, textarea, …) or their name if you need a more precise control. This means that we can first define how our form object should be rendered, as well as our Checkboxes, Textareas, etc. Adding a Callback renderer and specifying a function to render an element is as simple as that :

$r = HTML_QuickForm2_Renderer::factory('callback');
 
$r->setCallbackForClass('HTML_QuickForm2_Element', function($renderer, $element) {
    $error = $element->getError();
    if ($error) {
        $html[] = '<div class="clearfix error">';
        $element->addClass('error');
    } else {
        $html[] = '<div class="clearfix">';
    }
    $html[] = $renderer->renderLabel($element);
    $html[] = '<div class="input">'.$element;
    if ($error) {
        $html[] = '<span class="help-inline">'.$error.'</span>';
    } else {
        $label = $element->getLabel();
        if (is_array($label) && !empty($label[1])) {
            $html[] = '<span class="help-block">'.$label[1].'</span>';
        }
    }
    $html[] = '</div></div>';
    return implode('', $html);
});
echo $form->render($r);

Just adding the above to our form will already make it look a lot better with Bootstrap. There are some refinements we can add for the rest of our elements, this is shown here :
Step 2 : Defining callbacks to render elements

As you may notice, when I have to deal with special elements or group of elements, as is the case with Bootstrap and its action buttons for example, I usually just create a dumb subclass and define a specific callback to render it. For example, to render the form buttons:

// Callback for action inputs
 
$r->setCallbackForClass('ActionInputs', function($renderer, $group) {
    $html[] = '<div class="actions">';
    $elements = array_pop($renderer->html);
    $html[] = implode(' ', $elements);
    $html[] = '</div>';
    return implode('', $html);
});
 
// Callback for elements inside an action inputs group
 
$r->setElementCallbackForGroupClass('ActionInputs',
    'HTML_QuickForm2_Element', function($renderer, $element) {
    $html[] = (string)$element;
    return implode('', $html);
});

This is a very simple example, you can do a lot more in these callbacks, for example add a contextual error message, a label or an help text, join elements with a separator, etc.

There are, of course, many ways to improve this renderer and expand it to make it even more reusable. I personally find the Bootstrap CSS a little limited, for example it’s missing the following features I often use :

• Differentiate required elements
• Allow elements in inline inputs groups to have labels
• Allow checkboxes and radios to be displayed inline
• Use a standard text link instead of a button for cancel (better for redirects)
• Allow elements in inline inputs groups to have contextual errors

For the above, I have made my own QuickForm2 renderer and custom CSS, but if you know of any other good looking and interesting CSS framework for styling forms, please let me know.

• Liip distributes a full featured PHP 5.3 binary for Lion
• Zend has its Zend Server Community Edition
• MacPorts
• Homebrew

These are all very good solutions, but since I prefer to travel light and the version in Lion already comes with a lot of useful extensions, I preferred to go with it.

Here is the list of extensions installed with Lion:

bcmath, bz2, calendar, Core, ctype, curl, date, dba, dom, ereg, exif, fileinfo, filter, ftp, gd, hash, iconv, json, ldap, libxml, mbstring, mysql, mysqli, mysqlnd, odbc, openssl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, Phar, posix, readline, Reflection, session, shmop, SimpleXML, snmp, soap, sockets, SPL, SQLite, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, zip, zlib

In /etc, there is a php.ini.default file that is not activated, so you will have to modify it to suit your preferences and rename it to /etc/php.ini. For instance, Lion also ships with Xdebug, but it is not activated by default. To activate it, you’ll have to remove the semi-colon on the line that says:

zend_extension="/usr/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so"

Lion doesn’t provide neither PEAR nor PECL by default but it is easy to activate them because Apple provide the required php archive file (phar) for that:

cd /usr/lib/php
sudo php install-pear-nozlib.phar

Then edit the php.ini file and add:

include_path = ".:/usr/lib/php/pear"
extension_dir = "/usr/lib/php/extensions/no-debug-non-zts-20090626"

Then you can update your PEAR/PECL channels:

sudo pear channel-update pear.php.net
sudo pecl channel-update pecl.php.net
sudo pear upgrade-all

If like me you are missing the Intl extension, here is how I installed it (warning : requires Xcode):

1. Download and install ICU

   tar xzvf icu4c-4_8_1-src.tgz
   cd icu/source
   ./runConfigureICU MacOSX
   make
   sudo make install

2. Download PHP 5.3.6 sources (update: I tried with 5.3.8, I got a compilation error, so use 5.3.6)
3. Unpack
4. Change directory to ext/intl
5. Use the following commands in Terminal:

   cd ext/intl
   phpize
   ./configure --enable-intl
   make
   sudo cp modules/intl.so /usr/lib/php/extensions/no-debug-non-zts-20090626/

6. Activate intl in your php.ini file with

   extension=intl.so

Since I mostly work on multilingual sites, I also needed to install Gettext (it’s unfortunate that Apple will not ship gettext and intl by default, a lot of PHP developers use more than English, but that might be another licence issue…). The problem is that Gettext apparently defines stpncpy function, as does something in Lion…

As suggested by Stephen Yeargin in the comments, you can apply a small patch on Gettext that will modify the configure script to make sure function stpncpy is not already defined.

tar xzvf gettext-0.18.1.1.tar.gz
cd gettext-0.18.1.1
# apply patch here, then :
./configure
make
sudo make install

Then, back in the PHP sources directory:

cd ext/gettext
phpize
./configure --with-gettext
make
sudo cp modules/gettext.so /usr/lib/php/extensions/no-debug-non-zts-20090626/

And add this to the php.ini file:

extension=gettext.so

Finally I just restarted Apache from the Sharing Preference pane and I’m ready to start coding.

Updates 02/24/2012: Don’t use 5.3.8. Use the patch suggested in the comments for Gettext to compile.

Installing HTML_QuickForm2

QuickForm 2 is a PEAR package, so it can be easily installed using the following command from your command line:

pear install -f html_quickform2

This will also install the HTML_Common2 which is required by HTML_QuickForm2.

Form components

Before we get started with the code, there are some concepts you should know that will make your work with QuickForm 2 easier. More specifically, it is important to understand what makes a form :

• Elements : Elements are the form widgets that receive input from the form users. In QuickForm 2, elements are text fields, textareas, select boxes, radio buttons, checkboxes, buttons, etc. In most cases, the elements are descendant of the HTML_QuickForm2_Element class. To build a form, basically, you just have to add elements to it.
• Labels : Labels are what helps the users know what the input is expecting. Labels are usually placed in <label> tags although this can be changed by your form renderer. Checkable elements like radio buttons or checkboxes are also treated differently, their label is the text that is displayed next to each one of them. In QuickForm 2, an element can have multiple labels, this makes it easy to add descriptions and help text.
• Required elements : Required elements are checked for contents when they are submitted. They are also marked as such, so the form renderer knows they should be treated differently because the user needs to know he has to fill them.
• Groups and fieldsets : Elements can be grouped in generic containers. This helps organize your form logic and rendering. It is a very powerful feature of QuickForm 2 and is what makes working with it so pleasant (in my opinion). It is also a feature other form packages usually don’t have, last time I checked. Groups are descendant of the HTML_QuickForm2_Container class. By default, QuickForm 2 provides two containers : group and fieldset.
• Submit elements : Submit elements need to be treated differently since they are usually display at the bottom of the form and they don’t need a label. They can be either right or left aligned. They trigger the submit event of the form which leads to the form validation and processing. By default, QuickForm 2 has a way to identify which form has been submitted, even if you have more than one form on a page. Submit elements can also be buttons and images.
• Error messages : Errors are displayed once the form has be submitted and didn’t validate. QuickForm 2, thanks to its renderers flexibility, allows to group error messages together or display them next to the elements. Client side validation with javascript was added in version 0.5 and it works like HTML5 validation (but without the need for HTML5).

These are the basic parts that will usually compose your forms. QuickForm 2 has methods to deal with all of them in a flexible way as we will see now and in future tutorials.

Build the contact form

First thing, we’ll have to define our form object and specify how and where it is supposed to send its values when submitted.

$form = new HTML_QuickForm2('ContactForm', 'post', array(
    'action' => $_SERVER['PHP_SELF']
));

Notice that we used PHP_SELF as url for processing our form. It is usually a good habit to use an url that will process our form and then redirect to somewhere else once everything is done, using a header('Location: /other-url'). This technique is called Post/Redirect/Get and is recommended with QuickForm 2.

Using PHP_SELF is fine because QuickForm 2 needs first to build the form in order to know what the elements and rules are. Most of the time, the form is built in PHP_SELF. The good news is that QuickForm 2 uses PHP_SELF by default so you actually don’t have to specify the third parameter if that’s all you need.

Now, let’s add some form elements.

// Let's start with a fieldset
$fs = $form->addFieldset('contact_us')->setLabel("Contact us");
 
// Add a title select box
$title = $fs->addSelect('title')
             ->setLabel("Title : ")
             ->loadOptions(array('' => "Select your title...", "Mr.", "Ms"));
 
// Add a name text field
$name = $fs->addText('name')->setLabel("Name : ");
 
// Add a comment textarea with 6 rows
$comment = $fs->addTextarea('comment', array('rows' => 6))
                      ->setLabel("Comments : ");
 
// Add the submit button to our form (outside of our fieldset)
$form->addSubmit('submit', array('value' => "Send us your comments"));

This is a lot like playing with HTML directly. You specify element attributes in the second parameter and they get added to your element tag. Shall we later enforce a maxlength for our text field, it would be as easy as :

$name->setAttribute('maxlength', 64);
$title->setAttribute('style', 'width:200px');

That’s because all our elements inherit from HTML_Common2 which does that for us.

Validation

All our fields should be required so we have to specify it.

$title->addRule("required", "Please specify your title");
$name->addRule("required", "Please specify your name");
$comment->addRule("required", "Please enter some comments");

Upon user submission, QuickForm 2 will check that these fields have been filled. But before we actually call the validate() method, let’s make sure that the submitted values are not only spaces or newlines. In order to achieve this, we’ll trim all our form values :

// Apply the trim() function recursively on all form children elements
$form->addRecursiveFilter('trim');

By default, QuickForm 2 uses what we call intrinsic validation on the server-side. It just means that user cannot submit non-existent values from your select box (it can be turned off). Let’s validate the form and output it to the browser :

if ($form->validate()) {
  echo "Success"; // Use a redirect here...
} else {
  echo $form;
}

Thanks to a hidden element, QuickForm 2 knows when the form needs to be validated and will not try to validate it if unnecessary.

The form can be output with a simple echo because like all other QuickForm 2 elements, the __toString() method is implemented.

Conclusion

If you just look at the code, you will see that we made a full featured contact form that has validation for required elements and select boxes, recursive trimming of values and that is reusable, in just a few lines. Note that we could even have added client-side validation with javascript without having to add a single line, but this will be talked about in another post…

In the future, I plan to talk more about rendering and styling forms using CSS and eventually a custom renderer. I also plan to post some nice tricks to make working with QuickForm 2 as efficient as possible and how to make your own elements with javascript. So, stay tuned