Skip to content

Properties

This document contains a list of Formr's public properties.

action

The form's action. Formr will automatically insert the current script's filename into the <form> tag unless you set this property to something else. Typically used with fastform().

Set the form's action to login.php

$form->action = 'login.php';
$form->fastform('login');
Produces the following HTML 
<form action="login.php" method="post" accept-charset="utf-8">
    ...
</form>

charset

Formr's default character set is UTF-8, however, you can easily change this to something else, such as Latin-1.

Set the form's charset to Latin-1

$form->charset = 'Latin-1';

controls

An array containing all of the CSS classes used in Formr, which you can easily set when instantiating a new form. You can also create your own wrappers and save them in your own wrapper class.

Change the default text error class

$form->controls['text-error'] = 'my-error-class';

custom_validation_messages

Works in conjunction with the post() method and tells Formr to suppress the default validation messages and only show your own custom message.

The following example will only display the error message: "Please enter your email" upon validation error of the email field.

Only show custom error messages

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

error_heading_plural

When a form error occurs the messages method will add singular - or plural - default header text wrapped in an <h4> tag. This parameter allows you to change the default message string for when there is more than one error in the form.

Example

$form->error_heading_plural = 'Correct the Errors';

error_heading_singular

Same as error_heading_plural except that it will be shown if there is only one error in the form.

format_rule_dates

Allows you to choose how you want to format your dates when using the before and after validation rules. Default is 'M d, Y',

Example

$form->format_rule_dates = 'Y-m-d';

html_purifier

Formr will clean any text passed through the validate(), fastpost(), post() and get() methods using a combination of strip_tags() and FILTER_SANITIZE_SPECIAL_CHARS.

However, if you want to go deeper, you can easily use HTML Purifier. Just set the full path to your HTML Purifier script and Formr will do the rest.

Set the path to HTML Purifier

$form->html_purifier = '/home/mysite/htdocs/lib/HTMLPurifier.standalone.php';

id

Sets the ID of the form. You most likely will not need this as you can set the ID when creating the form, but it's here if you do.

Set the form's ID

$form->id = 'MyForm';

info_message

Use this property to pass a formatted info message through the messages() method.

Adding an info message

$form->info_message = 'This is an information message';
Produces the following HTML 
<div class="alert-info" role="alert">
    This is an information message
</div>

You can also pass a heading to your message by adding a pipe character between the message and heading.

Adding an info message with a heading

$form->info_message = 'This is an information message|Did You Know?';
Produces the following HTML 
<div class="alert-info" role="alert">
    <h4>Did You Know?</h4>
    This is an information message
</div>

inline_errors

Boolean. Default is FALSE. Turns off textual error messages at the top of the form and will instead display error messages below each field element.

Add an image to the right of the form field

If you use the following CSS, Formr will insert a small PNG of your choice (not included) to the right of the form field.

.inline-error {
    float: left;
    width: 24px;
    height: 24px;
    background: url('../img/invalid.png') no-repeat 4px 4px;
}

inline_errors_class

Sets the CSS class name if you're using inline error reporting. Default class is named inline-error.

inline_errors_class example

$form->inline_errors_class = 'my-inline-error-class';

Boolean. This property inserts an anchor link in the error message that then links to its corresponding form field in the form, handy if you have very long forms and there's a lot of scrolling. Note: the form field's name and ID attributes must be the same for this to work.

Enable linking to errors

$form->link_errors = true;

method

The form's method. Formr will automatically insert <form method="post"> into the <form> tag unless you set this property to something else. Typically used with fastform().

Set the form's method to GET

$form->method = 'GET';
$form->open();
Produces the following HTML 
<form action="/index.php" method="GET" accept-charset="utf-8">

minify

Boolean. Setting this to TRUE will remove all formatting and minify your output.

Example

$form->minify = true;

name

Sets the name of the form. You probably won't need this but it's here if you do.

Setting the form's name to "cheese"

$form->name = 'cheese';
Produces the following HTML 
<form action="foo.php" name="cheese" method="post" accept-charset="utf-8">

recaptcha_action_name

Helps you differentiate forms via actions in Google's reCAPTCHA Admin panel.

recaptcha_score

The default score for Google's reCAPTCHA is 0.5. Use this property to change that value.

recaptcha_secret_key

Your Google reCAPTCHA secret key, which can be obtained here.

recaptcha_site_key

Your Google reCAPTCHA site key, which can be obtained here.

recaptcha_use_curl

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

required

Formr enables you to easily make one field required, all fields required, or all but one field required. The $form->required property is global, which means that you don't have to mark each and every form field, form label and POST validation rule to "required"… instead, you supply the required field names to this property and Formr will handle everything for you automatically!

You can also omit fields from being required, which can be a huge time saver because using omitted fields will automatically make all other fields in the form required!

  1. To make a field required, just add it to the $form->required property.
  2. To make all fields required, instead of adding all field names, just add an asterisk (*).
  3. To omit fields, just wrap the omitted field name in parenthesis ().

Make fname, lname, and email Required

$form->required = 'fname,lname,email';

Make all Form Fields Required

$form->required = '*';

Make All Form Fields Required Except for fname

$form->required = '(fname)';

Require All Form Fields Except lname and country

$form->required = '(lname),(country)';

required_indicator

Inserts a visual representation inside the <label> tag to let the user know the field is required. You can set this to whatever you like during instantiation, or leave it at the default (empty) value.

Example

$form->required = 'username';
$form->required_indicator = '*';
$form->text('username','Username');
Produces the following HTML 
<label for="username">Username*</label> 
<input type="text" name="username" id="username" required>

sanitize_html

Will pass any $_POST values through PHP's FILTER_SANITIZE_SPECIAL_CHARS filter. Disabled by default.

Example

$form->sanitize_html = true;

salt

Add a custom salt when hashing passwords.

Example

$form->salt = '12wSkie93lekLCldkx,39cjwlg0374hflwshrp';

session

Automatically puts all submitted form values into a $_SESSION array. Handy for multi-page forms or if a user submits a form and then refreshes the page.

Example

$form->session = 'myForm';

Example

<?php
session_start();

// give our session a name
$form->session = 'myForm';

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

    $form->printr($_SESSION);
}
Produces somerthing like the following 
Array
(
    [myForm] => Array
        (
            [fname] => John
            [lname] => Wick
            [email] => johnwick@gunfu.com
        )
)

Danger

You must add session_start() to the top of your script, then pass the $_POST values through the fastpost(), post() or validate() methods or the $_SESSIONdata will not be set.

Warning

If you want your form fields to be populated with the $_SESSION data, you must use the session_values property, as outlined below.

session_values

Boolean. Will automatically populate all form fields with that field's corresponding value in the $_SESSION.

Use the $_SESSION values for all form fields

$form->session_values = true;

Prevent the automatic use of the $_SESSIONvalue by entering a value in the value parameter.

Preventing the $_SESSION value for a field

$form->input_text('lname', 'Last name', $lname)

Manually adding the $_SESSION value for a field

$form->input_text('lname', 'Last name', $_SESSION[$form->session]['lname'])

show_valid

Enabling this property will apply the valid Bootstrap or Bulma CSS classes to your fields upon form submission.

Example

$form->show_valid = true;

Produces something like the following... 

<div id="_name" class="form-group">
    <label class="control-label" for="name">Name</label>
    <input type="text" name="name" id="name" class="form-control is-valid">
</div>

submit

The submit button's value as a string. If you don't set this Formr will automatically insert value="Submit" into the submit button. You'll probably never use this, but it's here if you need it.

Example

$form->submit = 'Submit Me, Jerk!';
$form->input_submit();
Produces the following HTML 
<input type="submit" name="submit" value="Submit Me, Jerk!" id="submit">

success_message

Identical to $info_message except the enclosing <div> is formatted as a success message.

warning_message

Identical to $info_message except the enclosing <div> is formatted as a warning message.

upload_dir

Specifies the full path to your upload directory.

Example

$form->upload_dir = '/htdocs/uploads/';

upload_accepted_types

Lets you specify the types of files you will allow for upload to your server. Enter each file extension separated by a comma.

Specifying the Accepted Upload File Types

$form->upload_accepted_types = 'jpg,jpeg,gif,png';
You can also just enter the string images and Formr will automatically allow JPG, GIF, and PNG files. 
$form->upload_accepted_types = 'images';

upload_accepted_mimes

Same as upload_accepted_types but more secure. Instead of checking the file's extension it checks the file's mime type.

Specifying the Accepted Upload MIME Types

$form->upload_accepted_mimes = 'image/jpg,image/jpeg,image/gif,image/png';
You can also just enter the string images and Formr will automatically allow JPG, GIF, and PNG files. 
$form->upload_accepted_mimes = 'images';

upload_max_filesize

Maximum allowed size of the uploaded file, measured in bytes. Default is 2MB.

Example

$form->upload_max_filesize = 3145728; // 3145728 bytes = 3MB

upload_rename

Lets you rename the file after its been uploaded.

Rename the file with a 32 character random hash

$form->upload_rename = 'hash';

Will produce something like 

ZVHGgmvNGV30b2YwZ3Hx4T0xH2dNlWm4.jpg

Rename the file with a 12 character hash

$form->upload_rename = 'hash[12]';

Will produce something like 

3Hx4T0YwZ3Hx.jpg

Rename the file with a UNIX timestamp

$form->upload_rename = 'timestamp';

Will produce something like 

1374967622.jpg

Prepend a string onto the original filename

$form->upload_rename = 'prepend[my-file-]';

Will produce something like 

my-file-our_day_at_the_beach.jpg

Rename the file with a string

$form->upload_rename = 'string[myFilename]';

Will produce 

myFilename.jpg

upload_resize

Allows you to resize your uploaded images.

  1. The required first parameter contains the max width of the resized image.
  2. The required second parameter contains the max height of the resized image.
  3. The optional third parameter adds a string to the beginning of the file name.
  4. The optional fourth parameter specifies the upload directory if one hasn't been specified in upload_dir.
  5. The optional fifth parameter contains the quality of the resized image. Default is 80%. JPG only.

Resize the uploaded file to 150px x 150px

$form->upload_resize = array('resize' => '150,150');

The $upload_resize property will also accept an array as its value. The array key is the name of the process and can be anything you like, such as: "thumbnail", "avatar", "large_image", etc.

The array values are a simple string, and tell Formr what to do with the image. Each array key/value pair will perform a resize process on the uploaded image, so if you want to resize it 10 times, just add 10 key/value pairs.

Let's resize the uploaded image 3 times, for a total of 4 images; the original upload, and our three resized images.

  1. The first key will create an image with a max width and height of 600 pixels and be saved into the large directory.
  2. The second key will create an image with a max width and height of 100 pixels, will have the filename prepended with tn_, be saved into the thumbnail directory and have a JPG quality of 90%.
  3. The third key will create an image with a max width and height of 64 pixels and be saved put it into the avatars directory.

Resize images with an array

$resize = [
    'large' => '600,600,,/www/formr/uploads/large/',
    'thumbnail' => '100,100,tn_,/www/formr/uploads/thumbnails/,90',
    'avatar' => '64,64,,/www/formr/uploads/avatars/'
];

$form->upload_resize = $resize;

uploads

Set this to FALSE if you're using a third-party upload script to upload your files.

Example

$form->uploads = false;