Validation

This document contains examples of Formr's form validation methods and rules.

Retrieving Form Input

validate

The easiest, and most basic way to validate a form. Simply add a comma separated list of your form's labels and Formr will grab all of the form data, perform basic sanitization on it, validate it according to your rules, and put the values into an array.

The only parameter accepts a comma delimited string of form labels and their associated validation rules, wrapped in parentheses, and is required.

Retrieve the form's values

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

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

Warning

Notice how our label is named Email Address and our form field is named email_address? This is because Formr will take any spaces in the labels and convert them to an underscore.

In order to perform validation, just add your rules in parentheses after the label. If a label contains the word email, a valid_email validation rule will automatically be applied.

Validate the form's values

$data = $form->validate('Name(min[2]|max[32]), Email Address, Comments, Age(greater_than[17])');

Tip

You can add as many validation rules as you like by separating each rule with a pipe | character.

fastpost

This method works in conjunction with fastform() and is covered in detail on the FastForm Examples page.

post

This method processes and validates form input based upon a series of chained rules, and allows for the most control over your validation.

The required first parameter contains the field name.
The optional second parameter contains human readable text for messages.
The optional third parameter contains the validation rules.

Info

The second parameter will be used for error messages if that field fails validation. It can optionally contain a custom error message string that will be shown if the field is required, yet left empty when submitted.

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 allow_html as a validation rule and only trim() will be applied to the input.

Process form input and assign to variables

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

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

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

Make sure 'password_conf' matches 'password'

$password_conf = $form->post('password_conf','Password Confirm','matches[password]');

You can assign a human readable version of the field name in the second parameter for better error messages.

Make sure we get a valid email address

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

You can create custom error message by adding a pipe character after the name of the form field.

Create a custom error message string

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

reCAPTCHA

Formr supports Google reCAPTCHA v3, in which no user input is required. Instead Google calculates a score, and if the validation score falls below a certain value (default is 0.5) the validation fails and the form stops processing.

Setting up reCAPTCHA is really easy. First thing you need to do is head over to the reCAPTCHA v3 page and request your keys.

Warning

Make sure you select the reCAPTCHA v3 for the reCAPTCHA type!

Next, add those keys to Formr using the recaptcha_secret_key and recaptcha_site_key properties. You can also change the default score value with the recaptcha_score property.

After that add the $form->recaptcha_head() method to the <head> section of your document, and the $form->recaptcha_body() method right before the closing </body> tag (or anywhere you want to place your JavaScript).

Finally, check if the reCAPTCHA validation passed, or failed, using the recaptcha_passed() method after the form has been submitted.

Adding reCAPTCHA

<!DOCTYPE html>
<?php
    require 'Formr/class.formr.php';
    $form = new Formr\Formr();
    $form->recaptcha_site_key = 'YOUR-SITE-KEY';
    $form->recaptcha_secret_key = 'YOUR-SECRET-KEY';

    if ($form->submitted())
    {
        if (! $form->recaptcha_passed()) {
            $form->error_message('reCAPTCHA Failed');
        }
    }
?>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Formr reCAPTCHA v3</title>
    <?= $form->recaptcha_head() ?>
</head>
<body>
    <?php
       $form->messages();

       // build your form
       $form->create_form('Name,Email,Comments|textarea');

       // add the reCAPTCHA JavaScript
       $form->recaptcha_body();
    ?>
</body>
</html>

Use cURL for Validation

By default, Formr will use file_get_contents() for verification with Google's servers. You can use cURL instead by setting the recaptcha_use_curl property to TRUE.

$form->recaptcha_use_curl = true;

Validation Rules

The following table contains all validation rules.

Rule/Alias	Parameter?	Description	Example
after	No	Checks if the given date is after the current date using server time. The form input field must be formatted as `YYYY-MM-DD`.
allow_html, html	No	Allows HTML, script tags, etc. Nullifies all other string rules. Use with caution!
alpha	No	Returns `FALSE` if the given string contains anything other than alphabetical characters.
alpha_dash, ad	No	Returns `FALSE` if the given string contains anything other than alpha-numeric characters, underscores or dashes.
alpha_numeric, an	No	Returns `FALSE` if the given string contains anything other than alpha-numeric characters.
before	No	Checks if the given date is before the current date using server time. The form input field must be formatted as `YYYY-MM-DD`.
exact_length, exact, el	Yes	Returns `FALSE` if the given string is not exactly the parameter value.	`exact[8]`
greater_than, gt	Yes	Returns `FALSE` if the given string is less than the parameter value, or is not numeric.	`gt[8]`
greater_than_or_equal, gte	Yes	Returns `FALSE` if the given string is less than or equal to the parameter value, or is not numeric.	`gte[8]`
hash	No	Returns an encrypted string using the `password_hash` function.
integer, int	No	Returns `FALSE` if the given string contains anything other than an integer.
less_than, lt	Yes	Returns `FALSE` if the given string is greater than the parameter value or not numeric.	`lt[8]`
less_than_or_equal, lte	Yes	Returns `FALSE` if the given string is greater than or equal to the parameter value, or is not numeric.	`lte[8]`
matches	Yes	Returns `FALSE` if the given string does not match the one in the parameter.	`matches[field_name]`
max_length, max, ml	Yes	Returns `FALSE` if the given string is longer than the parameter value.	`max[12]`
min_length, min	Yes	Returns `FALSE` if the given string is shorter than the parameter value.	`min[6]`
md5	No	Returns an `md5` encrypted string.
not_regex	Yes	Does not match a user-defined regex.	`not_regex[/^\d+$/]`
numeric	No	Returns `FALSE` if the given string contains anything other than numeric characters.
regex	Yes	Matches a user-defined regex.	`regex[/[^0-9]/]`
required	No	Returns `FALSE` if the field is empty.
sha1	No	Returns an `sha1` encrypted string.
sanitize_email	No	Passes result through the `FILTER_SANITIZE_EMAIL` function.
sanitize_int	No	Passes result through the `FILTER_SANITIZE_NUMBER_INT` function.
sanitize_string	No	Passes result through the `strip_tags()` function.
sanitize_url	No	Passes result through the `FILTER_SANITIZE_URL` function.
slug	No	Creates a Twitter-style username string containing only letters, numbers and underscores.
strip_numeric	No	Strips out everything but numbers.
valid_email, email	No	Returns `FALSE` if the supplied string does not contain a valid email address.
valid_ip, ip	No	Returns `FALSE` if the supplied string is not a valid IP address.
valid_url, url	No	Returns `FALSE` if the supplied string is not formatted as a URL.