PHP Form Class Documentation

This page provides instructions for the PHP Form Class and shows how to use its methods for generating (X)HTML forms. An example demonstrates, showing both the source code and the resulting form.

To use the PHP Form Class, you include or require its class file in your document and create an HTML_Form instance. By default, form elements will be output using XHTML syntax[1], but you can specify regular HTML by passing false to the constructor.

require('includes/html_form.class.php');

$frm = new HTML_Form(false); // pass false for html rather than xhtml syntax

Next, start the form and begin adding form elements using the methods provided by the PHP Form Class.

About the Form Class Methods

Each of the PHP Form Class methods returns a string which you can assign to a variable or echo/print. The methods for adding form elements have named arguments for the required and most common attributes. You can use an optional associative array to add any other attributes you wish.

Start and End Form

The form class includes methods for starting and ending a form: startForm and endForm. Specify the action attribute when you start the form, that is, the page you wish the form to be submitted to:

/** startForm arguments:
  *   action, method (default is post), id (optional),
  *   associative array of additional attributes (optional)
  */
$str = $frm->startForm('result.php');

// [form elements get added here]

// end form when done
$str .=  $frm->endForm();

The following demonstrates how to add class and onsubmit attributes using the optional associative array argument mentioned above:

$str = $frm->startForm('result.php', 'post', 'myForm',
    // add optional attributes in associative array
    array('class' => 'demoForm',
        'onsubmit' => 'return checkBeforeSubmit(this)') );

All the methods for adding elements provide the opportunity to add optional attributes using associative array syntax.

addInput Method

The addInput method is used to add input elements, including text, checkbox, radio, hidden, password, submit, image, and the new HTML5 input types. It has named arguments for type, name, and value. A text box with just these attributes is added as follows:

// arguments: type, name, value
$str .= $frm->addInput('text', 'firstName', 'Sharon');

The following demonstrates adding a text input with additional attributes included in the optional associative array argument:

$str .= $frm->addInput('text', 'firstName', 'Sharon', 
    array('id'=>'firstName', 'size'=>16, 'maxlength'=>50) );

Radio buttons, checkboxes, submit and image buttons, hidden, and password elements all use the addInput method:

// checkbox
echo $frm->addInput('checkbox', 'brownies', 'likes');

// radio
echo $frm->addInput('radio', 'gender', 'male');
echo $frm->addInput('radio', 'gender', 'female');

// submit
echo $frm->addInput('submit', 'submit', 'Submit');

These can be seen, along with the full source code, in the PHP Form Class example. ^

addLabelFor Method

The form class includes an addLabelFor method. The following adds a label element for the text box just demonstrated:

// arguments: for (id of associated form element), text
echo $frm->addLabelFor('firstName', 'First Name: ');

The addInput and addLabelFor methods result in the following display:

If you are using a label with a for attribute, the form element needs an ID, which would be added using the associative array. If you would like to use a label element to contain a form element, you can use the startTag and endTag methods described below.

addTextArea Method

To add a text area, use the addTextArea method. Default values are provided for rows (4) and columns (30), or you can specify your own:

// arguments: name, rows, cols, value, optional assoc. array 
echo $frm->addTextArea('comments', 4, 40, '',
    array('id'=>'comments', 'placeholder'=>'[your comments]') );

Notice the example demonstrates with the HTML5 placeholder attribute which is supported by an increasing number of browsers. ^

Select List Methods

The PHP Form Class includes two methods for generating select lists: addSelectListArrays, used when option text and values are in separate arrays; and addSelectList, used when option text and values are both contained in a single array, or when the text will serve as the value.

An example demonstrating addSelectListArrays uses a months array for the option tag content and the PHP range function to generate numbers from 1 to 12 for the option values:

$months = array('January', 'February', 'March', 'April', 'May', 'June', 'July', 
        'August', 'September', 'October', 'November', 'December');
    
/** addSelectListArrays arguments:
  *   name, array containing option values, array containing option text,
  *   optional: selected option's value, header, additional attributes in associative array
  */
echo $frm->addSelectListArrays('month', range(1, 12), $months, '', ' - Month - ');

Resulting select list:

An example demonstrating addSelectList uses an array whose values will constitute the option tag content and leaves out the value attributes by setting the third argument to false:

$rank_ar = array('Totally lame', 'Minimally useful', 
        'Pretty good', 'I realy like it', 'Fabulous');

/** addSelectList arguments: 
  *   name, array containing option text/values
  *   include values attributes (boolean),
  *   optional arguments: selected value, header,
  *   additional attributes in associative array
  */
echo $frm->addSelectList('rank', $rank_ar, false, 'Fabulous');

Resulting select list:

When the third argument is set true for a numerically indexed array, the values assigned to the option elements are 0, 1, 2, etc. ^

Add Elements using startTag, endTag, addEmptyTag

The PHP Form Class provides methods that allow you to add other elements (for example: fieldset, legend, paragraphs, or divs) to contain form elements and give structure to your form. To wrap form elements in a paragraph, for example, pass the tag name to the startTag method:

// to wrap form elements in a paragraph 
$str .= $frm->startTag('p');
// add form element(s) here

// end tag
$str .= $frm->endTag();

The endTag method will remember the last tag opened so you don't always need to pass an argument. But if you are nesting elements, pass the tag name of the tag you want to close if it is other than the last one opened.

The startTag method also accepts an associative array of optional attributes to add to the tag, just as other methods of the form class do. The example uses the startTag and endTag methods extensively and includes comments.

Note: The PHP Form Class does not do error checking or validation for you. This shouldn't be a problem if you use the code with care. It would certainly be a good idea to send your page through an HTML validator to double check your work!

Demo, Download, and More

View the PHP Form Class file as well as an example demonstrating its use. The download file provides the PHP Form Class file and an example document.

See the PHP Table Class which is well suited for use with the form class. See also the PHP Order Form for a demonstration of the form class used in combination with the PHP Table Class.

Back to top


  1. Input and other empty tags will be closed and minimized or boolean attributes will be expanded. ^