Formr

Formr is a PHP micro-framework which installs easily and helps you build, layout and validate forms quickly, painlessly, and without all the complicated, messy overhead.


Features

  • Create complex forms with server-side processing and validation in only minutes
  • Instantly make one field required, all fields required, or all but one field required
  • Built-in POST validation rules, including validating email, comparisons, slugging and hashing
  • Bootstrap 3 ready; automatically wrap all of your form elements and messages in Bootstrap classes
  • Automatically build and format <label> tags, saving lots of time
  • Extensible: roll your own form & validation sets and dropdown menus and share 'em with others
  • Create and validate radio groups and checkbox arrays in seconds
  • Automatically wrap field elements in <p>, <div>, <ul>, <ol>, <dl>, Bootstrap's .form-control or roll your own
  • Object-oriented; supports multiple forms per page
  • Little helpers to assist in building, layout, testing and debugging
  • And a ton of other cool stuff too!


A Quick Note on Terminology
When we're talking about methods we're referring to a function inside a PHP class. When we're talking about properties we're referring to variables inside a PHP class.
Formr does not have database capabilities, and very limited email capabilities; there are plenty of great classes out there that do that much, much better than I ever could.

Extensibility

Formr is extensible in that it has some additional classes to which you can easily modify and add methods; this should hopefully make your life a little easier by enabling you to build, save and share custom dropdown menus, CSS classes, field wrappers, and form/validation sets.

To create your own:

  1. Open the appropriate class. file in the formr/lib directory and copy a method.
  2. Paste the method into the appropriate class file in the my_classes directory.
  3. Rename and modify the method to create your own. Make sure your methods have unique names!


For now you may only add your own custom wrapper class by editing the formr/lib/class.wrappers.php file. I plan on updating the Wrapper to make it a true plugin when I can find the time.

Screencasts

If you want to dive right in without reading all of this documentation (and I wouldn’t blame you!) take a look at the following screencasts.


A Note From the Developer

Hi,

Thank you for checking out Formr. I began writing Formr for myself a couple years ago, and I’ve found it to be such an invaluable part of my toolkit that I decided to share it. I’m well aware the code behind Formr isn’t something a rock star coder would write, and that’s because I’m not a rock star coder; I just like creating things.

As with all software, there are bound to be some bugs in Formr. Heck, I’m the only person (up until now) that’s ever used it! So if you find a bug, please report it! And if you find Formr useful (bugs and all), please consider a donation. Donating even $2 will really help in allowing me to work more on improving Formr and less on the day-to-day stuff in my freelancer life.

Thanks, and I hope you find Formr as useful as I have!

— Tim


Installing and Instantiating Formr

Before you can do anything you’ll need to download Formr and put it in your project directory.

Next you’ll need to include Formr in your script and then create an instance of the Formr class. Since each form is an object, you may have as many forms as you want in each page.

Creating an instance is really easy…

// require the Formr class
require_once 'formr/class.formr.php';

// now create an instance and give it a name, such as $form
$form = new Formr();

That’s all there is to it. You’re now ready to start building your forms!


Building a Form: the Basics

Let’s begin by taking a quick look at Formr’s input_text() method, which creates a standard <input type="text"> element and is the building block of most forms. While it will take a little longer to build a form using individual methods (as opposed to using fastform()) this approach will give you the most control. Plus, knowing how the individual methods behave will give you a better understanding of how Formr works, so this is where we’ll begin.

Most Formr input methods accept 6 - 8 parameters, with only the first one being required. You can read all about Formr's methods in the Formr Methods documentation. Also, instead of filling out all parameters of the input_text() method, the first parameter may contain an associative array containing all of the data you want your field to contain.

input_text()

Lets you generate a standard text input field.

  1. The first parameter contains the field’s name and is required.
  2. The optional second parameter contains the field’s label text.
  3. The optional third parameter contains a default value.
  4. The optional fourth parameter contains the field’s ID.
  5. The optional fifth parameter contains a string, which lets you add additional attributes, CSS, JavaScript, etc.
  6. The optional sixth parameter contains the field’s inline help text (Bootstrap only).


Adding text to the second parameter will automatically create a <label> element before the <input> element. If you'd rather manually create the label yourself, leave the second parameter empty.

Example: Create a basic text input…

echo $form->input_text('fname');

// will produce
<input type="text" name="fname" id="fname">

Example: Create an input with a label, ID, default value and placeholder text

echo $form->input_text('fname','First name:','John','fname','placeholder="first name:"');

// will produce
<label for="fname">First name:</label>
<input type="text" name="fname" id="fname" value="John" placeholder="first name:">

form_open()

Opens the form with a standard <form> tag and accepts three parameters — all of them optional — so you can just leave it empty and the <form> tag will be created automatically with the proper attributes.

// assuming our script is named index.php and is in the root...
echo $form->form_open();

// will produce
<form action="/index.php" method="post" accept-charset="utf-8">

input_submit()

Creates a standard <input type="submit"> element.

echo $form->input_submit();

// will produce
<input type="submit" name="submit" value="Submit" id="submit">

Wrapping Fields

You can easily (and automatically) wrap each form field in a <div>, <p> Bootstrap .form-group or roll your own wrapper. Just pass Formr the wrapper type when instantiating your form.

// wrap each form field in a `<div>`
$form = new Formr('div');
// wrap each form field in a `<p>`
$form = new Formr('p');
// wrap each form field in a `<div class="form-group">`
$form = new Formr('bootstrap');

Example: Build a Simple Contact Form Using Bootstrap

Let’s see how easy it is to incorporate Bootstrap into our Formr workflow…

require_once 'formr/class.formr.php';

// just add 'bootstrap' as your wrapper when you instantiate Formr
$form = new Formr('bootstrap');

// now build your form...
echo $form->form_open();
echo $form->input_text('name');
echo $form->input_email('email');
echo $form->input_submit();
echo $form->form_close();

The above code produces the following HTML with full Bootstrap formatting

<form action="/index.php" method="post" accept-charset="utf-8">
    <div id="_name" class="form-group">
        <input type="text" name="name" id="name" class="form-control">
    </div>
    <div id="_email" class="form-group">
        <input type="email" name="email" id="email" autocorrect="off" autocapitalize="off" class="form-control">
    </div>
    <div id="_submit" class="form-group">
        <input type="submit" name="submit" value="Submit" id="submit" class="btn">
    </div>
</form>

Example: Repopulating the POSTed Fields

If you build your form in PHP with Formr (instead of HTML), eg; $form->input_text('fname); all fields will automatically re-populate if there is an error upon form submission. However, if you prefer to build your form fields in HTML you can still re-populate the field value after a POST with the value() method, like so:

// enter the field's name as the method's sole parameter
<input type="text" name="fname" value="<?php echo $form->value('fname'); ?>">

Example: Building and Validating a Simple Contact Form

Let’s rebuild that contact form, except this time we’ll do it within HTML, then submit the form and validate it. The following code contains a complete form that includes all of the necessary classes and libraries and performs server-side PHP validation; it checks to see if the fields are required, if the email address is valid, slugs the username (Twitter style), checks if the passwords match, and then hashes the password using the PHP password_hash() function. Notice that we’re also using Formr’s value() method, which prints the POST value in the element’s value attribute.

PHP for Processing the POST

<?php
// include and instantiate Formr
require_once 'formr/class.formr.php';
$form = new Formr();

// make all fields required
$form->required = '*';

// check if the form was submitted
if($form->submit()) {

	// process and validate the POST data
	$username = $form->post('uname','Username','slug');
	$email = $form->post('email','Email','valid_email');
	$password = $form->post('passwd','Password','min_length[6]|hash');
	$pass_conf = $form->post('passwd_conf','Confirm Password','min_length[6]|matches[passwd]');
	
	// check if there were any errors
	if(!$form->errors()) {
		// no errors
		// user has entered a valid email address, username, and confirmed their password
		echo $form->success_message('Success!');
	}
}

// print messages
echo $form->messages();
?>

The HTML Form

<form action="index.php" method="post">
    <label for="email">Email:</label>
    <input type="email" name="email" value="<?php echo $form->value('email'); ?>">
    
    <label for="uname">Username:</label>
    <input type="text" name="uname" value="<?php echo $form->value('uname'); ?>">
    
    <label for="passwd">Password:</label>
    <input type="password" name="passwd">
    
    <label for="passwd_conf">Confirm Password:</label>
    <input type="password" name="passwd_conf">
    
    <input type="submit" name="submit" value="Register">
</form>

Handling POST Data

When a form is submitted, the POST data is returned as either a string or an array, depending upon the method used to process and validate the $_POST array, and/or if you’re POSTing a string or array. For instance, if you’re posting a first_name text field, then it’ll be returned as a string. However, if you’re posting an array of text fields, then they’ll be returned as an array. Here’s how a string will be handled - which will probably be 95% of what you process.

Here’s your form field…

$form->input_text('first_name');

This is how you would get the POST value - as a string

$first_name = $form->post('first_name');

Posting an array is pretty much the same

// a checkbox array
$form->input_checkbox('foods[],Lobster,lobster,lobster');
$form->input_checkbox('foods[],Steak,steak,steak');

// POST the form, then put the foods[] array into a variable
$foods = $form->post('foods[]');

// loop through the foods[] array
foreach($foods as $key => $value) {
    // do something with the results here
    ...
}

Retrieving the value of a fast_post() array…

// get the POST value...
$post = $form->fast_post('form_name');

// get the foods array out of the $post array...
$foods = $post['foods'];

foreach($foods as $key => $value) {
    // do something with the results here
    ...
}

Hashing Input

During POST validation, Formr can return an encrypted (or hashed) string from those values by passing either md5, sha1, or hash in the post() method’s third parameter.

// hashing a password with SHA1
$password = $form->post('password','Password|A password is required','sha1');

// hashing a password using PHP's `password_hash()` function
$password = $form->post('password','Password|A password is required','hash');

HTML Purifier

While we’re still talking about validation and security now is a good time to tell you that Formr is ready for HTML Purifier - and it’s real easy to set up. Just download HTML Purifier and tell Formr where the HTML Purifier class is located (full path!) when instantiating the form.

// we're using the standalone version of HTML Purifier
$form->html_purifier = '/path/to/HTMLPurifier.standalone.php';
If you enter the wrong path to HTML Purifier, Formr will use the default cleaning methods instead.

Form Validation Rules

The following table contains all of Formr’s validation rules for the post() method.

Rule Parameter Description Example
matches Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item]
min_length Yes Returns FALSE if the form element is shorter then the parameter value. min_length[6]
max_length Yes Returns FALSE if the form element is longer then the parameter value. max_length[12]
exact_length Yes Returns FALSE if the form element is not exactly the parameter value. exact_length[8]
greater_than Yes Returns FALSE if the form element is less than the parameter value or not numeric. greater_than[8]
less_than Yes Returns FALSE if the form element is greater than the parameter value or not numeric. less_than[8]
alpha No Returns FALSE if the form element contains anything other than alphabetical characters.  
alpha_numeric No Returns FALSE if the form element contains anything other than alpha-numeric characters.  
alpha_dash No Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes.  
numeric No Returns FALSE if the form element contains anything other than numeric characters.  
integer No Returns FALSE if the form element contains anything other than an integer.  
decimal No Returns FALSE if the form element is not exactly the parameter value.  
valid_email No Returns FALSE if the form element does not contain a valid email address.  
valid_ip No Returns FALSE if the supplied IP is not valid.  
md5 No Returns an md5 encrypted string.  
sha1 No Returns an sha1 encrypted string.  
hash No Returns an encrypted string using the password_hash() function.  
sanitize_string No Passes result through the FILTER_SANITIZE_STRING function.  
sanitize_url No Passes result through the FILTER_SANITIZE_URL function.  
sanitize_email No Passes result through the FILTER_SANITIZE_EMAIL function.  
slug No Creates a Twitter-style username string containing only letters, numbers and underscores.  
strip_numeric No Strips out everything but numbers.  
allow_html No Allows HTML, script tags, etc. Use with caution!