Overview
FormCheck class is intended to validate web forms. To validate a form you have to specify xml file with form configuration.
<?xml version="1.0" encoding="utf-8"?>
<FormCheck>
<!-- Configuration of validations to be performed -->
<validations>
<validation type="empty">username,firstname,lastname,email</validation>
<validation type="regexp" pattern="/^[0-9a-z]+$/i">username</validation>
<validation type="email">email</validation>
</validations>
<!-- Error messages -->
<errors>
<username>
<empty>Please enter username.</empty>
<regexp>Please use only alphanumeric characters in your username.</regexp>
</username>
<firstname>
<empty>Please specify your firstname.</empty>
</firstname>
<lastname>
<empty>Please specify your lastname.</empty>
</lastname>
<email>
<empty>Please specify your e-mail</empty>
<email>Your e-mail address is incorrect</email>
</email>
</errors>
</FormCheck>
The root element of configration file must be named FormCheck and must contain two major sub elements: validations and errors.
Inside of validations element you are defining all validations which should be performed during form validation. Each validation is described within validation element, which must have an attribute type, which in turn specifies type of validation (more details on validation types in just a moment). And within validation element you have to specify comma separated list of fields you want to validate.
Inside of errors element you are defining error messages for each field and for each validation type. For example:
<email>
<empty>Please specify your e-mail.</empty>
<email>Your e-mail is incorrect.</email>
</email>
Example above defines two error messages for field email: for validation of type empty (when field email is empty) and for validation of type email (when e-mail is incorrect).
Validation types
birthdate
Checks if the field value is a valid birthdate (given in the format: YYYY-MM-DD).
date
Checks if the field value is a valid date of the format YYYY-MM-DD.
Checks if the field value is a correct e-mail address.
empty
Checks if the field value is not an empty string. Do be aware, that "0" is not an empty string.
equals
Checks if the field value is equal to value of another field. In most cases is used by checking password confirmation field.
Parameters:
- field
- Name of the "another" field to be compared with.
regexp
Checks the field value against a regular expression. This allows a wide variety of checks to be made and can be used for things like phone numbers, format of nicknames, etc.
Parameters:
- pattern
- Regular expression pattern. If pattern has quotes or any other characters not allowed to be used in XML attributes, use constansts.
select
Checks if the field value is within a list of predefined options.
Parameters:
- options
- Comma delimited list of allowable options. For example if value should be either "1", "2" or "3", then the attribute value should be "1,2,3"
zipcode
Checks if ZIP code (post code) is in correct format.
Parameters:
- countries (optional)
- List of comma delimited ISO codes of countries (in ISO 3166-1 alpha-2 format), zipcode format of which you want to validate. For example if you want to validate if zipcode is whether Austrian or German, then countries attribute should be "at,de". By default the value of this attribute is "*", what means all countries.
Simple validation
// Instanciating a class
$formCheck = new FormCheck("form.xml");
// Validating form
$formCheck->Check($_POST);
// Checking if form has errors
if($formCheck->hasErrors)
{
// Getting error messages as an indexed array
$errors = $formCheck->GetErrorTexts();
// i.e. $errors = array("Please enter your name", "Please enter your e-mail");
// Or you get errors as an associave array
$errors = $formCheck->GetErrorTextsAssoc();
// i.e. $errors = array(
// "name" => "Please enter your name", "email" => "Please enter your e-mail"
// );
}
else
{
// ... form contains no errors ...
}
However, in some cases you may wish to trim form values before validating a form. For example, assume that user has entered only whitespaces. For situations such as these, you can use TrimFormValues static method to trim all form values.
// Trimming form values
$formVars = FormCheck::TrimFormVars($_POST);
// Validating form
$formCheck = new FormCheck("form.xml");
$formCheck->Check($formVars);
if($formCheck->hasErrors)
{
// ... displaying errors ...
}
Custom validations
Let's assume you want to check if username already exists in database. First you need to specify 2 validation and 3 error messages in xml with form configuration:
form.xml
<?xml version="1.0" encoding="utf-8"?>
<FormCheck>
<!-- Configuration of validations to be performed -->
<validations>
<validation type="empty">username</validation>
<validation type="regexp" pattern="/^[0-9a-z]+$/i">username</validation>
</validations>
<!-- Error messages -->
<errors>
<username>
<empty>Please enter username.</empty>
<regexp>Please use only alphanumeric characters in your username.</regexp>
<exists>Username you have entered already exists.</exists>
</username>
</errors>
</FormCheck>
$formCheck = new FormCheck("form.xml");
// Performing empty and regexp validations...
$formCheck->Check($_POST);
// If username has been entered and has a correct format,
// checking if it exists it database
if($formCheck->hasErrors == false)
{
$userExists = userNameExists($_POST["username"]);
if($userExists)
{
$formCheck->RegisterError("username", "exists");
}
}
if($formCheck->hasErrors)
{
$errors = $formCheck->GetErrorTexts();
}
Protecting against bots
FormCheck class provides a simple protection against spam bots. This protection is not as good as Captcha codes, but it is better than nothing. It creates a hidden field inside of your form with a secret key, unique for each form submitting. After the form has been submitted it verifies if secret key matches. Hovewer, it requires a PHP session to be started.
// Starting session
session_start();
$formCheck = new FormCheck("form.xml");
// If form has been submitted and secret key matches
if(!empty($_POST) && $formCheck->CheckSecret())
{
$formCheck->Check($_POST);
if($formCheck->hasErrors == false)
{
// ... saving results here ...
}
// Cleaning secret key from the session and disabling second form submit
$formCheck->ClearSecret();
}
else
{
// Generating hidden field
$hiddenField = $formCheck->GetHiddenField();
// $hiddenField represents HTML code of hidden input element.
// i.e. <input type="hidden" name="[key1]" value="[key2]" />
// ... displaying form here ...
}