This class was inspired by the HTML_QuickForm pear package. By the time I found out about it my code had become completely unmanageable, and the Quickform class held the promise of making my life so much easier. I was disheartened to discover that the HTML QuickForm class(es) were humongous, and required a ton of pear code besides. It didn't sit well with my KISS philosophy, so I decided to write my own class. This class does everything I had ever hoped the HTML Quickform would do and more. The great thing about this class is that it is easy enough to wrap your head around in case you need to make any changes.

With this class you will be able to create the following form fields:

Radio Buttons and Check Boxes
'radio' - Radio button(s) for a user to select one option from a set of alternatives.
'checkbox' - Checkbox(es) for a user to select one or more options from a set of alternatives.
'multicheck' - An array of checkboxes.

Select Form Fields
'select' - A menu from which a single selection can be made.
'multiselect' - A menu from which multiple selections can be made.
'hierselect' - Two select menus with the first menu controlling the options of the second menu.

Text Fields
'text' - A single line text input box.
'multitext' - An array of text fields.
'password' - A text field - only the input shows up as dots.
'file' - A file upload prompt.
'textarea' - Text fields that can span several lines.
'calendar' - A date input box with a helpful calendar using the jQuery datepicker widget.

Form Fields
'hidden' - To submit information not entered by the visitor.
'submit' - A button to submit the form to the server.

In addition it offers:

  • Complete file upload management
  • Easy integration with reCAPTCHA
  • Client side validation using the jQuery Form Validation plugin
  • Automatic server-side validation and filtering of all submitted data
  • Total control over the form layout
  • Clean (x)html code that validates

This class takes all of the form-related events of creating the form, filtering, validating, and processing the data, and puts it all into one object and one PHP page. This class will make your code more reliable, consistent, and simple.

Creates a new form object.

$class You can give your form a class name here.
Example
$form = new Form('awesome');

This method will not allow the form to be processed until all of the required fields have their appropriate values

$required An array of required form input names, ie. these fields must not be empty.
Note: multicheck, multiselect, multitext, hidden, and submit field types can not be required.
Example
$form->required(array('name', 'email', 'password'));

This method is to preselect the values of form inputs.

$values An array ('name'=>'value') of form default values.
This is optional in case you just want to return the array.
Note: multicheck and multitext values cannot be preselected here.
Returns The current array of 'name' and 'value' form default values.
Example
$form->values(array('name=>'user', 'email'=>'your@email.com'));

These are the form inputs you want to check and make sure that they have the kind of values you expect of them.

$check An array('name'=>'filter') of the form values you want returned. Refer to the data method of the Validation Class for the available filters and how to format them (don't worry, it's easy). You can also give the name of another form field to filter the value against. eg. to confirm a password or email address.
Example
$form->check(array('name'=>'', 'email'=>'email', 'password'=>'pass'));

To process[] multicheck and multitext input. We have this method because of the browsers bad habit of not returning multicheck values that are unselected. It is not necessary, but if you have multitext inputs with all of the same array keys, you might as well include them here with the multichecks. Don't forget to include a $form->field('hidden', 'process', $key) with each multicheck.

$process An array ('name'=>'filter') of the form values you want to process.
Example
$form->process(array('delete'=>'YN'));

This method will make sure the file(s) are of the correct type, and if so upload them to your uploads folder. If successful it will add to the $vars array returned by the $form->validate() function the files name. If unsuccessful it will trigger an error to alert you of what is happening, and inform the user they need to try again (if the field is required).

$upload An array ('name'=>'types') of files to upload.
type(s): (can also be it's own array)
'jpg' - jpeg, jpg, pjpeg
'gif'
'png'
'bmp' - bitmap
'swf' - flash
'doc' - ms word
'txt'
'pdf'
'ppt' - powerpoint
'xls' - excel
'xml'
'mpeg' - all types
'mov' - quicktime videos
'zip'
$filesize The maximum file size your form will upload in megabytes - the math is done in house to give the browser what it wants in bytes. Default is 5.
Example
$form->upload(array('image'=>array('jpg', 'gif', 'png')), 2);

This is where you collect all of the user-submitted information, process it, then send them on their merry way.

$form The name of the form. Must be the same as the $name indicated in the $form->header() method coming up.
$function This function will filter all form data. The default is 'escape_data' which will make all of the submitted form data safe to insert into a MySQL database.
Returns An array of 3 values:
1) A $vars['name'] = $value array of all of the $form->check(), $form->process(), and $form->upload() methods previously called.
2) An $errors array that you don't need to worry about. You only need to know that it is empty which means it is safe to process all $vars.
3) An $eject string to know where to send the user so that they can't hurt themselves by resubmitting the same form over and over again when they click their browsers back button.
Example
list($vars, $errors, $eject) = $form->validate('formname'); 
if (!empty($vars) && empty($errors)) { 
  $html .= '<pre>' . print_r($vars, true) . '</pre>'; 
  // $page->eject ($eject, 'Thanks!<br />Your form submission was successful.'); 
}

If you have your own special validation routine, this method allows you to do your thing, make a custom error, and have your user try again.

$name The name of the form element you would like to reject.
$message A note to the user on how they can make things right.
Returns An array of errors, if any, so that you can call this method one last time at the end of your conditionals and get a yea or nay on whether you should proceed or not.
Example
if ($vars['name'] != 'what I like') { 
  $form->error('name', 'Sorry Charlie, try again.'); 
} 
if (empty($form->error())  { // Continue . . .

This gives your form a nice layout by lining up your prompts and fields into separate columns down the page.

$size The size (in pixels) that you would like your prompts to occupy.
Example
$form->prompt(100);

This is what gets the party started. Everything until now was just setting up for the action.

$name The name of the form. Make sure it is the same as you called in $form->validate ($form).
$method Either 'get', or 'post'. Default is 'post'.
$action It's best to leave this blank. The form will automatically process itself where it is but with an added parameter so that after you process the form and $page->eject() them, they will go back to the same page only the browser is tricked so that when the user pushes the back button, your form isn't resubmitted with all the same old information.
Returns A string of code to add to your $html.
Example
$html .= $form->header('formname');

This method creates the actual form fields. You tell it the $type of field, what you want to $name it, $prompt the user so they know what to input, and give them (including the input field) their $options. There's a lot you can do with this method so we're just going to take it one type at a time.

$type Radio Buttons and Check Boxes
'radio' - Radio button(s) for a user to select one option from a set of alternatives.
'checkbox' - Checkbox(es) for a user to select one or more options from a set of alternatives.
'multicheck' - An array of checkboxes.

Select Form Fields
'select' - A menu from which a single selection can be made.
'multiselect' - A menu from which multiple selections can be made.
'hierselect' - Two select menus with the first menu controlling the options of the second menu.

Text Fields
'text' - A single line text input box.
'multitext' - An array of text fields.
'password' - A text field - only the input shows up as dots.
'file' - A file upload prompt.
'textarea' - Text fields that can span several lines.
'calendar' - A date input box with a helpful calendar using the jQuery datepicker widget.

Form Fields
'hidden' - To submit information not entered by the visitor.
'submit' - A button to submit the form to the server.
$name This field's input name and id. If this is a hidden field whose name is 'process', it will be turned to an array ('process[]').
$prompt Comes right before the form field to let the user know what to input, except for the 'hidden' form field where the $prompt is it's value.
$options This means different things to different types. Click on each field type for clarification.
$key This is the (optional) array key for 'multicheck' and 'multitext' form fields.
Returns A string of code to add to your $html.
$values An array of values for each button in the group.
Example
$html .= $form->field('radio', 'gender', 'Gender:', array('M'=>'Male', 'F'=>'Female'));
$values A key and value pair giving a single $value=>$description combo.
Example
$html .= $form->field('checkbox', 'terms', '', array('Y'=>'I accept your terms and conditions');
$value The checkbox's value.
$key This is an optional array key. If you include it then don't forget the hidden process field.
Example
$html .= $form->field('multicheck', 'add', 'Four', 'Y', 4) . $form->field('hidden', 'process', 4); 
$html .= $form->field('multicheck', 'add', 'Eight', 'Y', 8) . $form->field('hidden', 'process', 8); 
$html .= $form->field('multicheck', 'add', 'Fifteen', 'Y', 15) . $form->field('hidden', 'process', 15);
$values An array of values.
Example
$html .= $form->field('select', 'color', 'Personality:', array('r'=>'Red', 'b'=>'Blue', 'w'=>'White', 'y'=>'Yellow'));
$values An array of values.
Example
$html .= $form->field('multiselect', 'lost', 'Candidates:', array(4=>'John Locke', 8=>'Hugo Reyes', 15=>'James Ford', 16=>'Sayid Jarrah', 23=>'Jack Shephard', 42=>'Jin & Sun Kwon'));
$values A multi-dimensional array including a 'hier' key of the next select menus name.
Example
$categories = array(); 
$subcategories = array(); 
 
#-- Our Multi-Dimensional Array for the Hierselect Category --# 
$categories['hier'] = 'subcategory'; 
$categories[0] = array(1=>'Planes', 2=>'Trains',  3=>'Automobiles'); 
$categories[1] = array(1=>'Cessna 172', 2=>'Learjet', 3=>'Boeing 747'); 
$categories[2] = array(4=>'Amtrak', 5=>'The Alaska Railroad', 6=>'Bullet Train'); 
$categories[3] = array(7=>'Volkswagen Beetle', 8=>'Hummer', 9=>'Bugatti Veyron'); 
$values = $form->values(); 
if (isset($values['category'])) { // This is to preload the subcategories if a category has already been selected 
  $selected = $values['category']; 
  $subcategories = $categories[$selected]; 
} 
 
$html .= $form->field('hierselect', 'category', 'Category:', $categories)) . '<br />'; 
$html .= $form->field('select', 'subcategory', 'Subcategory:', $subcategories));
$options Default: array('width'=>200, 'maxlength'=>50)
Example
$html .= $form->field('text', 'email', 'Email:', array('width'=>250, 'maxlength'=>60));
$options Default: array('width'=>250, 'maxlength'=>50, 'value'=>'')
Multitext values can't be preselected unless you do so here.
$key This is an optional array key.
Example
$html .= $form->field('multitext', 'amount', 'Item 16:', array('width'=>50, 'maxlength'=>10), 16); 
$html .= $form->field('multitext', 'amount', 'Item 23:', array('width'=>50, 'maxlength'=>10), 23); 
$html .= $form->field('multitext', 'amount', 'Item 42:', array('width'=>50, 'maxlength'=>10, 'value'=>108), 42);
$options Default: array('width'=>100, 'maxlength'=>20)
Example
$html .= $form->field('password', 'password', 'Password:');
$option Default: array('size'=>50)
Example
$html .= $form->field('file', 'image', 'Image:');
$options Default: array('width'=>400, 'height'=>200)
Example
$html .= $form->field('textarea', 'comments', 'Comments:<br />');
Example
$html .= $form->field('calendar', 'date', 'Date:');
$value The hidden input's value.
$option This is where you can give your hidden input field an id for javascript's sake.
ie. array('id'=>'accessible');
Example
$html .= $form->field ('hidden', 'secret', 'value');
$name The name of your submit button.
$prompt Put '&nbsp;' here if you've set a value for the $form->prompt() and want the submit button to be inline with the form fields.
Example
$html .= $form->field('submit', 'Submit');

Automatic and easy integration with reCAPTCHA. Check it out at their site recaptcha.net. All you need to do is sign up and include their functions at the top of your page. Don't forget to add 'recaptcha' to your required array.

Returns A string of code to add to your $html.
Example
$form->required(array('recaptcha')); // Declare this before you validate the form. 
$html .= $form->recaptcha();

Closes up shop, and finishes your form's code.

Returns A string of code to add to your $html.
Example
$html .= $form->close();
Download