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 issues via the PEAR bug tracker or Github issues.

Pull requests are welcome.

Installation

The package may be installed either with PEAR

$ pear install HTML_QuickForm2

or with composer

$ composer require pear/html_quickform2

Since release 2.1 composer installation relies completely on autoloading and does not contain require_once calls or use include-path option.

Basic usage

require_once 'HTML/QuickForm2.php'; // Only when installed with PEAR

$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

$ phpunit tests/

after installing dependencies with composer. You can also test the installed package with

$ phpunit [PEAR tests dir]/HTML_QuickForm2

Since PEAR package needs its require_once statements re-enabled, please run the helper file before packaging and installing

$ php pear-package-helper.php

Then to build, simply

$ pear package .pear-package/package.xml

To install from scratch

$ pear install .pear-package/package.xml

To upgrade

$ pear upgrade -f .pear-package/package.xml