#native_company# #native_desc#

PEAR’s HTML_QuickForm

By Ian Gilfillan
on October 25, 2006



Programmers are often told not to reinvent the wheel, and that the best programmers borrow from others before they start to build something themselves. PHP, being primarily a web language, sees a lot of reinventing in regards to form display, processing and validation. However, there’s a great PEAR package that needs a little more exposure: HTML_QuickForm. It makes handling the rendering and display of forms, and more usefully, both client and server-side validation, quick and easy. This article will take you through the basics of that package. It assumes familiarity with HTML form elements, and reasonably basic PHP skills.

Installing HTML_QuickForm

The package has only two requirements: a version of PHP that is at least 4.2, and the HTML_Common package. At the time of writing, HTML_QuickForm 3.2.7 is the newest version of the package, and it requires HTML_Common 1.2.1. There are moves underfoot to rewrite both of these packages for PHP 5 (in the form of HTML_QuickForm2, and HTML_Common2), but as yet neither has been released.
You can check what PEAR packages are already installed by using pear list:
pear list
Installed packages:
Package        Version State
Archive_Tar    1.1     stable
Console_Getopt 1.2     stable
DB             1.6.2   stable
Date           1.4.6   stable
HTTP           1.2.2   stable
Image_Canvas   0.3.0   alpha
Image_Color    1.0.2   stable
Image_Graph    0.7.2   alpha
Mail           1.1.3   stable
Net_SMTP       1.2.6   stable
Net_Socket     1.0.1   stable
PEAR           1.3.2   stable
Validate       0.6.3   beta
XML_Parser     1.0.1   stable
XML_RPC        1.1.0   stable
This machine doesn’t have either HTML_QuickForm or HTML_Common, so they’ll need to be installed.
pear install HTML_Common
downloading HTML_Common-1.2.3.tgz ...
Starting to download HTML_Common-1.2.3.tgz (4,746 bytes)
.....done: 4,746 bytes
install ok: HTML_Common 1.2.3

pear install HTML_QuickForm
downloading HTML_QuickForm-3.2.7.tgz ...
Starting to download HTML_QuickForm-3.2.7.tgz (102,475 bytes)
........................done: 102,475 bytes
install ok: HTML_QuickForm 3.2.7

Displaying the form

The code required to display a form is simple. Let’s start with an example:
  require_once "HTML/QuickForm.php"; // tell PHP to include the QuickForm package

  $form = new HTML_QuickForm('register', 'post');  // instantiate the object
  $form->addElement('text', 'firstName', 'Enter first name'); // add a text element
  $form->addElement('password','password', 'Enter your password'); // add a password element
  $form->addElement('textarea','ta','Description'); // add a textarea element
  $form->addElement('submit','sb','Submit form'); // add a submit button element

It should be fairly self-explanatory what this snippet does. Include the package, instantiate the object, then add a text form element (called firstName, with the text Enter your first name appearing next to it, and then add a password form element called password, with the text Enter your password next to it. Here’s what the resulting HTML looks like:
<form action="/phpbuilder/html_quickform11.php" method="post" name="register" id="register">
<table border="0">

		<td align="right" valign="top"><b>Enter first name</b></td>
		<td valign="top" align="left">	<input name="firstName" type="text" value="" /></td>

		<td align="right" valign="top"><b>Enter your password</b></td>
		<td valign="top" align="left">	<input name="password" type="password" value="" /></td>
		<td align="right" valign="top"><b>Description</b></td>
		<td valign="top" align="left">	<textarea name="ta"></textarea></td>

		<td align="right" valign="top"><b></b></td>
		<td valign="top" align="left">	<input name="sb" value="Submit form" type="submit" /></td>

As you can see HTML_QuickForm allows you to get away with a lot less typing to get the same output, so even without all the other benefits, the abstraction will at least save you some time (although I wouldn’t recommend it for just this purpose!). It also produces (with a minor exception) markup that’s XHTML Strict-compliant (with the minor exception of the legacy form name attribute, which can be easily removed). The above example utilised a text, a textarea and a password element. Here’s a list of the other elements HTML_QuickForm can add, along with the HTML_QuickForm name, and the HTML equivalent. They’re all given straighforward names, so if you know the HTML term, you’ll know the term to use here.
element HTML
button <input type=”button” />
checkbox <input type=”checkbox” />
file <input type=”file” />
hidden <input type=”hidden” />
image <input type=”image” />
password <input type=”password” />
radio <input type=”radio” />
reset <input type=”reset” />
select <select>. The <option> elements can be loaded from either an array or a database.
submit <input type=”submit” />
text <input type=”text” />
textarea <textarea>
xbutton <button>
There are also various custom element types. We’re not going to look at any examples in this tutorial, but they’re listed here for reference.
advcheckbox An advanced checkbox type, allowing checkboxes to pass multiple values.
autocomplete A text field with autocomplete. It’s a normal text element, but at each keypress JavaScript is used to read an array and autocomplete if there’s anything matching.
date A group of elements for inputting dates and times
group Allows several elements to be grouped into a single new entity.
header Allows a heading to be added to the form.
hiddenselect A select element containing hidden elements for everything already selected with the methods setDefaults() or setConstants().
hierselect A select element where choosing one item from the first select will dynamically populate a linked second select element.
html Used to be used for adding raw HTML to a form, it’s now deprecated.
link A link type field
static Static data

Validating the data

As you’ve probably discovered, clicking on the submit button in our earlier example doesn’t yet do much. If you look at the form action attribute, you’ll notice that the same script is called. To make things easier for itself, HTML_QuickForm forms reference themselves, so the same script is responsible for generating the form, validating it, and processing it if successful. To make something happen, we’ll need to add logic to process the submitted form, as well as validate the data.
Validation is the bane of many developers, but HTML_QuickForm makes it really easy to validate both on the client-side and the server-side. It does so with the addRule() method. Then, to actually perform the validation, the validate() method is called. We’ll now only display the form if it hasn’t yet been validated (the code to process the form would be called at that point). All very simple! Here’s an example with two rules, one stating that the first name is a required field, and the other that the first name must only contain letters (and this excludes names with a dash, so you may not want to do this in a real application!):
  require_once "HTML/QuickForm.php";

  $form = new HTML_QuickForm('register', 'post');
  $form->addElement('text', 'firstName', 'Enter first name');
  $form->addElement('password','password', 'Enter your password');
  $form->addElement('submit','sb','Submit form');

  $form->addRule('firstName', 'Your name is required', 'required');
  $form->addRule('firstName', 'Your name can only contain letters','lettersonly');

  if ($form->validate()) {
    // processing code goes here.
    echo 'Success!';
  else {
Try and see what happens when you submit this form with invalid data, and then again with valid data. A red star indicates that the first name is a required field. If the data is entered incorrectly (either left out, or containing anything but letters) an appropriate error message is displayed, also in red.
The above example uses the required and lettersonly rules. Here’s a list of all the rules that can be applied:
rule argument description
alphanumeric   Can only contain alphanumeric characters (letters and numbers).
compare   Compares two values.
email true (which applies a DNS check) Must be a valid email (in syntax) (checks for a valid hostname if the argument is set to true).
filename $regex The filename of the uploaded file must match the regular expression in $regex.
lettersonly   Can only contain letters.
maxfilesize $maxsize The filename of the uploaded file cannot be larger than $maxsize bytes.
maxlength $maxlength Can be at most $maxlength characters in length.
mimetype $mimetype MIME type of the uploaded file must either be of type $mimetype (if $mimetype is scalar), or match one of the elements in $mimetype (if it’s an array).
minlength $minlength Must be at least $minlength in length.
numeric   Must contain a valid integer or decimal number.
nonzero   Cannot be zero.
nopunctuation   Cannot contain any punctuation characters, which include: ( ) . / * ^ ? # ! @ $ % + = , ” ‘ > .
rangelength $minlength,$maxlength Must be inclusively between $minlength and $maxlength characters in length.
regex $regex Must match the regular expression $regex.
required   Cannot be blank
uploadedfile   Must contain a successfully uploaded file.