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.
- 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 4 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
.form-controlor roll your own
- Built-in, easy to use CSRF protection
- Object-oriented; supports multiple forms per page
- Little helpers to assist in building, layout, testing and debugging
- And a ton of other cool stuff!
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 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:
- Open the appropriate
class.file in the
formr/libdirectory and copy a method.
- Paste the method into the appropriate class file in the
- Rename and modify the method to create your own. Make sure your methods have unique names!
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
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!
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…
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.
input_text()method, the first parameter may contain an associative array containing all of the data you want your field to contain.
Lets you generate a standard text input field.
- The first parameter contains the field’s name and is required.
- The optional second parameter contains the field’s label text.
- The optional third parameter contains a default value.
- The optional fourth parameter contains the field’s ID.
- The optional sixth parameter contains the field’s inline help text (Bootstrap only).
<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…
Example: Create an input with a label, ID, default value and placeholder text
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.
Creates a standard
<input type="submit"> element.
You can easily (and automatically) wrap each form field in a
.form-group or roll your own wrapper. Just pass Formr the wrapper type when instantiating your form.
Example: Build a Simple Contact Form Using Bootstrap
Let’s see how easy it is to incorporate Bootstrap into our Formr workflow…
The above code produces the following HTML with full Bootstrap formatting
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:
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
Notice that we’re also using Formr’s
value() method, which prints the
POST value in the element’s
PHP for Processing the POST
The HTML 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…
This is how you would get the
POST value - as a string
Posting an array is pretty much the same
Retrieving the value of a
POST validation, Formr can return an encrypted (or hashed) string from those values by passing either
hash in the
post() method’s third parameter.
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.