PHP Form Class Complete documentation with code examples
The PHP Form class is the core of the system. Instantiate your forms by creating an object with $form = new Form();. Then add your fields and render the HTML code with the help of the functions detailed in this document.
Overview
To build and display your form, you have to include four PHP code blocks:
The first block at the very beginning of your page to include the autoloader and build the form.
The second block in your <head></head> section to call required css files for plugins.
The third block in <body></body> section to render your form.
The fourth block just before </body> to call required js files and js code to activate plugins.
Here is an example of a page containing a form:
<?php
/*============================================
= 1st block - the form =
============================================*/
use phpformbuilder\Form;
use phpformbuilder\Validator\Validator;
// Start the PHP session
session_start();
// Include the main Form class
include_once rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . '/phpformbuilder/autoload.php';
// Create the form
$form = new Form('test-form', 'horizontal', 'novalidate');
// Call functions to add fields and elements
$form->addInput('text', 'user-name', '', 'Name :', 'required, placeholder=Name');
$form->addRadio('is-all-ok', 'Yes', 1);
$form->addRadio('is-all-ok', 'No', 0);
$form->printRadioGroup('is-all-ok', 'Is all ok ?', false, 'required');
$form->addBtn('submit', 'submit-btn', 1, 'Send', 'class=btn btn-success');
// iCheck plugin
$form->addPlugin('icheck', 'input', 'default', array('%theme%' => 'square', '%color%' => 'red'));
/*=========== End of 1st block ============*/
?>
<!DOCTYPE html>
<html>
<head>
<title>Test Form</title>
<!-- Bootstrap 5 CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
<?php
/*============================================================
= 2nd block - css includes for plugins =
============================================================*/
$form->printIncludes('css');
/*=================== End of 2nd block ====================*/
?>
</head>
<body>
<h1>My first form</h1>
<?php
/*======================================================================================================
= 3rd block - render the form and the feedback message if the form has been sent =
======================================================================================================*/
if (isset($sentMessage)) {
echo $sentMessage;
}
$form->render();
/*======================================== End of 3rd block =========================================*/
?>
<!-- Bootstrap 5 JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p" crossorigin="anonymous"></script>
<?php
/*========================================================================
= 4th block - js includes for plugins and js code (domready) =
========================================================================*/
$form->printIncludes('js');
$form->printJsCode();
/*========================= End of 4th block ===========================*/
?>
</body>
</html>
Frameworks
All options are ready to use and will generate HTML markup according to the chosen framework.
$form = new Form('my-form', 'horizontal', 'novalidate', 'tailwind');
UIKit
$form = new Form('my-form', 'horizontal', 'novalidate', 'uikit');
No framework
Add the minimal Bootstrap 5 CSS to your page head, then you can build your forms with Bootstrap 5.
This style sheet only includes what is necessary to layout your responsive forms and will not break anything in the other parts of your pages.
<head>
// link to the minimal Bootstrap 5 CSS
<link rel="stylesheet" href="/phpformbuilder/templates/assets/bootstrap5-phpfb/css/bootstrap5-phpfb.min.css">
</head>
<?php
// Then you can build your form
$form = new Form('my-form', 'horizontal', 'novalidate');
Without PHP Form Builder, your page loads the plugin dependencies (CSS and JavaScript files) one by one. For instance, if your form uses five plugins, you will need to call at least ten files (5 CSS + 5 JavaScript), which considerably increases the loading time.
PHP Form Builder groups and compresses all the CSS and JavaScript dependencies into a single CSS | JavaScript file.
Your page will, therefore, only call two dependency files. Efficiency is maximum, no matter how many plugins you use.
JavaScript dependencies can also be loaded with the excellent loadjs library.
The PHP Form Builder options define the containers and various HTML elements your forms will use.
The Default options are for use with Bootstrap 5.
Each can be overwritten the way you want to match other framework
You can call the getOptions(mixed $opt) function at any time to display the options and their values for debugging purposes. The $opt argument can be an option name, or an array of options names, or null if you want to show all the options keys => values.
For example, with Bootstrap, each group (label + element) has to be wrapped into a <div class="form-group"></div> and to have a .form-control class
We also need do add .col-sm-x & .control-label to labels, and to wrap elements with <div class="col-sm-x mb-3"></div>.
The form options allow us to configure it all efficiently.
If needed, wrappers can contain two HTML elements.
It can be done with elementsWrapper, checkboxWrapper, and radioWrapper.
The table below shows the correspondence between the options and the generated HTML code. The values of the options are arbitrary, used simply to illustrate the examples.
/**
* Defines the layout (horizontal | vertical).
* Default is 'horizontal'
* Clears values from the PHP session if static::clear has been called before
* Catches posted errors
* Adds hidden field with the form ID
* Sets elements wrappers
*
* @param string $formId The ID of the form
* @param string $layout (Optional) Can be 'horizontal' or 'vertical'
* @param string $attr (Optional) Can be any HTML input attribute or js event EXCEPT class
* (class is defined in layout param).
* attributes must be listed separated with commas.
* Example : novalidate,onclick=alert(\'clicked\');
* @param string $framework (Optional) bs4 | bs5 | bulma | foundation | material | tailwind | uikit
* (Bootstrap 4, Bootstrap 5, Bulma, Foundation, Material design, Tailwind, UIkit)
* @return \phpformbuilder\Form
*/
options
Call setOptions() only if you change defaults options
/**
* Sets form layout options to match your framework
* @param array $userOptions (Optional) An associative array containing the
* options names as keys and values as data.
*/
Mode (production vs. development)
Default mode is production.
$form->setMode(string $mode);
/**
* set the form mode to 'development' or 'production'
* in production mode, all the plugins dependencies are combined and compressed in a single css or js file.
* the css | js files are saved in plugins/min/css and plugins/min/js folders.
* these 2 folders have to be wrirable (chmod 0755+)
*
* @param string $mode 'development' | 'production'
* @return \phpformbuilder\Form
*/
/**
* Redefines form action
*
* @param string $url The URL to post the form to
* @param boolean $addGetVars (Optional) If $addGetVars is set to false,
* url vars will be removed from destination page.
* Example : www.myUrl.php?var=value => www.myUrl.php
*
* @return \phpformbuilder\Form
*/
Layout
Set the layout of the form ("horizontal" or "vertical")
$form->setLayout(string $layout);
/**
* Set the layout of the form.
*
* @param string $layout The layout to use. Can be "horizontal" or "vertical".
* @return \phpformbuilder\Form
*/
Method
The default method is POST.
Call setMethod() only if you change default method
/**
* Ends a fieldset tag.
* @return \phpformbuilder\Form
*/
startDependentFields
Start a dependent fields block.
The dependent fields block is hidden and will be shown if $parentField changes to one of $showValues.
Don't forget to call endDependentFields to end your Dependent Fields block.
if $inverse is true, dependent fields will be shown if any other value than $showValues is selected
Each Dependent fields block can include one or several dependent fields blocks.
Dependent fields MUST NOT START with the same fieldname as their parent field.
/**
* Start a hidden block
* which can contain any element and html
* Hiden block will be shown on $parentField change
* if $parentField value matches one of $showValues
* @param string $parentField name of the field which will trigger show/hide
* @param string $showValues single value or comma separated values which will trigger show.
* @param boolean $inverse if true, dependent fields will be shown if any other value than $showValues is selected.
* @return void
*/
/**
* Adds an input element to the form.
*
* @param string $type The type of the input element.
* Accepts all input html5 types except checkbox and radio :
* button, color, date, datetime, datetime-local,
* email, file, hidden, image, month, number, password,
* range, reset, search, submit, tel, text, time, url, week
* @param string $name The name of the input element.
* @param string $value (Optional) The default value of the input element.
* @param string $label (Optional) The label of the input element.
* @param string $attr (Optional) Any additional attributes for the input element.
* Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the input's name.
* Example : class=my-class,placeholder=My Text,onclick=alert(\'clicked\');
* @return \phpformbuilder\Form
*/
/**
* Adds textarea to the form
* @param string $name The textarea name
* @param string $value (Optional) The textarea default value
* @param string $label (Optional) The textarea label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the textarea.
* Example : cols=30, rows=4;
* @return \phpformbuilder\Form
*/
Options for Select list
Always add your options BEFORE creating the select element
/**
* Adds option to the $selectName element
*
* IMPORTANT : Always add your options BEFORE creating the select element
*
* @param string $selectName The name of the select element
* @param string $value The option value
* @param string $txt The text that will be displayed
* @param string $groupName (Optional) the optgroup name
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the option.
* Example : class=my-class
* @return \phpformbuilder\Form
*/
Add the selectpicker class for Bootstrap select or the select2 class for the Select2 plugin, data-attributes and phpformbuilder will do the job.
Don't forget to activate your plugins to add the required css/js files to your page.
/**
* Adds a select element
*
* IMPORTANT : Always add your options BEFORE creating the select element
*
* @param string $selectName The name of the select element
* @param string $label (Optional) The select label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the input's name.
* Example : class=my-class
* @param bool $displayGroupLabels (Optional) True or false.
* Default is true.
* @return \phpformbuilder\Form
*/
The addCountrySelect() function generates a full country select dropdown list with all the countries options. Fortunately, you don't have to add the options one by one. The function does it for you.
You can choose your prefered plugin, which can be slimselect (default), bootstrap-select or select2.
If you choose the bootstrap-select plugin keep in mind that it requires Bootstrap's dropdown in your bootstrap.min.js
/**
* adds a country select list with flags
* @param string $selectName
* @param string $label (Optional) The select label
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the select.
* Example : class=my-class
* @param array $userOptions (Optional) :
* plugin : slimselect | select2 | bootstrap-select Default: 'slimselect'
* lang : MUST correspond to one subfolder of [$this->pluginsUrl]countries/country-list/country/cldr/
* *** for example 'en', or 'fr_FR' Default : 'en'
* flags : true or false. Default : true
* *** displays flags into option list
* flag_size : 16 or 32 Default : 32
* return_value : 'name' or 'code' Default : 'name'
* *** type of the value that will be returned
* @return \phpformbuilder\Form
*/
The addTimeSelect() function generates an hours:minutes drop-down list. The options allow you to set a minimum time, a maximum time, the interval in minutes between each option, and the separator character.
/**
* adds an hours:minutes select dropdown
* @param string $selectName
* @param string $label (Optional) The select label
* @param string (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the name of the select.
* Example : class=my-class
* @param array $userOptions (Optional) :
* min : the minimum time in hour:minutes Default: '00:00'
* max : the maximum time in hour:minutes Default: '23:59'
* step : the step interval in minutes between each option Default: 1
* format : '12hours' or '24hours' Default : '24hours'
* display_separator : the displayed separator character between hours and minutes Default : 'h'
* value_separator : the value separator character between hours and minutes Default : ':'
* @return \phpformbuilder\Form
*/
/**
* Adds radio button to $groupName element
*
* @param string $groupName The radio button groupname
* @param string $label The radio button label
* @param string $value The radio button value
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* Example : checked=checked
* @return \phpformbuilder\Form
*/
/**
* Prints radio buttons group.
*
* @param string $groupName The radio button group name
* @param string $label (Optional) The radio buttons group label
* @param bool $inline (Optional) True or false.
* Default is true.
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* Example : class=my-class
* @return \phpformbuilder\Form
*/
/**
* Prints checkbox group.
*
* @param string $groupName The checkbox group name (will be converted to an array of indexed value)
* @param string $label (Optional) The checkbox group label
* @param bool $inline (Optional) True or false.
* Default is true.
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* Example : class=my-class
* @return \phpformbuilder\Form
*/
/**
* Adds a button to the form
*
* If $btnGroupName is empty, the button will be automatically displayed.
* Otherwise, you'll have to call printBtnGroup to display your btnGroup.
*
* @param string $type The html button type
* @param string $name The button name
* @param string $value The button value
* @param string $text The button text
* @param string $attr (Optional) Can be any HTML input attribute or js event.
* attributes must be listed separated with commas.
* If you don't specify any ID as attr, the ID will be the input's name.
* Example : class=my-class,onclick=alert(\'clicked\');
* @param string $btnGroupName (Optional) If you wants to group several buttons, group them then call printBtnGroup.
* @return \phpformbuilder\Form
*/
/**
* Prints buttons group.
*
* @param string $btnGroupName The buttons' group name
* @param string $label (Optional) The buttons group label
* @return \phpformbuilder\Form
*/
/**
* Adds HTML code at any place of the form
*
* @param string $html The html code to add.
* @param string $elementName (Optional) If not empty, the html code will be inserted
* just before or after the element.
* @param string $pos (Optional) If $elementName is not empty, defines the position
* of the inserted html code.
* Values can be 'before' or 'after'.
* @return \phpformbuilder\Form
*/
When your HTML is linked to an element, always call addHtml() BEFORE creating the element.
To add helper texts, icons, buttons, or any input group addon, use the shortcut functions:
/**
* Wraps the element with HTML code.
*
* @param string $html The HTML code to wrap the element with.
* The HTML tag must be opened and closed.
* Example :
* @param string $elementName The form element to wrap.
* @return \phpformbuilder\Form
*/
/**
* Renders the HTML code of the form.
*
* @param bool $debug (Optional) True or false.
* If true, the HTML code will be displayed
* @param bool $display (Optional) True or false.
* If false, the HTML code will be returned but not displayed.
* @return \phpformbuilder\Form
*
*/
Ajax loading
PHP Form Builder allows you to load your forms with Ajax.
Loading in Ajax allows to:
integrate your forms on any HTML page
load the forms asynchronously, which is suitable for your page loading speed
To load your form with Ajax:
1
Create your form using the built-in PHP functions and save it in a PHP file somewhere on your server. Set the ajax option to true to enable Ajax loading. Here's a sample code:
<?php
use phpformbuilder\Form;
use phpformbuilder\Validator\Validator;
/* =============================================
start session and include form class
============================================= */
$formId = 'my-form';
session_start();
include_once rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . '/php/phpformbuilder/phpformbuilder/autoload.php';
/* =============================================
validation if posted
============================================= */
if ($_SERVER["REQUEST_METHOD"] == "POST" && Form::testToken($formId) === true) {
// do stuff
}
/* ==================================================
The Form
================================================== */
$form = new Form($formId, 'horizontal', 'data-fv-no-icon=true, novalidate');
// $form->setMode('development');
// enable Ajax loading
$form->setOptions(['ajax' => true]);
// add your fields & plugins here
// render the form
$form->render();
2
In your main file (html): Create a div with a specific id, for instance:
<div id="ajax-form"></div>
3
In your main file (html):
Add the JavaScript code to load your form:
<!-- Ajax form loader -->
<!-- Change the src url below if necessary -->
<script src="/phpformbuilder/plugins/ajax-data-loader/ajax-data-loader.min.js"></script>
<script>
// --- SETUP YOUR FORM(S) BELOW IN THE "ajaxForms" VARIABLE ---
var ajaxForms = [
{
formId: 'ajax-contact-form-1',
container: '#ajax-form',
url: 'ajax-forms/contact-form-1.php'
}
];
// --- NO NEED TO CHANGE ANYTHING AFTER THIS LINE ---
// --- COPY/PASTE THE FOLLOWING CODE IN THE HTML FILE THAT WILL LOAD THE FORM ---
document.addEventListener('DOMContentLoaded', function() {
ajaxForms.forEach(function(currentForm) {
const $formContainer = document.querySelector(currentForm.container);
if (typeof($formContainer.dataset.ajaxForm) === 'undefined') {
fetch(currentForm.url)
.then((response) => {
return response.text()
})
.then((data) => {
$formContainer.innerHTML = '';
$formContainer.dataset.ajaxForm = currentForm;
$formContainer.dataset.ajaxFormId = currentForm.formId;
loadData(data, currentForm.container);
}).catch((error) => {
console.log(error);
});
}
});
});
</script>
/**
* load scripts with loadJS
* https://github.com/muicss/loadjs
*
* @param string $bundle optional loadjs bundle name to wait for
* @return void
*/
Get the plugins includes
The getIncludes() function returns the HTML code required by each plugin used in your form. Unlike the printIncludes() function, it returns the code but does not display it ("return" instead of "echo").
getIncludes(string $type, bool $debug = false);
Print plugins includes
The printIncludes() function inserts the CSS & JavaScript files required by each plugin used in your form.
Call printIncludes() at the right places (generally css inside your <head></head> section, and js just before </body>).
If your form contains no plugin, no need to call this function.
/**
* Prints html code to include css or js dependancies required by plugins.
* i.e.:
* <link rel="stylesheet" ... />
* <script src="..."></script>
*
* @param string $type value : 'css' or 'js'
* @param bool $debug (Optional) True or false.
* If true, the html code will be displayed
* @param bool $display (Optional) True or false.
* If false, the html code will be returned but not displayed.
* @return string|object $finalOutput|$this
*/
About optimization
PHP Form Builder is conceived for maximum optimization and speedy loading time.
The getJsCode() function returns the JS code generated by the plugin. Unlike the printJsCode() function, it returns the code but does not display it ("return" instead of "echo").
getJsCode(string $type, bool $debug = false);
Print plugins JS code
Prints the JS code generated by the plugin.
If your form contains no plugin, no need to call this function.
/**
* Prints js code generated by plugins.
* @param bool $debug (Optional) True or false.
* If true, the html code will be displayed
* @param bool $display (Optional) True or false.
* If false, the html code will be returned but not displayed.
* @return \phpformbuilder\Form
*/
Example with colorpicker plugin
$form->addInput('text', 'my-color', '', 'Pick a color:', 'data-colorpicker=true');
$form->printJsCode();
/**
* Allows to group inputs in the same wrapper
*
* Arguments can be :
* - a single array with fieldnames to group
* OR
* - fieldnames given as strings
*
* @param string|array $input1 The name of the first input of the group
* OR
* array including all fieldnames
*
* @param string $input2 The name of the second input of the group
* @param string $input3 [optional] The name of the third input of the group
* @param string $input4 [optional] The name of the fourth input of the group
* @param string ...etc.
* @return \phpformbuilder\Form
*/
The setCols() function wraps label and fields with columns.
The columns can only be set in horizontal forms.
$form->setCols(int $labelColNumber, int $fieldColNumber, string $breakpoint = 'sm');
Bootstrap 4 / 5 auto column Bootstrap 4 & Bootstrap 5 allows automatic-width columns. To build automatic-width columns, set $fieldsCols to -1
/**
* Shortcut for labels & cols options
*
* @param int $labelColNumber number of columns for label
* @param int $fieldColNumber number of columns for fields
* @param string $breakpoint Bootstrap's breakpoints : xs | sm | md |lg
* @return \phpformbuilder\Form
*/
addHelper() MUST always be called BEFORE creating the element
/**
* Shortcut to add element helper text
*
* @param string $helperText The helper text or HTML to add.
* @param string $elementName the helper text will be inserted just after the element.
* @return \phpformbuilder\Form
*/
Example
$form->addHelper('Enter your last name', 'last-name');
$form->addInput('text', 'last-name', '', 'Last name', 'required');
Add Addon
Adds button or text addon before or after the chosen field
/**
* shortcut to prepend or append any adon to an input
* @param string $inputName the name of target input
* @param string $addonHtml addon html code
* @param string $pos before | after
* @return \phpformbuilder\Form
*/
/**
* add a HTML heading
*
* @param string $html the heading content text or HTML
* @param string $tagName (Optional) the heading tag name (h1, h2, ...)
* @param string $attr (Optional) the heading attributes
* @return void
*/
Example
$form->addHeading('Please fill the form', 'h5', 'class=text-muted');
/**
* shortcut to prepend or append icon to an input
*
* @param string $inputName the name of target input
* @param string $iconHtml icon html code
* @param string $pos before | after
* @return \phpformbuilder\Form
*/
/**
* build an Alert message according to the framework html
*
* @param string $contentText
* @param string $framework bs4|bs5|bulma|foundation|material|tailwind|uikit
* @param string $type success|primary|info|warning|danger
* @return string the alert HTML code
*/
Example
Form::buildAlert('<strong>This is a danger alert example</strong>', 'bs5', 'danger');
/**
* Start a column HTML div
*
* @param int $colNumber - the number of columns between 1 and 12
* @param string $breakpoint - xs, sm, md or lg
* @param string $additionalClass
* @param string $id
* @return \phpformbuilder\Form
*/
PHP Form Builder manages the memorization of fields and posted values without you needing taking any action.
If your form is posted with errors, i.e., validation fails, the posted values are automatically displayed in the corresponding fields.
To set the default value of a field, it must be saved in the PHP session in this way:
$_SESSION['form-id']['field-name'] = 'my-value';
If the form is posted, the field will have the posted value. Otherwise, it will have the default value registered in the PHP session.
Here's the global workflow:
You create your form and add fields.
PHP Form Builder registers each field name in PHP session: $_SESSION['form-id']['fields'][] = 'field-name';
You post the form
You validate the posted values: $validator = Form::validate('form-id');
If the validation fails:
The error messages are stored in PHP session: $_SESSION['errors'][$formId] as $field => $message
You instanciate your form again:
PHP Form Builder registers the posted values in PHP session: $_SESSION['form-id']['field-name'] = $_POST['my-value'];
PHP Form Builder gets and displays the session value and the possible error for each field.
registerValues (static function)
When you instantiate a form, it automatically stores corresponding posted values in session unless you called the clear function before creating your form.
Values are registered this way: $_SESSION['form-id']['field-name']
You can call Form::registerValues('form-id') manually at any time.
mergeValues is used to merge previously registered values in a single array. Usefull for step forms to send all steps values by email or store into database for example.
/**
* merge previously registered session vars => values of each registered form
* @param array $formsArray array of forms IDs to merge
* @return array pairs of names => values
* ex : $values[$fieldName] = $value
*/
clear (static function)
Clears the corresponding previously registered values from session.
Form::clear('form-id');
Validation
Overview
PHP Form Builder comes with two different validation systems.
PHP Validation The form is validated after being posted. It is a PHP validation, essential for security.
JavaScript Validation The fields are validated on the fly for better User Experience.
Never forget: The only way to avoid security issues is PHP Validation. Users can easily disable JavaScript and get around the JavaScript validation.
PHP Validation
Basics
To create a new validator object and auto-validate required fields, use this standard-code (replace 'form-id' with your form ID)
/* =============================================
validation if posted
============================================= */
if ($_SERVER["REQUEST_METHOD"] == "POST" && Form::testToken('form-id') === true) {
// create validator & auto-validate required fields
$validator = Form::validate('form-id');
// additional validation
$validator->maxLength(100)->validate('message');
$validator->email()->validate('user-email');
// check for errors
if ($validator->hasErrors()) {
$_SESSION['errors']['form-id'] = $validator->getAllErrors();
} else {
// validation passed, you can send email or do anything
}
}
$validator = Form::validate('form-id');
This loads the Validator, then creates a new Validator object, and finally validates the required fields, if any. Required fields validation is automatic. There's nothing more to do.
Then we use $validator native methods for others validations (email, date, length, ...)
// check for errors
if ($validator->hasErrors()) {
$_SESSION['errors']['form-id'] = $validator->getAllErrors();
}
If there are some errors, we register them in the PHP session. The form will automatically display the error messages.
Dependent fields validation
Dependent fields validation is something magic.
Form::validate() validates the required dependent fields only if their parent field value matches the condition to display them.
If you use additional validators, for example $validator->email()->validate('user-email'); you have to test if the field has to be validated or not according to your dependent fields conditions:
if ($_POST['parent-field'] == 'value') {
$validator->email()->validate('user-email');
}
$validator->required()->validate('my-field.0');
/* if at least 2 values must be selected: */
$validator->required()->validate(array('my-field.0', 'my-field.1'));
The field value must be a valid credit card number.
RequiredoneOf($allowed, $message = null)
The field value must be one of the $allowed values. $allowed can be either an array or a comma-separated list of values. If comma-separated, do not include spaces unless intended for matching.
RequiredhasLowercase($message = '')
The field value must contain at least one lowercase character.
RequiredhasUppercase($message = '')
The field value must contain at least one uppercase character.
RequiredhasNumber($message = '')
The field value must contain at least one numeric character.
RequiredhasSymbol($message = '')
The field value must contain at least one symbol character.
Define your own custom callback validation function. $callback must pass an is_callable() check. $params can be any value, or an array if multiple parameters must be passed.
Required
: Empty fields are NOT VALID
Optional
: Empty fields are VALID
Validation examples
Validation examples code
Main validation code
if ($_SERVER["REQUEST_METHOD"] == "POST" && Form::testToken('my-form-id') === true) {
// create validator & auto-validate required fields
$validator = Form::validate('contact-form-1');
// additional validation
$validator->email()->validate('email-field-name');
// add custom message if you want:
$validator->integer('You must enter a number')->validate('number-field-name');
$validator->hcaptcha('hcaptcha-secret-key', 'Captcha Error')->validate('h-captcha-response');
// check for errors
if ($validator->hasErrors()) {
$_SESSION['errors']['my-form-id'] = $validator->getAllErrors();
}
}
Checkboxes validation
If we want at least one checked:
$form->addCheckbox('chk_group', 'check 1', 1);
$form->addCheckbox('chk_group', 'check 2', 2);
$form->addCheckbox('chk_group', 'check 3', 3);
$form->printCheckboxGroup('chk_group', 'check one: ');
/* Validation: */
if(!isset($_POST['chk_group']) || !is_array($_POST['chk_group'])) {
/* if none are posted, we register the error */
$validator->required('check at least one checkbox please')->validate('chk_group');
}
Trigger an error manually
If we want at least 2 checked:
$form->addCheckbox('chk_group', 'check 1', 1);
$form->addCheckbox('chk_group', 'check 2', 2);
$form->addCheckbox('chk_group', 'check 3', 3);
$form->printCheckboxGroup('chk_group', 'check at least 2: ');
/* Validation: */
if(!isset($_POST['chk_group']) || !is_array($_POST['chk_group']) || count($_POST['chk_group']) < 2) {
/* if less than two are posted, we create a tricky validation which always throws an error */
$validator->maxLength(-1, 'Check at least two please')->validate('chk_group');
}
To add any custom validation, use HTML5 attributes with validatorname and validator option:
<?php
$form->addInput('text', 'username', 'Username', '', 'data-fv-not-empty, data-fv-not-empty___message=The username is required and cannot be empty');
When the user submits the form, the validator automatically sends the form if all the fields are valid. If you want to disable this behavior add the data-fv-no-auto-submit attribute to your form:
$form = new Form('my-form', 'vertical', 'data-fv-no-auto-submit=true, novalidate');
Callback & JavaScript validation API
The callback function allows you to enable/disable validators and use the Form Validation plugin API the way you want.
Create a function named fvCallback - The validator plugin will call it when it's ready. Then you can use all the validator's API.
The callback function name is fvCallback
You can access the form validator instance this way:
var form = forms['my-form'];
// form.fv is the validator
form.fv.on('core.form.invalid', function() {
// do stuff
});
example of use:
<script type="text/javascript">
var fvCallback = function() {
var form = forms['my-form'];
// form.fv is the validator
// you can then use the formvalidation plugin API
form.fv.on('core.form.invalid', function() {
// do stuff
});
};
</script>
/**
* Send an email with posted values and custom content
*
* Tests and secures values to prevent attacks (phpmailer/extras/htmlfilter.php => HTMLFilter)
* Uses custom html/css template and replaces shortcodes - syntax : {fieldname} - in both html/css templates with posted|custom values
* Creates an automatic html table with vars/values - shortcode : {table}
* Merges html/css to inline style with Pelago Emogrifier
* Sends email and catches errors with Phpmailer
* @param array $options
* sender_email : the email of the sender
* sender_name [optional] : the name of the sender
* reply_to_email [optional] : the email for reply
* recipient_email : the email destination(s), separated with commas
* cc [optional] : the email(s) of copies to send, separated with commas
* bcc [optional] : the email(s) of blind copies to send, separated with commas
* subject : The email subject
* isHTML : Send the mail in HTML format or Plain text (default: true)
* textBody : The email body if isHTML is set to false
* attachments [optional] : file(s) to attach : separated with commas, or array (see details inside function)
* template [optional] : name of the html/css template to use in phpformbuilder/mailer/email-templates/
* (default: default.html)
* human_readable_labels [optional]: replace '-' ans '_' in labels with spaces if true (default: true)
* values : $_POST
* filter_values [optional] : posted values you don't want to include in the e-mail automatic html table
* custom_replacements [optional] : array to replace shortcodes in email template. ex : array('mytext' => 'Hello !') will replace {mytext} with Hello !
* sent_message [optional] : message to display when email is sent. If sent_message is a string it'll be automatically wrapped into an alert div. Else if sent_message is html code it'll be displayed as is.
* debug [optional] : displays sending errors (default: false)
* smtp [optional] : use smtp (default: false)
*
* @param array $smtpSettings
* host : String Specify main and backup SMTP servers - i.e: smtp1.example.com, smtp2.example.com
* smtp_auth: Boolean Enable SMTP authentication
* username: String SMTP username
* password: String SMTP password
* smtp_secure: String Enable TLS encryption. Accepted values: tls|ssl
* port: Number TCP port to connect to (usually 25 or 587)
*
* @return string sent_message
* success or error message to display on the page
*/
The fields named *-token and *submit-btn are automatically filtered. It means that the posted values will not appear in the email sent.
// Create 'my-custom-template.html' and 'my-custom-template.css' in the 'phpformbuilder/mailer/email-templates-custom/' folder
// You can use shortcodes in your HTML template, they will be automatically replaced with the posted values.
// For instance, {user-email} will be replaced with the real $_POST['user-email'] value.
// You can use the special {table} shortcode to display a complete table with all the posted fieldnames / values.
// Then:
$emailConfig = array(
'sender_email' => 'contact@phpformbuilder.pro',
'sender_name' => 'PHP Form Builder',
'recipient_email' => addslashes($_POST['user-email']),
'subject' => 'Contact From PHP Form Builder',
'template' => 'my-custom-template.html',
'filter_values' => 'submit-btn, token',
'debug' => true
);
$sentMessage = Form::sendMail($emailConfig);
Your message has been successfully sent !
Example with Text Email (no template, no HTML)
$emailConfig = array(
'sender_email' => 'contact@phpformbuilder.pro',
'sender_name' => 'PHP Form Builder',
'recipient_email' => addslashes($_POST['user-email']),
'subject' => 'Contact From PHP Form Builder',
'textBody' => $_POST['message'], // textBody is required or the message won't be sent.
'isHTML' => false,
'debug' => true
);
$sentMessage = Form::sendMail($emailConfig);
Your message has been successfully sent !
Complete Example using a styled template
The following code will :
Load a styled email template phpformbuilder/mailer/email-templates/custom[.html/.css]
Replace template shortcodes, including header image and colors, with the values set in $replacements
Replace the other template's shortcodes with the posted values
Merge HTML/CSS to inline style with Pelago Emogrifier
Copy/paste an existing HTML/CSS template from phpformbuilder/mailer/email-templates/ and save it into phpformbuilder/mailer/email-templates-custom/ (or create a new HTML file + a new css file with both same name)
Use the shortcode {table} in your HTML template if you want to add an automatic HTML table with all posted values.
Write the fieldnames between braces in your template. They'll be replaced automatically with posted values. For example: Hello {user-first-name} {user-name}
[optional] You can use the custom_replacements option to replace specific texts in email with specific values
Call sendMail() function and set your HTML template in template option
How to replace array values using sendMail() function
The best way to replace the posted array values in a custom email template is to create non-array indexed values, then add them in the sendMail custom_replacements option.
Example using array values
<?php
/*
Example with three posted colors
Email template will use {color_1}, {color_2}, {color_3}
*/
// create index
$i = 1;
// loop through posted values
foreach ($_POST['color'] as $color) {
// name indexed variable and give it posted value
$var = 'color_' . $i;
$$var = $color;
// increment index
$i++;
}
$options = array(
// [...]
'custom_replacements' => array(
'color_1' => $color_1,
'color_2' => $color_2,
'color_3' => $color_3
),
// [...]
);
$sentMessage = Form::sendMail($options);
Your message has been successfully sent !
Attachments Examples
Examples using the FileUpload plugin
The path of the uploaded files is defined in the fileuploader plugin configuration (variable $fileUploadConfig) when you instantiate the fileuploader plugin.
To get the information about the uploaded file you have to call the function FileUploader::getPostedFiles
Single file:
// at the beginning of your file
use fileuploader\server\FileUploader;
include_once rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . 'phpformbuilder/plugins/fileuploader/server/class.fileuploader.php';
// once the form is validated
$options = array(
[...]
);
if (isset($_POST['user-file']) && !empty($_POST['user-file'])) {
// set the filepath according to the path defined in the fileuploader plugin configuration
$path = rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . '/file-uploads/';
// get the posted filename
$postedFile = FileUploader::getPostedFiles($_POST['user-file']);
$filename = $postedFile[0]['file'];
// add the attachment to the email
$options['attachments'] = $path . $filename;
}
$msg = Form::sendMail($options);
Multiple files separated with commas:
// at the beginning of your file
use fileuploader\server\FileUploader;
include_once rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . 'phpformbuilder/plugins/fileuploader/server/class.fileuploader.php';
// once the form is validated
$options = array(
[...]
);
if (isset($_POST['user-files']) && !empty($_POST['user-files'])) {
// set the filepath according to the path defined in the fileuploader plugin configuration
$path = rtrim($_SERVER['DOCUMENT_ROOT'], DIRECTORY_SEPARATOR) . '/file-uploads/';
// get the posted filename
$postedFiles = FileUploader::getPostedFiles($_POST['user-files']);
$attachments = array();
foreach ($postedFiles as $pf) {
$filename = $pf['file'];
$attachments[] = $path . $filename;
}
// add the attachments to the email
$options['attachments'] = implode(',', $attachments);
}
$msg = Form::sendMail($options);
// Execute a SQL query with (or without) placeholders, then fetch the results
$sql = 'SELECT * FROM test_table';
$db->query($sql);
// Execute the same query in debug mode
$rows = $db->query($sql, $values, true);
// Execute a SQL query with placeholders
$sql = 'SELECT id, name, age FROM test_table WHERE active = :active';
$values = array('active' => true);
$db->query($sql, $values);
// loop through the results
while ($row = $db->fetch()) {
echo $row->name . '<br>';
}
// or fetch all the records then loop
// (this function should not be used if a huge number of rows have been selected, otherwise it will consume a lot of memory)
$rows = $db->fetchAll();
foreach($rows as $row) {
echo $row->name . ' ';
}
$db->select - The DB class creates the SQL query for you
// Setup the query
$columns = array('id', 'name');
$where = false;
$extras = array('order_by' => 'name ASC');
$db->select('test_table', $columns, $where, $extras);
// loop through the results
while ($row = $db->fetch()) {
echo $row->name . '<br>';
}
// or fetch all the records then loop
// (this function should not be used if a huge number of rows have been selected, otherwise it will consume a lot of memory)
$rows = $db->fetchAll();
foreach($rows as $row) {
echo $row->name . ' ';
}
$db->convertQueryToSimpleArray - Convert the rows to an associative array then loop
