Proposal for "Structures_Form"

» Metadata » Status
» Description
A generic input form package which can be extended for any type of front end such as HTML, CLI or PHP-GTK 2.

This package was originally designed to make it easy to add forms to PHP-GTK 2 packages and applications. This package separates the data management from the display of the form. The package is modeled after HTML_QuickForm but cannot extend HTML_QuickForm because HTML_QuickForm is tied too tightly to HTML.

PHP-GTK 2 forms are very similar to HTML forms. They consist of a handful of different input types and the data is submitted all together when a user clicks the submit button. The difference is how the user values are submitted and stored. HTML forms submit data in an HTTP request using either GET or POST. PHP-GTK 2 forms call a callback which is then responsible for retrieving the values.

While this package was originally designed for PHP-GTK 2 applications, the main class, Structures_Form, does not use any PHP-GTK 2 specific code. This makes the class very flexible. A CLI renderer could easily be applied to allow the quick and easy creation of command line forms.


  1. Flexible enough to allow just about any element type you can think of.
  2. Element groups allow for elements to be logically and visually grouped on display.
  3. Validation rules can be registered and unregistered on the fly.
  4. Any class that implements Structures_Form_ElementInterface can be used as a form element.
  5. Any class that implements Structures_Form_GroupInterface can be used as a form element group.
  6. Any class that implements Structures_Form_RuleInterface can be used as a rule in the form.
  7. Any class that implements Structures_Form_RendererInterface can be used to display a form.
  8. Elements, Element Groups, and Renderers can all be registered independantly or using an ElementSet.
  9. Structures_Form is lightweight. Files are not included until they needed, reducding overhead and improving speed.
  10. All classes included in the package will be fully unit tested (PEAR::PHPUnit2) before the first beta release. (Unit tests must wait until the API is stable)

In order to make it possible to create elements on the fly without restricting the number of constructor arguments this package must use the Reflection API. This means that the user must have reflection enabled.

In HTML_QuickForm, all form elements extend a common base class. In PHP-GTK 2 this is not possible because the elements need to be added to containers. To be added to a container a class must extend GtkWidget. While it is not possible to force all form elements to inherit from the same base class we can use an interface to enforce consistency.

Element, group and renderer classes will be defined in sub-packages such as Structures_Form_Gtk2. Separating the elements into different classes (based on UI type) prevents the user from having to download a gigantic package full of files they won't need.
» Dependencies » Links
  • PHP >= 5.1.2
» Timeline » Changelog
  • First Draft: 2006-03-23
  • Proposal: 2006-03-23
  • Call for Votes: 2006-04-14
  • Scott Mattocks
    [2006-03-23 20:29 UTC]

    Bug fix in getGroups().
    Search through groups when element is not found in getElement().
  • Scott Mattocks
    [2006-03-30 18:02 UTC]

    Added Structures_Form_Exception class.
    Added swapElementSet method to easily change from one frontend to another.
  • Scott Mattocks
    [2006-03-31 16:12 UTC]

    Fix Structures_Form_Exception class name typo.
    Make Required rule report element label not name.
  • Scott Mattocks
    [2006-04-13 19:46 UTC]

    Use path constants consistently.