README

Simple, extendable form validator for multi-dimensional forms

Installation

PHP Form Validator is available on Packagist (using semantic versioning), and installation via Composer is the recommended way to install. Just add this line to your composer.json file:

"madesimple/php-form-validator": "^2.8"

or run:

composer require madesimple/php-form-validator

Validation Rules

Validation rules are an associative array of dot notation field names in the input array to a pipe separated string of rules. The asterisk, *, can be use in the dot notation as a wildcard. For example, a set of rules could look like this:

// Rules Set
$rulesSet = [
    'username'         => 'required|alpha-numeric|max-str-len:50',
    'firstName'        => 'required|human-name|required-with:lastName|max-str-len:255',
    'lastName'         => 'required|human-name|required-with:firstName|max-str-len:255',
    'address.line1'    => 'present',
    'address.postCode' => 'present',
    'likes.*.item'     => 'required-with:likes.*.rating|max-str-len:50'
    'likes.*.stars'    => 'required-with:likes.*.item|is:int|min:1|max:5'
];

// Valid Input
$input = [
    'username' => 'jbloggs',
    'firstName' => 'Joe',
    'lastName' => 'Bloggs',
    'address' => [
        'line1' => '123 Fake St',
        'postCode' => 'AB12 3CD',
    ]
    'likes' => [
        [
            'item'  => 'php-form-validator',
            'stars' => 5
        ]
    ]
];

The following are all the validation rules that this library provides:

Rule Name	Keyword	Parameters	Description
Present	`present`		The field must be present but can have any value including `null`.
Required	`required`		The field must be present and cannot be `null` (can be an empty string).
Required If	`required-if`	`field(,value)+`	The field is required if the specified field(s) and the specified value(s).
Required With	`required-with`	`field`	The field is required if the other field is not `null`.
Required With All	`required-with-all`	`field(,field)*`	The field is required if all of the other fields are not `null`.
Required With Any	`required-with-any`	`field(,field)*`	The field is required if any of the other fields are not `null`.
Required Without	`required-without`	`field`	The field is required if the other field is `null`.
Equals	`equals`	`field`	The field's value must equals the other specified field's value.
Not Equals	`not-equals`	`field`	The field's value must not equal the other specified field's value.
Identical	`identical`	`field`	The field's value must be identical the other specified field's value.
Not Identical	`not-identical`	`field`	The field's value must not be identical the other specified field's value.
In	`in`	`value(,value)*`	The field must equal one of the specified options.
Not In	`not-in`	`value(,value)*`	The field must not equal one of the specified options.
Contains	`contains`	`value(,value)*`	The field should be an array and must contain all the specified options (may contain other values not listed).
Contains Only	`contains-only`	`value(,value)*`	The field should be an array and must contain only the specified options.
Minimum Array Count	`min-arr-count`	`int`	The field should be an array and must have an `array_count` of at least the specified value.
Maximum Array Count	`max-arr-count`	`int`	The field should be an array and must have an `array_count` of at most the specified value.
Minimum	`min`	`int`	The field should be numeric and must be at least the specified value.
Maximum	`max`	`int`	The field should be numeric and must be at most the specified value.
Greater Than	`greater-than`	`field`	The field should be numeric and must have a value greater than the other field.
Less Than	`less-than`	`field`	The field should be numeric and must have a value less than the other field.
Alpha	`alpha`		The field must only contain alphabetic characters.
Alpha Numeric	`alpha-numeric`		The field must only contain alphabetic and numerical characters.
Minimum String Length	`min-str-len`	`int`	The field should be string and must have a `strlen` of at least the specified value.
Maximum String Length	`max-str-len`	`int`	The field should be a string and must have a `strlen` of at most the specified value.
String Length	`str-len`	`int`	The field should be a string and must have a `strlen` of exactly the specified value.
Human Name	`human-name`		The field must be a valid human name.
Is: ...	`is`	`type`	The field must be of the specified basic PHP type. There must be a corresponding `is_<type>` method.
Email	`email`		The field must be a valid email address
Date	`date`	`(format)?`	The field must be a valid date in the specified format (defaults to `'Y-m-d'`).
URL	`url`		The field must be a valid URL.
UUID	`uuid`		The field must be a valid UUID (\universally unique identifier).
Card Number	`card-number`		The field must be a valid card number.
Regex	`regex`	`regex pattern`	The field must match the regex pattern.
Not Regex	`not-regex`	`regex pattern`	The field must not match the regex pattern.

Adding Extra Rules

Extra rules can be added to the validator to extend its functionality to provide specific rules for your project. If you believe your rule should be added to the core library please submit a pull request. To add your extra rule you must call both addRule and setRuleMessage.

Simple extra rule

For example, if you wanted to add a rule that would validate that a timezone was valid:

// Add the rule to the validator
$validator = new Validator;
$validator->addRule('timezone', function (Validator $validator, array $data, $pattern, $rule) {
    foreach ($validator->getValues($data, $pattern) as $attribute => $value) {
        if (null === $value) {
            continue;
        }
        if (in_array($value, listTimezones())) {
            continue;
        }

        $validator->addError($attribute, $rule);
    }
});
$validator->setRuleMessage('timezone', ':attribute must be an timezone');


// Validate using the new rule
$rules = [
    'timezone' => 'present|timezone',
];
$validator->validate($_POST, $rules);

Extra rule with parameters

For example, if you wanted to add a rule that would validate that an identifier existed in your database:

// Add the rule to the validator
$validator = new Validator;
$validator->addRule('model-exists', function (Validator $validator, array $data, $pattern, $rule, $array $parameters) {
    // Connect to database
    $db = getDbInstance();
    list($model, $property) = $parameters;

    foreach ($validator->getValues($data, $pattern) as $attribute => $value) {
        if (null === $value) {
            continue;
        }
        if (doesModelExist($db, $model, $property, $value)) {
            continue;
        }

        $validator->addError($attribute, $rule, [
            ':model' => $model
        ]);
    }
});
$validator->setRuleMessage('model-exists', ':attribute must be an existing :model');


// Validate using the new rule
$rules = [
    'uuid' => 'required|model-exists:user,uuid',
];
$validator->validate($_POST, $rules);

Another example, if you wanted to do a complex validation of a sub-array:

// Add the rule to the validator
$validator = new Validator;
$validator->addRule('complex', function (Validator $validator, array $data, $pattern, $rule, $array $parameters) {
    foreach ($validator->getValues($data, $pattern) as $attribute => $value) {
        if (null === $value) {
            continue;
        }
        $rules['type'] = 'in:alpha,beta';
        switch ($value['type']) {
            case 'alpha':
                $rules['shared_field'] = 'is:int';
                $rules['alpha_specific_field'] = 'is:int';
                break;

            case 'beta':
                $rules['shared_field'] = 'in:blue,green';
                $rules['beta_specific_field'] = 'is:int';
                break;
        }

        // Apply the type specific rules to this part of the data
        $validator->validate($value, $rules, $attribute);
    }
});
// No need to define a rule message as only sub-rules can generate errors

Validation Rules

Present

The field must be present but can have any value including null.

// Example usage:
$rulesSet = [
    'field' => 'present',
];

Required

The field must be present and cannot be null (can be an empty string).

// Example Usage
$rulesSet = [
    'field' => 'required'
];

Required If

The field is required if the specified field(s) and the specified value(s).

// Example Usage
$rulesSet = [
    'field0' => 'required-if:field1:yes',
    'field1' => 'required|in:yes,no'
];

Required With

The field is required if the other field is not null.

// Example Usage
$rulesSet = [
    'field0' => 'required-with:field1',
    'field1' => 'required-with:field0'
];

Required With All

The field is required if all the other fields are not null.

// Example Usage
$rulesSet = [
    'field0' => 'required-with-all:field1,field2',
    'field1' => 'is:int'
    'field2' => 'in:alpha,beta'
];

Required With Any

The field is required if any of the other fields are not null.

// Example Usage
$rulesSet = [
    'field0' => 'required-with-any:field1,field2',
    'field1' => 'is:int'
    'field2' => 'in:alpha,beta'
];

Required Without

The field is required if the other field is null.

// Example Usage
$rulesSet = [
    'field0' => 'required-without:field1',
    'field1' => 'required-without:field0'
];

Equals

The field's value must be equal to the other specified field's value.

// Example Usage
$rulesSet = [
    'field0' => 'equals:field1',
    'field1' => 'required'
];

Not Equals

The field's value must not equal the other specified field's value.

// Example Usage
$rulesSet = [
    'field0' => 'not-equals:field1',
    'field1' => 'required'
];

Identical

The field's value must be identical the other specified field's value.

// Example Usage
$rulesSet = [
    'field0' => 'identical:field1',
    'field1' => 'required'
];

Not Identical

The field's value must not be identical the other specified field's value.

// Example Usage
$rulesSet = [
    'field0' => 'not-identical:field1',
    'field1' => 'required'
];

In

The field must equal one of the specified options.

// Example Usage
$rulesSet = [
    'field' => 'in:apple,pear,orange'
];

Not In

The field must not equal one of the specified options.

// Example Usage
$rulesSet = [
    'field' => 'not-in:apple,pear,orange'
];

Contains

The field should be an array and must contain all the specified options (may contain other values not listed).

// Example Usage
$rulesSet = [
    'field' => 'contains:apple,pear,orange'
];

Contains Only

The field should be an array and must contain only the specified options.

// Example Usage
$rulesSet = [
    'field' => 'contains-only:apple,pear,orange'
];

Min Array Count

The field should be an array and must have an array_count of at least the specified value.

// Example Usage
$rulesSet = [
    'field' => 'min-arr-count:1'
];

Max Array Count

The field should be an array and must have an array_count of at most the specified value.

// Example Usage
$rulesSet = [
    'field' => 'max-arr-count:5'
];

Min

The field should be numeric and must be at least the specified value.

// Example Usage
$rulesSet = [
    'field' => 'min:1'
];

Max

The field should be numeric and must be at most the specified value.

// Example Usage
$rulesSet = [
    'field' => 'max:5'
];

Greater Than

The field should be numeric and must have a value greater than the other field.

// Example Usage
$rulesSet = [
    'field0' => 'greater-than:field1'
];

Less Than

The field should be numeric and must have a value less than the other field.

// Example Usage
$rulesSet = [
    'field0' => 'less-than:field1'
];

Alpha

The field must only contain alphabetic characters.

// Example Usage
$rulesSet = [
    'field' => 'alpha'
];

Alpha Numeric

The field must only contain alphabetic and numerical characters.

// Example Usage
$rulesSet = [
    'field' => 'alpha-numeric'
];

Min String Length

The field should be string and must have a strlen of at least the specified value.

// Example Usage
$rulesSet = [
    'field' => 'min-str-len:3'
];

Max String Length

The field should be a string and must have a strlen of at most the specified value.

// Example Usage
$rulesSet = [
    'field' => 'max-str-len:50'
];

String Length

The field should be a string and must have a strlen of exactly the specified value.

// Example Usage
$rulesSet = [
    'field' => 'str-len:10'
];

Human Name

The field must be a valid human name.

// Example Usage
$rulesSet = [
    'field' => 'human-name'
];

Is ...

The field must be of the specified basic PHP type. There must be a corresponding is_<type> method.

// Example Usage
$rulesSet = [
    'field' => 'is:numeric' // any basic PHP type (must have corresponding is_<type> method)
];

Email

The field must be a valid email address

// Example Usage
$rulesSet = [
    'field' => 'email'
];

Date

The field must be a valid date in the specified format (defaults to 'Y-m-d').

// Example Usage
$rulesSet = [
    'field' => 'date' // defaults to 'Y-m-d'
];

URL

The field must be a valid URL.

// Example Usage
$rulesSet = [
    'field' => 'url'
];

UUID

The field must be a valid UUID (\universally unique identifier).

// Example Usage
$rulesSet = [
    'field' => 'uuid'
];

Card Number

The field must be a valid card number. See http://stackoverflow.com/questions/174730/what-is-the-best-way-to-validate-a-credit-card-in-php for more details.

// Example Usage
$rulesSet = [
    'field' => 'card-number'
];

Regex

The field must match the regex pattern provided as parameter. Specify rules in an array when using this rule, especially when the regex expression contains a | character. See https://www.php.net/preg_match for nore details.

// Example Usage
$rulesSet = [
    'field' => ['regex:/^[Ff]oobar[1!]+$/']
];

Not Regex

The field must not match the regex pattern provided as parameter. Specify rules in an array when using this rule, especially when the regex expression contains a | character. See https://www.php.net/preg_match for nore details.

// Example Usage
$rulesSet = [
    'field' => ['not-regex:/^[abc]{1,3}\W+$/i']
];

madesimple / php-form-validator

Maintainers

Details

README

Installation

Validation Rules

Adding Extra Rules

Simple extra rule

Extra rule with parameters

Validation Rules

Present

Required

Required If

Required With

Required With All

Required With Any

Required Without

Equals

Not Equals

Identical

Not Identical

In

Not In

Contains

Contains Only

Min Array Count

Max Array Count

Min

Max

Greater Than

Less Than

Alpha

Alpha Numeric

Min String Length

Max String Length

String Length

Human Name

Is ...

Email

Date

URL

UUID

Card Number

Regex

Not Regex