README

This is a small PHP class that makes it easy to build and output forms as HTML or XHTML. Forms are tedious and can be difficult to build just right. Also, there are so many different option possible that it's easy to forget what you can do with them.

I tried to balance ease-of-use with flexibility and came up with something I find pretty darn helpful. I'm considering this a "beta" for the time being since it's only being used in a few applications and all the different options have not been exhaustively checked.

Give it a try and let me know what you like, hate, and think needs to be fixed.

Working with the form builder

The process for creating a form is simple:

Instantiate the class
Change any form attributes, if desired
Add inputs, in order you want to see them
Output the form

Let's walk through these one by one

1) Instantiate the class

This is pretty simple:

$new_form = new PhpFormBuilder();

This uses all the default settings for the form, which are as follows:

action: empty, submit to current URL
method: post
enctype: application/x-www-form-urlencoded
class: none
id: none
markup: html
novalidate: false
add_nonce: false
add_honeypot: true
form_element: true
add_submit: true

Explanations for each of the settings are below

You can also instantiate by passing in a URL, which becomes the action for the form:

$new_form = new PhpFormBuilder('http://submit-here.com');

2) Change any form attributes, if desired

Once the form has been created, use the set_att function to change the default attributes:

// Add a new form action
$new_form->set_att('action', 'http://submit-here.com');

// Change the submit method
$new_form->set_att('method', 'get');

// Change the enctype
$new_form->set_att('enctype', 'multipart/form-data');

// Can be set to 'html' or 'xhtml'
$new_form->set_att('markup', 'xhtml');

// Classes are added as an array
$new_form->set_att('class', array());

// Add an id to the form
$new_form->set_att('id', 'xhtml');

// Adds the HTML5 "novalidate" attribute
$new_form->set_att('novalidate', true);

// Adds a WordPress nonce field using the string being passed
$new_form->set_att('add_nonce', 'build_a_nonce_using_this');

// Adds a blank, hidden text field for spam control
$new_form->set_att('add_honeypot', true);

// Wraps the inputs with a form element
$new_form->set_att('form_element', true);

// If no submit type is added, add one automatically
$new_form->set_att('form_element', true);

Currently, there are some restrictions to what can be added but no check as to whether the classes or ids are valid so be mindful of that.

3) Add inputs, in order you want to see them

Inputs can be added one at a time or as a group. Either way, the order they are added is the order in which they'll show up.

Add fields using their label (in human-readable form), an array of settings, and a name/id slug, if needed.

$new_form->add_input('I am a little field', array(), 'little_field')

Argument 1: A human-readable label that is parsed and turned into the name and id, if these options aren't explicitly set. If you use a simple label like "email" here, make sure to set a more specific name in argument 3.
Argument 2: An array of settings that are merged with the default settings to control the display and type of field. See below for default and potential settings here.
Argument 3: A string, valid for an HTML attribute, used as the name and id. This lets you set specific submission names that differ from the field label.

Default and possible settings for field inputs (argument 2):

type

Default is "text"
Can be set to anything and, unless mentioned below, is used as the "type" for an input field
Setting this to "title" will output an h3 element using the label text
Setting this to "textarea" will build a text area field
Using "select" in combination with the "options" argument will create a dropdown.

name

Default is argument 3, if set, or the label text formatted
This becomes the "name" attribute on the field

id

Default is argument 3, if set, or the label text formatted
This becomes the "id" attribute on the field and the "for" attribute on the label

label

Default is argument 1, can be set explicitly using this argument

value

Default is empty
If a $_REQUEST index is found with the same name, the value is replaced with that value found

placeholder

Default is empty
HTML5 attribute to show text that disappears on field focus

class

Default is an empty array
Add multiple classes using an array of valid class names

options

Default is an empty array
The options array is used for fields of type "select," "checkbox," and "radio." For other inputs, this argument is ignored
The array should be an associative array with the value as the key and the label name as the value like array('value' => 'Name to show')
The label name for the field is used as a header for the multiple options (set "add_label" to "false" to suppress)

min

Default is empty
Used for types "range" and "number"

max

Default is empty
Used for types "range" and "number"

step

Default is empty
Used for types "range" and "number"

autofocus

Default is "false"
A "true" value simply adds the HTML5 "autofocus" attribute

checked

Default is "false"
A "true" value simply adds the "checked" attribute

required

Default is "false"
A "true" value simply adds the HTML5 "required" attribute

add_label

Default is "true"
A "false" value will suppress the label for this field

wrap_tag

Default is "div"
A valid HTML tag name for the field wrapper.
Set this to an empty string to not use a wrapper for the field

wrap_class

Default is an array with "form_field_wrap" as the only value
Classes should be added as an array of valid HTML class names

wrap_id

Default is empty
Add an id to this field by passing a string

wrap_style

Default is empty
This string of text will be added within a style attribute

4) Output the form

One quick statement outputs the form as HTML:

$new_form->build_form();

Roadmap

There are a few things that I'd like to correct here and a few features to add. In order of priority:

Validation for adding classes and ids
Add fieldsets and legends
Function to change the default field settings
Add ability to set selected and checked for select and multiple checkboxes
More strict name generation
Ability to add HTML within the form
'html_before' and 'html_after' for form attributes

joshcanhelp / php-form-builder

Maintainers

Details