README

Validity is a simple validation and filtration package for PHP. It can be used to validate both single values like integers and strings, and complex nested structures, using however complex validation logic you can think of. Nice default errors messages in English or Russian. Easily extensible with a custom language package, with always having ability to provide a custom error message for any rule on every field.

Why?

The goal was simple: to have a reasonably small validation package that easily covers all my needs:

validating basic data types, without having to type a lot,
validating arrays, validating against complex logic,
validating values depending on other fields' values,
filtering of value
internationalization, nice error messages for all cases — out-of-the-box
ability to specify custom message for each and every case

Features

Basic field types: int, float, bool, string.
More advanced types: date, datetime, email, phone, enum.
Pattern validation.
User-supplied callback validation.
Validation of array values (f. e. array of checkboxes or text inputs). Precise error messages (ability to display the exact key on which the error happened). Messages are internally represented as objects containing array key information, if relevant. Every message is exported to JSON as {text: <string>, "key": <null or string or int>}
Validation of a compound field (field is an associative array).
Filtration with user-supplied callbacks.
Easy setting of limits (min/max) for numeric fields, date/datetime fields, setting min and max length for strings.
Marking a field as required. You can also specify a condition under which a certain field is required (i. e., when a user selects "University" as education level, University name field can be set as required).
Out-of-the-box English & Russian languages are at your disposal, containing default error messages for every case. You can easily create your own language class to use for default messages. At least for a boilerplate version of code those messages should work fine, without having to write a single message by hand.
Easy to override error messages for each and every validation rule: if you don't specify an error message, then a default one is selected from the language class. If a message is provided for a rule, that message is used.
When dealing with strings, potentially malicious unicode characters are not allowed, for better security.

Examples

A few examples can be found in the examples folder. The easiest way to see them is to let your web-server serve these scripts: I simply symlink the examples folder below my localhost's $root.

I will also provide an example right here:

use \validity\FieldSet, \validity\Field;

$name = Field::pattern("name", "/^[A-Z][a-zA-Z\- ]+$/")->setRequired();
$greeting = Field::enum("greeting", ["mr", "mrs"])->setRequired();
$subscriptions = Field::int("subscriptions")->setMin(1)->expectArray();
$email = Field::email("email")->setRequiredIf(
    function(FieldSet $fieldSet) {
        return (bool) $fieldSet->getFiltered("subscriptions");
    }
);
$dateOfBirth = Field::date("date_of_birth")->setMax("-18years")->setRequired();
$education = Field::string("education")
     ->setMinLength(10)
     ->setMaxLength(100)
     ->expectArray()
     ->setArrayMinLength(0)
     ->setArrayMaxLength(3)
     ->setArraySkipEmpty(true);

$fieldSet = (new FieldSet())
        ->add($name)
        ->add($greeting)
        ->add($subscriptions)
        ->add($email)
        ->add($dateOfBirth)
        ->add($education);

if ($fieldSet->isValid($_POST)) {
    $data = $fieldSet->getFiltered();
    // do something with $data
} else {
    // display errors summary
    echo $fieldSet->getErrors()->toString();
}

In this code example, no custom messages are used. Because the language is not specified for the FieldSet contrustor, the default language class (English) will be used to provide pretty neat error messages. However, for every call that specifies a validation rule, you may supply a custom message, and it will then override the one from language pack. Messages can be provided in form of a template. {label} is always replaced by the field's label.

Creating fields

Fields are created using named constructors:

Field::int(string $name = null, string $message = null),
Field::float(string $name = null, string $message = null),
Field::bool(string $name = null, string $message = null),
Field::string(string $name = null, string $message = null),
Field::date(string $name = null, string $message = null),
Field::datetime(string $name = null, string $message = null),
Field::enum(string $name = null, array $values, string $message = null),
Field::email(string $name = null, string $message = null),
Field::phone(string $name = null, string $message = null),
Field::pattern(string $name = null, string $pattern, string $message = null),
Field::assoc(string $name = null, FieldSet $innerFieldSet, $message = null, $errorSeparator = "; ").

Every named constructor return a Field of a corresponding type, most of them being pretty much self-explanating, with an exception of Assoc, which you can know more about in Validating compound values section.

In all cases, $message is used as error in case input cannot be interpreted as int, float etc.

Required fields

Field can be marked as required:

Field::string("username")->setRequired("Please enter username");

Sometimes, a field is only required in case some other fields are filled (or any other conditions are met).

Field::email("email")->setRequiredIf(
    function(FieldSet $fieldSet) {
        return (bool) $fieldSet->getFiltered("subscriptions");
    }
);

setRequiredIf() accepts either a boolean or a callback as argument. In first case, it simply marks the field as required or removes this mark. When a callable is used, it is evaluated in the process of validation, and the field is only considered as required if the callback returns TRUE. In the example above, the email field is required in case the user has chosen to subscribe to some mailing list.

Default values

Every field can be assigned a default value:

Field::int("price")->setDefault(100, true, false);

The two remaining arguments are $replaceEmpty and $replaceInvalid. In case $replaceEmpty is set to TRUE (default behavior), default value is used for the field in case no/empty value was specified in input. In case $replaceInvalid is set to TRUE (defaults to FALSE), then, should the input value fail any validation, it is replaced silently with the default, and no error is raised.

Simple constraints

Numeric fields (int & float), as well as Date/Datetime fields can be assigned minimum and maximum values:

Field::int("price")->setMin(1);
Field::date("date_of_birth")->setMax("-18years");

String values can be set to accept minumum and maximum string length:

Field::string("name")
    ->setMinLength(2)
    ->setMaxLength(100);

In case an array is expected, it can also be limited:

Field::string("education")
    ->setMaxLength(100)
    ->expectArray()
    ->setArrayMinLength(0)
    ->setArrayMaxLength(3)

In the last case, setMaxLength(100) limits the length of every string in the education array, while setArrayMinLength() and setArrayMaxLength() set the limits for the array size (so we expect from 0 to 3 entries in education, each entry being a string with a maximum length of 100 chars).

Callbacks as validators

This is the most powerful validation:

Field::string("username")
    ->addCallbackRule(
        function($value, FieldSet $fieldSet) {
            return !Users::usernameExists($value);
        }
    );

When the callback is called, it is passed 3 arguments:

$value — obviously, the value to be validated;
$fieldSet — the FieldSet instance, so that it's possible to get values of neighboring fields;
$key — in case the field expects an array value, then an integer or a string key of the array element is passed (defaults to NULL).

The callback should return boolean: TRUE if the validation passes, FALSE if it fails.

Dates

Date and datetime fields will transform the input value to a formatted date, so when you finally call getFiltered(), they will contain string dates, formatted according to output format setting (Y-m-d by default for date and Y-m-d H:i:s for datetime fields). You may alter this format setOutputFormat(). By default, Date and Datetime fields expect the input to strictly follow format set by setInputFormat(), and this input format also defaults to Y-m-d or Y-m-d H:i:s. However, setInputFormat() accepts the second optional argument — $strict. Setting it to false will cause the validator to try first the exact input format but then to try php's date_create(). Be careful with using non-strict date formats, because it might be very confusing. For example, values like "+1year" or "16 years ago march 1st" will be valid dates. Moreover, values like "2010-02-31", which is obviously an invalid date, will pass validation! In the latter case, the resulting value will be (surprise!) 2010-03-03. More on this in PHP manual — read comment by thomas dot ribiere at allgoob dot com.

Validating arrays

Any field can be set to expect an array value:

Field::int("subscriptions")->expectArray();

In this case, the field is expected to be array of elements, each of those validated against type (int in the example above) and any of the rules that you specify. Minimum and maximum array length can be controlled with:

setArrayMinLength(int)
setArrayMaxLength(int)

In case some of the array elements fail validation, it might be handy to see what particular elements failed. Consider the following example:

Field::int("subscriptions", "{label}: value #{key} is not an integer")
    ->setMin(1, "Subscriptions: value #{key} must be greater then or equal to {min}")
    ->expectArray()
    ->setArrayKeyOffset(1);

Let's say we have the following dataset:

{
  "subscriptions": [
    1,
    "not an integer",
    -1
  ]
}

Then we will have the following error messages:

subscriptions: value #2 is not an integer"
subscriptions: value #3 must be greater then or equal to {min}"

The message parser will replace "{key}" with the corresponding array key. Numeric arrays in PHP are zero-indexed, so by default, in case of an error on the first array element, you get an error message saying "value #0 is invalid". While this might be a desired behavior, you also might want this to be displayed as "value #1 is invalid". This is achieved by calling Field::setArrayKeyOffset(1) - then all the keys are incremented by 1 in the error messages. It is also often the case that integer IDs are used as keys for various data, so by default validity does not apply an offset to numeric keys.

Validating compound values

Assoc (Field::assoc()) is a compound field, so FieldSet will expect the value to be an array, which it will validate with a help of $innerFieldSet. A real-life example: set of three fields used to make up a date input: date[year], date[month], date[day]. Let's suppose that we expect $_POST["date"] to be array(year: integer, month: integer, day: integer) In this case, $innerFieldSet will contain fields, created with Field::int() and named year, month and day, each having proper range validation: setMax() and setMin(). $message parameter to Field::assoc() will only be used in case when $_POST["date"] is not an array. If it is an array, then the $innerFieldSet will take care of further validation. Should the $innerFieldSet report any errors, they will all be combined into a string and used as an error message for the date field in the outer FieldSet.

Tips & tricks

Are you using Zend Framework but still want to use validity? Good news for you! Zend Validators are callable, so you can simply add them as validation rules:

Field::string("email")->addCallbakRule(new EmailAddress(), "Email is invalid!");

Are you using Yii2 but still want to use validity? It's just a tiny bit more complicated then in case of ZF:

Field::string("email")->addCallbakRule(function($value) {
    return (new EmailValidator())->validate($value);
}, "Email is invalid!");

I chose email validation for this tips on purpose. Validity also offers email validation, but (at least for now) it is a simple regexp check. Zend or Yii2 offer much more sophisticated ways to validate an email, and you can simply use it while at the same time performing routines validity-style.

Labels

Every field must have a name. Name is the first parameter to all the named constructors. Name is essentially the key of the associative array the FieldSet will validate. In addition, field can also have a label. For example, field name is date_of_birth but label is Date of birth. Label can be set with Field->setLabel(string $label). If not set, field name is used as label.

crocodile2u / validity

Maintainers

Details