Simple Example¶

Data validation is essential in all programming to ensure safety and correctness of all programs. The Validation service simplifies this task with a concise and extensible API.

$rules = array(
  'username' => 'required|minLength[5]',
  'password' => 'required|minLength[5]'
);

$result = ee('Validation')->make($rules)->validate($_POST);

if ($result->isValid())
{
  // yay
}

// no :(

Defining Rules¶

Which rules to apply is defined in a string of pipe delimited rule names. The rules are processed from left to right:

"required|alphaNumeric"

Some rules may also take parameters. These are added in braces after the rule name:

"required|enum[blue,red,yellow]" // only allow these three color names

Required Fields¶

The required rule is used to ensure that fields are set and not blank. A field is considered blank if it only contains whitespace.

If no required rule is encountered then a blank field is considered valid regardless of the other rules:

"numeric|alpha" // despite conflicting rules, a blank field will pass

This means that you will usually want to use required at the beginning of the rule string. The exception being conditional rules, which are covered later.

Conditional Rules¶

There are times where you only want to apply validation if a certain value has been set. The whenPresent rule allows you to do this:

$rules = array(
  'name' => 'whenPresent|minLength[45]'
);

A more complex case of this is when certain fields rely on the presence of other fields. A common case for this are checkboxes that enable a functionality. For example, a checkbox to subscribe to an email newsletter may require an email address field that is otherwise optional. The whenPresent rule accepts a list of fields that must all be present for the rules to be applied:

$rules = array(
  'email' => 'whenPresent[newsletter]|required|email'
);

Custom Rules¶

ExpressionEngine allows you to create one-off validation rules on any validator object. This is done by calling the defineRule method:

$validator = ee('Validation')->make();

$validator->defineRule('impossible', function($key, $value, $parameters)
{
  return ($value == 5 && $value == 6);
});

$validator->setRules(array(
  'age' => 'required|impossible'
));

$result = $validator->validate($data);

Custom Conditional Rules¶

Custom conditional rules can be created by calling skip() on the ValidationRule object. This can be useful, for example, if you need to conditionally validate a field based on the value of another field:

use EllisLab\ExpressionEngine\Service\Validation\Validator;

$data = $_POST;

$validator->defineRule('whenNotifyTypeIs', function($key, $value, $parameters, $rule) use ($data)
{
  return ($data['notify-type'] == $parameters[0]) ? TRUE : $rule->skip();
});

$validator->setRules(array(
  'notify-type' => 'required|enum[email,sms]',
  'email' => 'whenNotifyTypeIs[email]|required|email',
  'sms' => 'whenNotifyTypeIs[sms]|required|regex[/^\d{3}-\d{3}-\d{4}$/]',
));

Checking a Single Rule¶

check($rule, $value)¶

Occasionally, you might need to check whether a value passes a validation rule, you can do that using the check() method:

$valid = ee('Validation')->check('uniqueEmail', '[email protected]');

Parameters:	$rule (string) – The rule to check, see Built-in Rules $value (string) – The value to check
Returns:	TRUE if the $value is valid
Return type:	boolean

Built-in Rules¶

Handling Results¶

Handling validation results can be as fine grained as you need it to be. A call to validate() will return a result object:

$result = $validator->validate($data);

$result->isValid(); // true | false
$result->isNotValid(); // false | true

$result->hasErrors('username'); // true | false

$errors = $result->getAllErrors(); // $errors['fieldname']['rulename'] = 'Message';

// either:
$errors = $result->getAllErrors();
$username_errors = $errors['username'];

// or better:
$username_errors = $result->getErrors('username');