weew/validator

Simple validation library.

PHP Validator

, _(*1)

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, _(*2)

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., _(*3)

• weew/validator-doctrine-constraints

Constraints

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

$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., _(*5)

$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., _(*6)

$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., _(*7)

$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., _(*8)

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., _(*9)

$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., _(*10)

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., _(*11)

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., _(*12)

$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 *., _(*13)

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

In the example above, result will hold an error with subject items.1.name., _(*14)

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.#., _(*15)

$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., _(*16)

Property accessors

Validator comes with support for multiple data types., _(*17)

Array accessor

This accessor adds support for array based data sets., _(*18)

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

Object accessor

This accessor adds support for object based data sets., _(*19)

$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., _(*20)

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

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