Methods

This document contains a list of Formr's public methods, grouped by functionality.

Form Builders

create_form

This method allows you to create a form by entering the form's label text.

The only parameter contains a comma separated string of your form's labels and is required.

Build a basic form

$form->create_form('Name, Email');

Produces the following HTML

<form action="/index.php" id="myForm" method="post" accept-charset="utf-8">
    <label for="name">Name</label> 
    <input type="text" name="name" id="name" class="input">

    <label for="email">Email</label> 
    <input type="email" name="email" id="email" class="input">

    <button type="submit" name="button" id="button" class="button">Submit</button>
</form>

The default behavior is to create each form element as <input type="text">. If you want to specify an element type, just add a pipe character and the type of element you want to use.

Specify input types

$form->create_form('Name, Comments|textarea');

Produces the following HTML

<form action="/index.php" id="myForm" method="post" accept-charset="utf-8">
    <label for="name">Name</label> 
    <input type="text" name="name" id="name" class="input">

    <label for="comments">Comments</label> 
    <textarea name="comments" id="comments" class="input" ></textarea>

    <button type="submit" name="button" id="button" class="button">Submit</button>
</form>

Tip

Formr will create an <input type="email"> element if your label text contains the word email.

create_form_multipart

Identical to create_form() except that it adds the <form enctype="multipart/form-data"> attribute.

create

Identical to create_form() except that it omits the <form></form> tags and submit button.

Warning

The create(), create_form(), and create_form_multipart() form building methods are meant for rapid creation of basic forms, so they won't fully support all input element types, such as select, checkbox, or radio. If you require those elements, consider using fastform(), or build the form element-by-element.

fastform

This method allows you to build incredibly complex forms using simple key/value arrays and strings. Read the FastForm docs for complete examples. Validate with the fastpost() method;

1. The first parameter contains the array (or string) and is required.
2. If you'd like to add CSRF protection, just enter either the desired SESSION timeout duration (in seconds), CSRF, or TRUE in the second parameter. CSRF and TRUE default to a 3600 second (1 hour) timeout.

Example

$form->fastform('login');

Produces the following HTML

<form action="/index.php" id="login" method="post" accept-charset="utf-8">
    <fieldset>
        <input type="text" name="username" id="username" class="input" placeholder="username">
        <input type="password" name="password" id="password" class="input" autocorrect="off" autocapitalize="off" placeholder="password">
        <input type="submit" name="submit" value="Login" id="submit" class="button">
    </fieldset>
</form>

Warning

When using CSRF protection you must enable sessions by adding session_start() at the top of your file.

fastform_multipart

Identical to fastform() except that it adds the <form enctype="multipart/form-data"> attribute.

---

Form Processors

validate

This method allows you to retrieve and validate a form's values by entering only the form's label text. Read the Validate Form docs for complete examples.

The only parameter contains a comma separated string of your form's labels and is required.

Validate a basic form

$form->validate('Name, Email, Comments');

All form values are put into an array, so it's really easy to retrieve them.

Retrieve values

$data = $form->validate('Name, Email, Comments');

$name = $data['name'];
$email = $data['email'];
$comments = $data['comments'];

You can add validation rules to each field by wrapping them in parenthesis. Each rule must be separated by a pipe character. If a field is named Email it will automatically have the valid_email rule applied.

Validate values

$form->validate('Name(min[2]|max[60]), Email, Comments(min[5])');

post

This method allows you to retrieve and validate a form's values with much more control and fine-tuning then the validate() method.

1. The first required parameter is the form field's name.
2. The optional second parameter contains a human readable field name and custom error message.
3. The optional third parameter contains validation rules.

Basic example

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

Make sure a valid email address is posted

$email = $form->post('email','Email','valid_email');

Password is not less than 6 characters and not more than 20

$password = $form->post('password','Password','min[6]|max[20]');

Create a custom error message

$email = $form->post('email','Email|Enter your email address','valid_email');

Info

The form data is passed through PHP's trim() and strip_tags() functions for basic sanitation. If you want to allow HTML in your forms, just add the allow_html validation rule in the third parameter and only trim() will be applied to the input.

get

Identical to post() except that it retrieves values via PHP's $_GET array.

fastpost

This method will return an array of key/value pairs, and perform validation. Read the FastForm docs for complete examples. Use with the fastform() method.

1. The only parameter contains an array, or the form name as a string, and is required.

Example

<?php
    require 'Formr/class.formr.php';
    $form = new Formr\Formr();

    if($form->submitted()) {
        $data = $form->fastpost('login');

        $username = $data['username'];
        $password = $data['password'];
    }
?>
 <!DOCTYPE html>
 <html lang="en">
 <body>
     <div class="container">
         <?php $form->fastform('login'); ?>
     </div>
 </body>
 </html>

redirect

This method lets you redirect to another URL after the form has been submitted.

The only parameter contains the redirection URL and is optional. If left blank, Formr will redirect to the current URL.

Example

if ($form->submitted()) {
    $form->redirect('https://mysite.com/thankyou');
}

submitted

The submitted() method checks to see if the form has been submitted or not. It does this by checking the $_SERVER['REQUEST_METHOD'] for POST.

Example

if ($form->submitted()){
    // form is submitted via POST
}

---

Form Tags

open

Creates a standard <form> tag.

Opens a form with a standard <form> tag and accepts six parameters. All parameters are optional, so you can just leave it empty and the <form> tag will be created automatically with the proper attributes.

1. The optional first parameter contains the form's name.
2. The optional second parameter contains the form's ID.
3. The optional third parameter contains the form's action.
4. The optional fourth parameter contains the form's method. Default is POST.
5. The optional fifth parameter contains a string, which lets you add CSS, JavaScript, etc.
6. The optional sixth parameter contains an associative array which creates hidden fields.

Opening a form and setting an ID

$form->open('MyForm');

Produces the following HTML (assuming our script's filename is form.php)

<form action="form.php" name="MyForm" id="MyForm" method="post" accept-charset="utf-8">

Adding the form action manually

$form->open('','','contact.php','','class="bar"');

Produces the following HTML

<form action="contact.php" method="post" accept-charset="utf-8" class="bar">

Adding hidden input fields

Hidden fields can be added by passing an associative array to the sixth parameter, where the array key is the field name and the array value is the field's value.

$hidden = [
    'username' => 'JohnWick',
    'email' => 'johnwick@gunfu.com'
];

$form->open('form.php', '', '','','',$hidden);

Produces the following HTML

<form action="form.php" name="MyForm" id="MyForm" method="post" accept-charset="utf-8">

<input type="hidden" name="username" id="username" value="JohnWick">
<input type="hidden" name="email" id="email" value="johnwick@gunfu.com">

Notice

If an action isn't specified, open() will assume you want to process the form in the current script and will add the script's filename in the form's action attribute using $_SERVER['SCRIPT_NAME'].

Notice

open() will always add the attribute <form accept-charset="utf-8">, unless you change the $charset property.

Warning

The global property $form->id will override the second parameter of open().

open_multipart

This method is identical to open() except that it adds the <form enctype="multipart/form-data"> attribute.

close

Closes the form with a standard </form> tag.

Example

$form->close();

Produces the following HTML

</form>

---

Text Inputs

text

Creates an <input type="text"> element.

1. The required first parameter contains the field's name.
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 CSS, Placeholders, JavaScript, etc.
6. The optional sixth parameter utilizes Bootstrap's or Bulma's help text.

Info

If an ID is not entered in the fourth parameter, it will be created using the name.

Create a text input element

$form->text('name');

Produces the following HTML

<input type="text" name="name" id="name">

Create a text input element with a label and default value

$form->text('name','Your name','John Wick');

Produces the following HTML

<label for="name">Your name</label> 
<input type="text" name="name" id="name" value="John Wick">

Create a text input element with a placeholder, and additional class to a Bootstrap input

$form->text('name','','', '', 'placeholder="Name" class="gunfu"');

Produces the following HTML

<input type="text" name="name" id="name" value="" placeholder="Name" class="form-control gunfu">

Create a text input element using an associative array

$data = [
    'name' => 'name',
    'label' => 'Your name',
    'id' => 'name',
    'value' => '',
    'maxlength' => '32',
    'class' => 'input',
    'placeholder' => 'Enter your name...'
];

$form->text($data);

Produces the following HTML

<label for="name">Your name</label> 
<input name="name" id="name" maxlength="32" class="input" placeholder="Enter your name..." type="text">

Formr also supports adding Bootstrap and Bulma inline help classes.

Adding inline help

$form = new Formr\Formr('bootstrap');

$form->text('name','Name','John Wick','','','please enter your name');

Produces something like...

<div id="_name" class="form-group">
    <label for="name">Name</label>
    <input name="name" id="name" value="John Wick" type="text" class="form-control">
    <p class="form-text">please enter your name</p>
</div>

Tip

You can also specify if you want the .form-text text to show only when there's a form error on that field by wrapping the string with square brackets [ ]

$form->text('name','Name','','','','[please enter your name]');

color

Identical to text() except that it creates an <input type="color"> element.

date

Identical to text() except that it creates an <input type="date"> element.

datetime

Identical to text() except that it creates an <input type="datetime-local"> element.

email

Identical to text() except that it creates an <input type="email"> element.

error

Prints the element's error message to the screen.

Example

$form->text('name', 'Name');
$form->error('name');

hidden

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

1. The required first parameter contains the field's name.
2. The required second parameter contains the field's value.

Example

$form->hidden('fname','John');

Produces the following HTML

<input type="hidden" name="fname" id="fname" value="John">

Create hidden elements with an associative array

$data = [
    'name' => 'John Wick',
    'email' => 'johnwick@gunfu.com',
    'url' => 'http://gunfu.com'
];

$form->hidden($data);

Produces the following HTML

<input type="hidden" name="name" id="name" value="John Wick">
<input type="hidden" name="email" id="email" value="johnwick@gunfu.com">
<input type="hidden" name="url" id="url" value="http://gunfu.com">

honeypot

Adds a hidden "honeypot" field to the form, which is useful in preventing bots from hijacking the form by killing the script if the field was filled.

Example

$form->honeypot('foo');

Produces the following HTML

<input type="text" name="foo" value="" style="display:none">

month

Identical to text() except that it creates an <input type="month"> element.

number

Identical to text() except that it creates an <input type="number"> element.

password

Identical to text() except that it creates an <input type="password"> element.

range

Identical to text() except that it creates an <input type="range"> element.

search

Identical to text() except that it creates an <input type="search"> element.

tel

Identical to text() except that it creates an <input type="tel"> element.

textarea

Identical to text() except that it creates a <textarea> element.

time

Identical to text() except that it creates an <input type="time"> element.

url

Identical to text() except that it creates an <input type="url"> element.

value

Prints the field's value after the form has been submitted. Use when building forms in HTML.

Example

<input type="text" name="address" value="<?php $form->value('address') ?>">

week

Identical to text() except that it creates an <input type="week"> element.

---

Checkboxes & Radios

checkbox

Creates an <input type="checkbox"> element.

1. The required first parameter contains the field's name.
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 CSS, JavaScript, etc.
6. The optional sixth parameter utilizes Bootstrap's .form-text block-level text.
7. The optional seventh parameter tells Formr if the checkbox should be ticked.

Example: create a standard checkbox

$form->checkbox('agree','I Agree','agree','agreeID');

Produces the following HTML

<label for="agree">
    <input type="checkbox" name="agree" id="agreeID" value="agree">I Agree
</label>

Tick a checkbox on page load

$form->checkbox('agree','I Agree','agree','agree','','','checked');

Produces the following HTML

<label for="agree">
    <input checked="checked" type="checkbox" name="agree" id="agree" value="agree">I Agree
</label>

Warning

Notice how in the seventh parameter we used the string checked instead of the boolean TRUE? This is because anything in that parameter will return TRUE, even if it's an incorrect value. Therefore we must either enter the string checked, the string selected, or the actual checkbox value (example below) to tell Formr we want this element checked on form load.

Tick a checkbox using a variable

$favorite_fruit = 'bananas';
$form->checkbox('bananas','Bananas','bananas','','','',$favorite_fruit);

Produces the following HTML

<input checked="checked" type="checkbox" name="bananas" id="bananas" value="bananas">
<label class="form-check-label" for="bananas"> Bananas</label>

checkbox_inline

Identical to checkbox(), plus adds the appropriate Bootstrap CSS classes to the <label> and enclosing <div>.

radio

Identical to checkbox() except that it creates an <input type="radio"> element.

radio_inline

Identical to radio(), plus adds the appropriate Bootstrap CSS classes to the <label> and enclosing <div>.

---

Select Menus

select

Creates a standard <select> element.

1. The required first parameter contains the field's name.
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 CSS, JavaScript, etc.
6. The optional sixth parameter utilizes Bootstrap's .form-text block-level text.
7. The optional seventh parameter contains a default value.
8. The required eighth parameter contains an array of options to populate the menu.

Using an array to create a select menu

$options = [
    'cat' => 'The Cat in the Hat',
    'lorax' => 'The Lorax',
    'yertle' => 'Yertle the Turtle',
    'grinch' => 'The Grinch Who Stole Christmas',
];

// notice that we added a 'selected' value in the 7th parameter
$form->select('books','Books','','','','','yertle',$options);

Produces the following HTML

<label for="books">Books</label> 
<select name="books" id="books">
    <option value="cat">The Cat in the Hat</option>
    <option value="lorax">The Lorax</option>
    <option value="yertle" selected>Yertle the Turtle</option>
    <option value="grinch">The Grinch Who Stole Christmas</option>
</select>

Instead of selecting a value from our $options array we can insert a string, and if a match isn't available in the $options array then an empty <option> tag will be created instead.

Adding a default option on the fly

$form->select('books','Books','','','','','Select a Book...',$options);

Produces the following HTML

<label for="books">Books</label> 
<select name="books" id="books">
    <option value="">Select a Book...</option>
    <option value="cat">The Cat in the Hat</option>
    <option value="lorax">The Lorax</option>
    <option value="yertle">Yertle the Turtle</option>
    <option value="grinch">The Grinch Who Stole Christmas</option>
</select>

Tip

You may also pass an array of default values through the 7th parameter and Formr will create a <select multiple> element.

Selecting multiple options

$options = [
    'cat' => 'The Cat in the Hat',
    'lorax' => 'The Lorax',
    'yertle' => 'Yertle the Turtle',
    'grinch' => 'The Grinch Who Stole Christmas',
];

$selected = ['cat','yertle'];

$form->select('books','Books','','','','',$selected,$options);

Produces the following HTML

<label for="books">Books</label> 
<select name="books" multiple id="books">
    <option value="cat" selected>The Cat in the Hat</option>
    <option value="lorax">The Lorax</option>
    <option value="yertle" selected>Yertle the Turtle</option>
    <option value="grinch">The Grinch Who Stole Christmas</option>
</select>

It's also possible to create the select menu and all of the options using an associative array.

Creating a select menu from an associative array

$data = [
    'name' => 'books',
    'id' => 'books',
    'label' => 'Books',
    'options' => [
        'cat' => 'The Cat in the Hat',
        'lorax' => 'The Lorax',
        'yertle' => 'Yertle the Turtle',
        'grinch' => 'The Grinch Who Stole Christmas',
    ],
    'selected' => 'lorax',
    'value' => ''
];

$form->select($data);

Produces the following HTML

<label for="books">Books</label> 
<select name="books" id="books" class="input">
    <option value="cat">The Cat in the Hat</option>
    <option value="lorax" selected>The Lorax</option>
    <option value="yertle">Yertle the Turtle</option>
    <option value="grinch">The Grinch Who Stole Christmas</option>
</select>

Building selects with strings

The select() method also has a little trick up its sleeve: if you pass a string as the 8th parameter, Formr will look for a method with the same name inside the lib/class.formr.dropdowns.php or my_classes/my.dropdowns.php files.

For instance, if you enter the string states in the 8th parameter, Formr will automatically produce a menu containing all 50 US states. This is basically a plugin system, which will not only allow you to tap into all of Formr's built-in menus, but will also allow you to create and save your own.

Check out the Formr Extend repo for more information on creating your own dropdown menus.

Example

$form->select('state','State:','','','','','','states');

Produces the following HTML

<label for="state">State:</label> 
<select name="state" id="state" >
    <option value="" selected="selected">Select a State...</option>
    <option value="AL">Alabama</option>
    <option value="AK">Alaska</option>
    ...
    <option value="WI">Wisconsin</option>
    <option value="WY">Wyoming</option>
</select>

Following is a list of Formr's built-in menus

Menu Name	Description
states	Displays all 50 U.S. States
countries	Displays all World Countries
provinces	Displays all Canadian Provinces
states_provinces	Displays all U.S. States and Canadian Provinces
age	Displays ages in groups, 18-24, 25-29, etc.
height	Displays a list of heights in feet and inches
years_old	Makes sure a person is of a certain age. Default is 18 years old
days	Displays numbers starting from 1 - 31. Good for registration forms
months	Display months of the year, with the month name being the key and the value
years	Displays every year starting from 1930. Good for registration forms
months_alpha	Displays months of the year with a numeric key
cc_months	Displays months of the year, with the key being an integer. Good for credit card forms
cc_years	Displays the current year up to 2025. Good for credit card forms

select_multiple

Identical to select(), plus adds the multiple attribute to create a multiple select list.

Warning

Don't forget to add square brackets to your field name, or PHP will only allow one selection at a time.

$form->select_multiple('name[]')

dropdown

Alias of select()

dropdown_multiple

Alias of select_multiple()

---

File Uploads

file

Creates an <input type="file"> element.

1. The required first parameter contains the field's name.
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 CSS, JavaScript, etc.
6. The optional sixth parameter utilizes Bootstrap's .form-text block-level text.

Example

$form->file('image');

Produces the following HTML

<input type="file" name="image">

file_multiple

Identical to file() except that it adds the multiple attribute, which allows the user to select multiple files with only one input.

Example

$form->file_multiple('images[]');

Produces the following HTML

<input type="file" name="images[]" multiple>

Warning

Because we're uploading multiple files we have to prepend our field name with square brackets [] to create an array.

upload

Alias of file().

upload_multiple

Alias of file_multiple().

---

Buttons

button

Creates a standard <button type="button"> element.

1. The optional first parameter contains the button name.
2. The optional second parameter contains label text.
3. The optional third parameter contains the button's value.
4. The optional fourth parameter contains the button's ID.
5. The optional fifth parameter contains a string, which lets you add CSS, JavaScript, etc.

Example

$form->button();

Produces the following HTML

<button type="button" name="button" id="button" class="button">Submit</button>

Changing the button text

$form->button('button','','Press Me');

Produces the following HTML

<button type="button" name="button" id="button" class="button">Press Me</button>

input_submit

Identical to button() except it creates an <input type="submit"> element.

Example

$form->input_submit();

Produces the following HTML

<input type="submit" name="submit" value="Submit" id="submit" class="button">

submit_button

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

The only parameter contains the button's value text and is optional.

Example

$form->submit_button();

Produces the following HTML

<button type="submit" name="submit" id="submit" class="button">
    Submit
</button>

Change the button value

$form->submit_button('Submit Form');

Produces the following HTML

<button type="submit" name="submit" id="submit" class="button">
    Submit Form
</button>

reset_button

Creates a standard <button type="reset"> element.

The only parameter contains the button's value text and is optional.

Example

$form->reset_button();

Produces the following HTML

<button type="reset" name="reset" id="reset" class="button">
    Reset
</button>

---

Messaging

messages

Use this method to print your form's messages. If using Bootstrap as your wrapper, error messages will be formatted automatically using the proper alert CSS classes.

1. The optional first parameter contains your field wrapper's open tag.
2. The optional second parameter contains your field wrapper's close tag.

Example

$form->messages();

Wrap messages in a custom div

$form->messages('<div class="error">','</div>');

Info

messages() will not print anything to the screen if Formr's $errors array is empty, so there's really no reason why you shouldn't have it in your scripts, as it also prints out error messages if you forgot to add a property or configured something incorrectly.

error_message

Add your own custom error messages throughout your application. Uses the Bootstrap or Bulma error classes, which can be changed via the $controls property or by creating your own wrapper class.

Visit the Extend Repo for more info on creating your own wrappers.

Example

$form->error_message('This is bad, and you should feel bad!');

info_message

Identical to error_message() except adds an info CSS class.

success_message

Identical to error_message() except adds a success CSS class.

Print a success message after the form has been submitted

if ($form->submitted()) {
    if ($form->ok()) {
        $form->success_message('Thank you for submitting our form!');
    }
}

warning_message

Identical to error_message() except adds a warning CSS class.

---

Error Handling

errors

Use this method to see if Formr's $errors array is empty.

Example

if ($form->errors()) {
    echo 'there were form errors';
} else {
    echo 'no errors!';
}

add_to_errors

Manually add a field's name to the $errors array and it will be printed via the messages() method.

Example

$form->add_to_errors('zip');

You can add a custom message by separating your field name and message with a pipe character.

Adding a custom error message

$form->add_to_errors('zip|Please enter your zip code');

in_errors

Check if a field is in the $errors array.

Check if email is in the $errors array

if ($form->in_errors('email')) {
    // email is in the $errors array
}

in_errors_if

Returns a string if the given form field is in the $errorsarray.

Example

$form->in_errors_if('name','Please enter your name');

in_errors_else

If the given field is in the $errors array return a string, else return another string.

Example

$form->in_errors_else('name','Please enter your name','You entered your name!');

---

Labels

label

Creates a standard <label> tag.

1. The required first parameter contains the field name for which this label is being created.
2. The required second parameter contains the label text and is required.
3. The optional third parameter contains an ID attribute.
4. The optional fourth parameter contains a string, which lets you add CSS, JavaScript, etc.

Example

$form->label('name','Your name:');

Produces the following HTML

<label for="name">Your name:</label> 

Add a CSS class to the label

$form->label('name','Your name:','','class="label"');

Produces the following HTML

<label for="name" class="label">Your name:</label>

label_open

Identical to the label() method, except that it does not add a close </label> tag.

label_close

Creates a standard </label> tag.

The only parameter to label_close() contains the label text. This is handy if you want to wrap a label around a checkbox or radio button and want the text to be after the element, rather than before.

Example

$form->label_close('Derby');

Produces the following HTML

Derby</label>

Full label example

$form->label_open('bowler');
$form->input_checkbox('bowler','','bowler');
$form->label_close('Bowler');

Produces the following HTML

<label for="bowler">
    <input type="checkbox" name="bowler" id="bowler" value="bowler">Bowler
</label>

---

Fieldsets

fieldset_open

Creates a standard <fieldset> tag.

1. The optional first parameter contains the legend text.
2. The optional second parameter contains a string, which lets you add CSS, JavaScript, etc.

Example

$form->fieldset_open('Contact information');

Produces the following HTML

<fieldset>
<legend>Contact information</legend>

fieldset_close

Creates a standard </fieldset> tag.

The only parameter accepts a string and is optional.

Example

$form->fieldset_close();

Produces the following HTML

</fieldset>

---

Email

send_email

Sends a very basic HTML or plain-text email using PHP's mail() function. Optionally loops though the contents of the $_POST array and prints the key/value pair in the email.

1. The required first parameter is the recipient's email address.
2. The required second parameter is the email subject.
3. The required third parameter contains the message body.
4. The optional fourth parameter accepts a 'from' email address.
5. The optional fifth parameter is binary: set to TRUE if you'd like to send the email as HTML.
6. The optional sixth parameter lets you pass custom mail headers as a string.

Send a plain-text email

$to = 'recipient@email.com';
$subject = 'Ahoy, Matey!';
$message = 'Welcome to our website!...';

$form->send_email($to, $subject, $message);

Send an HTML Email with a Return Address

$to = 'recipient@email.com';
$from = 'me@domain.com';
$subject = 'Ahoy, Matey!';
$message = 'Welcome to our website!...';

$form->send_email($to, $subject, $message, $from, TRUE);

Send the $_POST array as HTML

$to = 'recipient@email.com';
$from = 'me@domain.com';
$subject = 'Ahoy, Matey!';

$form->send_email($to, $subject, 'POST', $from, TRUE);

Produces something like

your_name: John Wick
your_email: johnwick@gunfu.com

Pass custom Headers

$headers  = "MIME-Version: 1.0\r\n";
$headers .= "Content-Type: text/html; charset=ISO-8859-1\r\n";
$headers .= "From: " . $from . "\r\n";

$form->send_email($to, $subject, $message, $from, 'HTML', $headers);

If you want prettier emails while looping through the $_POST array, name your input fields with capital letters and underscores, and then prepend each name with an underscore. Prepending a field with an underscore tells Formr to replace all underscores with spaces, making for an easier to read email.

Example

$form->input_text('_First_Name','First Name');
$form->input_text('_Last_Name','Last Name');

And the email will look like something like this

First Name: John
Last Name: Wick

---

Debugging

printr

Incredibly handy! Formr's shortcut for PHP's print_r() function, which automatically formats and prints the contents of an array; or just pass a string for easy debugging.

Example

$form->printr($_POST);
$form->printr($_GET);
$form->printr($data);

// pass a string for breakpoints...
$form->printr('Here');

$form->printr('POST');  // lazy alias...
$form->printr('GET');   // lazy alias...

dump

Alias of printr().

dd

Same as printr() but adds die to kill the script after printing.

info

Prints out the settings of your form. Try it!

Example

$form->info();

---

reCAPTCHA v3

recaptcha_body

Prints the necessary JavaScript for client-side token retrieval. Put this before the closing </body> of your document.

recaptcha_head

Prints the <script> attribute which links to an external Google reCaptcha script (api.js) for client-side validation. Put this in the <head> section of your document.

recaptcha_passed

Boolean. Checks if the reCAPTCHA passed validation.

Example

if($form->recaptcha_passed()) {
    // the reCAPTCHA passed
}

if(! $form->recaptcha_passed()) {
    // the reCAPTCHA failed
}

Misc.

clear

Empties the $_POST super global after a form submission. Handy if you want to show an empty form after a successful submission.

Example

if($form->submitted())
{
    $name = $form->post('name');
    $email = $form->post('email');

    if($form->ok()) {
        $form->clear();
    }
}

csrf

Adds CSRF protection to your form by creating a hidden field and filling it with a random token, which is validated upon form submission. If the token fails validation an error message will be shown to the user.

The only parameter changes the expiration time, in seconds, and is optional. Default expiration value is 3600 seconds (1 hour).

Example

$form->open();
$form->csrf(5600);

Produces something like

<input type="hidden" name="csrf_token" value="6d956b86e3bxoe29d7df1f492df85654fed6ee52591c9cd1bf854d6079e7fd3c|cleo93jclk3k8">

Warning

csrf needs a SESSION to work, so you must add session_start() at the top of your script or you will receive an error.

ok

Easy way to check if there are no errors with the submitted form.

Send an email if the form was submitted successfully

if($form->submitted()) {
    if($form->ok()) {
        $form->success_message = 'We have received your submission|Thank You!';
    }
}

slug

Only allows letters, numbers and underscores in a string. If any character other than a letter, number, or underscore is encountered it will be converted to an underscore.

Example

$username = $form->slug('P Sherman 42');

Produces the following slugged text

P_Sherman_42

unset_session

Performs a session_unset()on the $form->session property upon refresh or submit. Will output a message to the browser letting you know it has been unset.

Example

$form->session = 'myForm';
$form->session_unset();

heading

This method is useful if you have a form that is more along the lines of a test, or questionnaire and you want to really call out the field when there's an error in the form. Basically, you enter the field name in the first parameter and the string in the second, and if there's an error the string will be enclosed in tags.

Example

<h3>
    <?php echo $form->heading('question1','How many inches in a foot?'); ?>
</h3>

// will produce upon page load
<h3>How many inches in a foot?</h3>

// will produce upon form error
<h3><span class="error">How many inches in a foot?</span></h3>