README

This is a repository for PEAR HTML_QuickForm2 package that has been migrated from PEAR SVN.

HTML_QuickForm2 provides methods to create, validate and render HTML forms. It is a PHP5 rewrite of PEAR HTML_QuickForm and related packages.

Features:

• Supports all form elements defined in HTML4, provides several custom elements. Support for HTML5 form elements is planned.
• Server-side and client-side validation, several common rules provided. Validation rules can be combined with 'and' and 'or' for complex validation scenarios. Client-side validation can be run on changing the form field and on submitting the form.
• Client-side validation and Javascript-backed elements use a small self-contained JS library, there is no dependency on JS frameworks.
• Multipage forms (tabbed forms and wizards) are possible.
• Pluggable elements, rules, renderers and renderer plugins.

Please report all issues via the PEAR bug tracker.

Pull requests are welcome.

Basic usage

require_once 'HTML/QuickForm2.php';

$form = new HTML_QuickForm2('tutorial');

// Set defaults for the form elements
$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
    'name' => 'Joe User'
)));

// Add some elements to the form
$fieldset = $form->addElement('fieldset')->setLabel('QuickForm2 tutorial example');
$name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
                 ->setLabel('Enter your name:');
$fieldset->addElement('submit', null, array('value' => 'Send!'));

// Define filters and validation rules
$name->addFilter('trim');
$name->addRule('required', 'Please enter your name');

// Try to validate a form
if ($form->validate()) {
    echo '<h1>Hello, ' . htmlspecialchars($name->getValue()) . '!</h1>';
    exit;
}

// Output the form
echo $form;

Additional examples are in the docs/examples directory.

Documentation

...is available on PEAR website

• Tutorial
• Migration from HTML_QuickForm and HTML_QuickForm_Controller
• Form elements overview
• Elements' values and validation
• Form output customization and Javascript support
• Multipage forms

Generated API documentation for the current release is also there.

Testing, Packaging and Installing (Pear)

To test, run either

$ phpunit tests/

or

$ pear run-tests -r

To build, simply

$ pear package

To install from scratch

$ pear install package.xml

To upgrade

$ pear upgrade -f package.xml