everest/validation

Everest - Validation Component

Everest - Validation Component

The Validation Component of Everest is ment to validate user input in a simple and intuitive way., _(*1)

Installing

Simply go to your project directory where the composer.json file is located and type:, _(*2)

    composer require everest/validation

Usage

This package offers two methods of data validation. You can either validate a single value on a specific requirement (type) or you can validate one or more validation chains on each key of an array or array like object., _(*3)

Validating single value

use Everest\Validation\Validation;

$int = Validation::integer('10'); // $int -> 10
$noint = Validation::integer('foo'); // Will throw \Everest\Validation\InvalidValidationException

Validating an array of values using a validation chain

use Everest\Validation\Validate;

$data = [
    'foo' => '10',
    'bar' => 'foo'
];

$data = Validate::lazy($data)
    ->that('foo')->integer()->between(0, 20)
    ->that('bar')->enum(['bar', 'foo'])->upperCase()
    ->execute();

// $data -> ['foo' => 10, 'bar' => 'FOO']

You can use additional validation chains by seperating them with ->or(), _(*4)

use Everest\Validation\Validate;

$data = [
    'bar' => 'foo'
];

$data = Validate::lazy($data)
    ->that('bar')->integer()->between(0, 20)
    ->or()->string()->minLength(2)
    ->execute();

// $data -> ['bar' => 'FOO']

Strict and lazy validation

One can choose between Validate::strict() and Validate::lazy(). First will throw an InvalidValidationException on the first occuring error and the last will collect all occuring errors and will throw a InvalidLazyValidationException, which provices a ::getErrors() and ::getErrorsGroupedByKey() method to access all bundled InvalidValidationException exceptions., _(*5)

Validating nested arrays

One can use dot-notation to validate nested values., _(*6)

use Everest\Validation\Validate;

$data = [
    'foo' => [
        ['bar' => 1, 'name' => 'Some name'],
        ['bar' => 2, 'name' => 'Some other name']
    ]
];

$data = Validate::lazy($data)
    ->that('foo.*.bar')->integer()->between(0, 20)
    ->that('foo.*.name')->string()->upperCase()
    ->execute();

// $data -> [
//   'foo' => [
//     ['bar' => 1, 'name' => 'SOME NAME'],
//     ['bar' => 2, 'name' => 'SOME OTHER NAME']
//   ]
// ]

Optional parameters

Parameters can be marked as optional and as optional with default. If the validation ueses a default value as fallback this value is NOT validated by the validation chain anymore!, _(*7)

use Everest\Validation\Validate;

$data = ['foo' => 10];

$result = Validate::lazy($data)
    ->that('foo')->integer()
    ->that('bar')->optional(/* no default */)->integer()
    ->execute();

// $result -> ['foo' => 10]

$result = Validate::lazy($data)
    ->that('foo')->integer()
    ->that('bar')->optional(null)->integer()
    ->execute();

// $result -> ['foo' => 10, 'bar' => null]

Types

Types are rules that a supplied value has to fulfill., _(*8)

Array

Validation::array($value), validates that given value is an array., _(*9)

Between

Validation::between($value, numeric $min, numeric $max), validates that given value holds $min <= $value <= $max., _(*10)

Boolean

Validation::boolean($value), validates that given value is a boolean or booleanish value. The result will be casted to a boolean. This type inteprets $value as follows:, _(*11)

Every other value will throw an InvalidValidationException., _(*12)

DateTime

Validation::dateTime($value, string $pattern), validates that given value matches the supplied date pattern and returns a new DateTime instance., _(*13)

DateTimeImmutable

Same as DateTime but returns a new DateTimeImmutable instance., _(*14)

Enum

Validation::dateTime($value, array $enum), validates that given value matches one of the $enum values. If $enum is an assoc array it tryes to match $value against the keys and returns the associated value., _(*15)

Float

Validation::float($value), validates that given value is numeric. The result will be casted to a float., _(*16)

Integer

Validation::integer($value), validates that given value is an integer or integerish. The result will be casted to an integer., _(*17)

KeyExists

Validation::keyExisits($value, $key), validates that given value is an array and that the supplied key exists in this array., _(*18)

Length

Validation::length($value, int $length), validates that given value matches the supplied string length using strlen., _(*19)

LengthBetween

Validation::lengthBetween($value, int $min, int $max), validates that given values string length is between supplied minimum and maximum., _(*20)

LengthMax

Validation::lengthMax($value, int $max), validates that given values string length lower or equal supplied maximum., _(*21)

LengthMin

Validation::lengthMin($value, int $min), validates that given values string length greater or equal supplied minimum., _(*22)

Max

Validation::max($value, int $max), validates that the given numerical value is lower or equal supplied maximum., _(*23)

Min

Validation::min($value, int $max), validates that the given numerical value is greater or equal supplied minimum., _(*24)

NotEmpty

Validation::notEmpty($value), validates that the given value is not empty., _(*25)

Null

Validation::null($value), validates that the given value is null., _(*26)

String

Validation::string($value), validates that the given value is a string., _(*27)

Filters

Filters can be used to transfrom the validated result., _(*28)

LowerCase

Validation::lowerCase($value), executes strtolower on the supplied value., _(*29)

StripTags

Validation::stripTags($value), executes strip_tags on the supplied value., _(*30)

Trim

Validation::trim($value), executes trim on the supplied value., _(*31)

UpperCase

Validation::upperCase($value), executes strtoupper on the supplied value., _(*32)

Custom Types

One can add custom types by creating a new class that extends from Everest\Validation\Types\Type., _(*33)

<?php

class CustomType extends \Everest\Validation\Types\Type {

    public static $errorName = 'invalid_custom_error';
    public static $errorMessage = '%s is not a valid custom type.';

    public function __invoke($value, $message = null, string $key = null, $customArg1 = null, $customArg2 = null)
    {
        if (/* Your invalid condition here */) {
            $message = sprintf(
                self::generateErrorMessage($message ?: self::$errorMessage),
                self::stringify($value)
            );

            throw new InvalidValidationException(self::$errorName, $message, $key, $value);
        }

        /**
         * You may transform/cast the result before retuning it.
         * In this case it is usefull to add a custom argument as 
         * `$doCast` = false flag
         */


        return $value;
    }
}

In the next step you need to connect your type with the Everest\Validation\Validation class., _(*34)

<?php

// Add as class. A singleton instance will be created when the type is requested the first time
\Everest\Validation\Validation::addType('custom_name', CustomType::CLASS);

// Add as instance. You can also supply a instance of your custom type. 
// E.g. when you need to do some configuration in `__construct()`
\Everest\Validation\Validation::addType('custom_name', new CustomType());

If you want to overload an existing type you need to pass true as third argument to \Everest\Validation\Validation::addType., _(*35)

Now you can use the custom type by Validation::custom_type($var) or in a validation chain with ->custom_type()., _(*36)

License

This project is licensed under the MIT License - see the LICENSE.md file for details, _(*37)