README

Table of contents

• Installation
• Available constraints
• Additional constraint packs
• Constraints
• Constraint groups
• Validator
• Validation result and validation errors
• Composing a custom validator
• Creating a custom validator class
• Custom constraints
• Wildcard validation
• Property accessors
  • Array accessor
  • Object accessor
  • Getter accessor
• Contributing constraints

Installation

composer require weew/validator

Available constraints

• Accepted
• Allowed
• AllowedSubset
• Alpha
• AlphaNumeric
• Array
• Boolean
• DomainName
• Email
• Equals
• Float
• Forbidden
• ForbiddenSubset
• Integer
• IP
• IPv4
• IPv6
• Length
• MaxAddress
• Max
• MaxLength
• Min
• MinLength
• MinMax
• MinMaxLength
• NotEmpty
• NotNull
• Nullable
• Null
• Numeric
• Regex
• Scalar
• String
• Url

Additional constraint packs

There are additional constraints that you may load trough composer.

• weew/validator-doctrine-constraints

Constraints

Constraints are small pieces of validation logic. A constraint can be used on its own, without the validator.

$constraint = new EmailConstraint();
// or
$constraint = new EmailConstraint('Custom error message.');
$check = $constraint->check('foo@bar.baz');

if ($check) {
    // valdiation passed
} else {
    echo $constraint->getMessage();
}

Constraint groups

Constraint groups allows you to configure multiple constraints for a single value.

$group = new ConstraintGroup('email', [
    new EmailConstraint(),
]);
// or
$group = new ConstraintGroup('email');
$group->addConstraint(new EmailConstraint());

Constraint groups can be used to validate data without the validator. The check method returns a ValidationResult object.

$result = $group->check('foo@bar.baz');

Validator

The easiest way to use the validator is by creating a new instance and adding constraints inline. Validator will return a ValidationResult object.

$validator = new Validator();
$data = ['username' => 'foo', 'email' => 'foo@bar.baz'];

$result = $validator->check($data, [
    new ConstraintGroup('email', [
        new EmailConstraint(),
    ]),
]);

Validation result and validation errors

Validation result is used to group occurring validation errors. Validation errors hold information about the validated properties, their values and the applied constraints.

if ($result->isFailed()) {
    foreach ($result->getErrors() as $error) {
        // $error->getSubject()
        // $error->getValue()
        // $error->getMessage()
        // $error->getConstraint()
    }
}

Composing a custom validator

You can compose a validator with predefined constraints that will be applied on each validation.

$data = ['username' => 'foo', 'email' => 'foo@bar.baz'];
$validator->addConstraint('email', new EmailConstraint());
$validator->addConstraints('username', [
    new AlphaConstraint(),
    new MinMaxLengthConstraint(3, 20),
]);

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

Creating a custom validator class

Configuring validators inline is not always the best solution. Sometimes you might want to create dedicated validator classes. With this library this is very easy to achieve.

class UserProfileValidator extends Validator {
    protected function configure() {
        $this->addConstraint('email', new EmailConstraint());
        $this->addConstraints('username', [
            new AlphaConstraint(),
            new MinMaxLengthConstraint(3, 20),
        ]);
    }
}

$data = ['username' => 'foo', 'email' => 'foo@bar.baz'];
$validator = new UserProfileValidator();
$result = $validator->check($data);

Custom constraints

Creating a new constraint is a fairly easy task. All you have to do is to implement the IConstraint interface. This is an example on how to create a simple constraint that makes sure that a number is within the given range.

class MinMaxConstraint implements IConstraint {
    protected $min;
    protected $max;
    protected $message;

    public function __construct($min, $max, $message = null) {
        $this->min = $min;
        $this->max = $max;
        $this->message = $message;
    }

    public function check($value, IValidationData $data = null) {
        if (is_numeric($value)) {
            return $value >= $this->min && $value <= $this->max;
        }

        return false;
    }

    public function getMessage() {
        if ($this->message !== null) {
            return $this->message;
        }

        return 'Some default error message.';
    }

    public function getOptions() {
        return [
            'min' => $this->min,
            'max' => $this->max,
        ];
    }
}

Wildcard validation

Imagine you have a similar structure that you want to validate.

$input = [
    'items' => [
        ['name' => 'name1'],
        ['name' => null],
        ['name' => 'name3'],
    ],
];

In order to validate the name property of every single element inside the items array, you would have to iterate over the items manually. You could also use a wildcard to target all the values. To wildcard array values, you can use this special character *.

$result = $validator->addConstraint('items.*.name', new NotNullConstraint());

In the example above, result will hold an error with subject items.1.name.

Array keys can also be validated using wildcards. You'll have to use a different wildcard character #. Be aware that the # wildcard character should always be the last path segment. This is wrong foo.#.bar, this is ok foo.bar.#.

$input = [
    'items' => [
        'name1' => 'value1',
        '2' => 'value2',
        'name3' => 'value3',
    ],
];

$result = $validator->addConstraint('items.#', new MinMaxLengthConstraint(3, 5));

Result will contain an error with subject #items.1. As you see, there is a # prefix in front of subjects for wildcard keys. This way you can differentiate between subjects for values and subjects for keys.

Property accessors

Validator comes with support for multiple data types.

Array accessor

This accessor adds support for array based data sets.

$data = ['email' => 'foo@bar.baz'];
$validator->check($data);

Object accessor

This accessor adds support for object based data sets.

$data = new stdClass();
$data->email = 'foo@bar.baz';
$validator->check($data);

Getter accessor

This accessor adds support for objects that only allow to access data over getter methods.

class User {
    protected $username;
    public function __construct($username) {
        $this->username = $username;
    }
    public function getUsername() {
        return $this->username;
    }
}

$validator->check(new User('foo'));