README

PASVL - PHP Array Structure Validation Library

Think of a regular expression [ab]+ which matches a string abab. Now imaging the same for arrays.

The purpose of this library is to validate an existing (nested) array against a template and report a mismatch. It has the object-oriented extendable architecture to write and add custom validators.

Note to current users: this version is not backwards compatible with the previous 0.5.6.

Installation

composer require lezhnev74/pasvl

Example

Refer to files in Example folder.

Usage

Array Validation

// Define the pattern of the data, define keys and values separately
$pattern = [
    '*' => [
        'type' => 'book',
        'title' => ':string :contains("book")',
        'chapters' => [
            ':string :len(2) {1,3}' => [
                'title' => ':string',
                ':exact("interesting") ?' => ':bool',
            ],
        ],
    ],
];

// Provide the data to match against the above pattern.
$data = [
    [
        'type' => 'book',
        'title' => 'Geography book',
        'chapters' => [
            'eu' => ['title' => 'Europe', 'interesting' => true],
            'as' => ['title' => 'America', 'interesting' => false],
        ],
    ],
    [
        'type' => 'book',
        'title' => 'Foreign languages book',
        'chapters' => [
            'de' => ['title' => 'Deutsch'],
        ],
    ],
];

$builder = \PASVL\Validation\ValidatorBuilder::forArray($pattern);
$validator = $builder->build();
try {
    $validator->validate($data);
} catch (ArrayFailedValidation $e) {
    // If data cannot be matched against the pattern, then exception is thrown.
    // It is not always easy to detect why the data failed matching, the exception MAY sometimes give you extra hints.
    echo "failed: " . $e->getMessage() . "\n";
}

Optional String Validation

$pattern = ":string :regexp('#^[ab]+$#')";
$builder = \PASVL\Validation\ValidatorBuilder::forString($pattern);
$validator = $builder->build();
$validator->validate("abab"); // the string is valid
$validator->validate("abc"); // throws RuleFailed exception with the message: "string does not match regular expression ^[ab]+$"

Validation Language

This package supports a special dialect for validation specification. It looks like this:

Short language reference:

• Rule Name Specify zero or one Rule Name to apply to the data. Optinal postfix ? allows data to be null. Refer to the set of built-in rules in src/Validation/Rules/Library. For custom rules read below under Custom Rules. For example, :string? describes strings and null.

• Sub-Rule Name Specify zero or more Sub-Rule Names to apply to the data AFTER the Rule is applied. Sub Rules are extra methods of the main Rule. For example, :number :float describes floats.

• Quantifier Specify quantity expectations for data keys. If none is set then default is assumed - !. Available quantifiers:

  • ! - one key required (default)
  • ? - optional key
  • * - any count of keys
  • {2} - strict keys count
  • {2,4} - range of keys count

  For example:

    $pattern = [":string *" => ":number"];
    // the above pattern matches data:
    $data = ["june"=>10, "aug" => "11"];

Pattern Definitions

• as exact value

  $pattern = ["name" => ":any"]; // here the key is the exact value
  $pattern = ["name?" => ":any"]; // here the key is the exact value, can be absent as well
  $pattern = [":exact('name')" => ":any"]; // this is the same

• as nullable rule

  $pattern = ["name" => ":string?"]; // the value must be a string or null

• as rule with subrules

  $pattern = ["name" => ":string :regexp('#\d*#')"]; // the value must be a string which contains only digits

• as rule with quantifiers

  $pattern = [":string {2}" => ":any"]; // data must have exactly two string keys

Compound Definitions

This package supports combinations of rules, expressed in a natural language. Examples:

• :string or :number
• :string and :number
• (:string and :number) or :array

There are two combination operators: and, or. and operator has precedence. Both are left-associative.

Custom Rules

By default, the system uses only the built-in rules. However you can extend them with your own implementations. To add new custom rules, follow these steps:

• implement your new rule as a class and extend it from \PASVL\Validation\Rules\Rule
• implement a new rule locator by extending a class \PASVL\Validation\Rules\RuleLocator
• configure your validator like this:

  $builder = ValidatorBuilder::forArray($pattern)->withLocator(new MyLocator()); // set your new locator
  $validator = $builder->build();

Built-in Rules

This package comes with a few built-in rules and their corresponding sub-rules (see in folder src/Validation/Rules/Library):

• :string - the value must be string
  • :regexp(<string>) - provide a regular expression(the same as for preg_match())
  • :url
  • :email
  • :uuid
  • :contains(<string>)
  • :starts(<string>)
  • :ends(<string>)
  • :in(<string>,<string>,...)
  • :len(<int>)
  • :max(<int>)
  • :min(<int>)
  • :between(<int>,<int>)
• :number
  • :max(<int>)
  • :min(<int>)
  • :between(<int>, <int>)
  • :int - the number must be an integer
  • :float - the number must be a float
  • :positive
  • :negative
  • :in(<a>,<b>,<c>) - the number must be within values (type coercion possible)
  • :inStrict(<a>,<b>,<c>) - the number must be within values (type coercion disabled)
• :exact(<value>)
• :bool(<?value>) - the value must be boolean, if optional argument is given the value must be exactly it
• :object
  • :instance(<fqcn>)
  • :propertyExists(<string>)
  • :methodExists(<string>)
• :array
  • :count(<int>)
  • :keys(<string>,<string>,...)
  • :min(<int>) - min count
  • :max(<int>) - max count
  • :between(<int>, <int>) - count must be within
• :any - a placeholder, any value will match

Hints

• PHP casts "1" to 1 for array keys:

  $data = ["12" => ""];
  $pattern_invalid = [":string" => ""];
  $pattern_valid = [":number :int" => ""];

• Technically speaking PASVL is a non-deterministic backtracking parser, and thus it can't always show you what exact key did not match the pattern. That is because, say, a key can match different patterns and there is no way of knowing which one was meant to be correct. In such cases it returns a message like "no matches found at X level".

🏆 Contributors

• Greg Corrigan. Greg spotted a problem with nullable values reported as invalid.
• Henry Combrinck. Henry tested the library extensively on real data and found tricky bugs and edge cases. Awesome contribution to make the package valuable to the community.
• @Averor. Found a bug in parentheses parsing.
• Julien Gidel. Improved regexp sub-rule.

License

This project is licensed under the terms of the MIT license.