diff --git a/docs/validating-array/check.md b/docs/validating-array/check.md index f0274ec..2ff0228 100644 --- a/docs/validating-array/check.md +++ b/docs/validating-array/check.md @@ -4,32 +4,138 @@ {% code title="" %} ```php -Arr::check(array $array, mixed|callable $condition, bool $strict = false): bool +Arr::check(array $array, mixed|callable $condition, int $flag = 0): bool ``` {% endcode %} #### Description -Check if every element of an array meets specified condition. +Check if some or every array element meets specified condition. -#### Examples +If `CHECK_SOME` flag is NOT present then every array element must meet specified condition in order to pass check. + +#### Condition + + + + + + + + + + + + + + + + + + +
$condition typeDescription
callable + +

Callable should return truthy or falsy value (while using CHECK_STRICT flag, + return values other than true are treated as false).

+

+

Callable is supplied with either only element value (function($value)) + or pair of element value and key (function($value, $key)) + as arguments. +
Arguments amount depend on callable definition and is dynamically + resolved using reflection (defaults + to 2 - value and key)

+
mixed + +

If condition type is different than callable then every + array element is compared against it value.

+

+

$value == $condition by default

+

$value === $conditionif CHECK_STRICT flag is enabled

+
#### Flags + +Can be used as stand alone \(i.e.`Arr::CHECK_STRICT`\) as well as in conjunction \(i.e. `Arr::CHECK_STRICT | Arr::CHECK_SOME`\) + +{% hint style="info" %} +`$flag` argument used to be a boolean parameter called `$strict` + +But do not worry, it it is fully backward compatible due to in-flight type conversion from `bool` to `int` +{% endhint %} + + + + + + + + + + + + + + + + + + +
Constant nameDescription
CHECK_STRICT + +

In case condition is callable check if it result is + exactly true +

+

+
If condition is not callable, then check if array element + is equal to it both by value and type

+

+

See Condition section for more info

+
CHECK_SOME + +

Check will return true on first array element that match specified condition or + false if none of them matches it.

+

+

By default check method will return true only if + ALL of array elements meet specified condition +

+
#### Examples ```php -$array = [1, 1, 1]; +$array = [1, '1', true]; +// Every array element is EQUAL to 1 ($value == '1') Arr::check($array, '1') -> true -Arr::check($array, '1', true) -> false +// Only one array element is the SAME as 1 ($value === '1') which is not sufficient +Arr::check($array, '1', Arr::CHECK_STRICT) -> false -Arr::check($array, 'is_int') -> true +// When CHECK_SOME flag is present, one element is sufficient to pass check +Arr::check($array, '1', Arr::CHECK_STRICT | Arr::CHECK_SOME) -> true +// You can also use built-in functions to validate whole array +Arr::check($array, 'is_int') -> false Arr::check($array, 'is_string') -> false -Arr::check($array, function ($value) { return $value; }) -> false +// When CHECK_SOME flag is present only one element need to meet specified condition +Arr::check($array, 'is_int', Arr::CHECK_SOME) -> true +Arr::check($array, 'is_string', Arr::CHECK_SOME) -> true + +// Every value of array is truthy +Arr::check($array, function ($value) { return $value; }) -> true +// Above check can be simplified to +Arr::check($array, true) -> true +// Or even shorter +Arr::check($array, 1) -> true + +// When CHECK_STRICT flag is present, check will fail for callback return values other true +Arr::check($array, function ($value) { return $value; }, Arr::CHECK_STRICT) -> false +// But when callback is written as follows check will pass +Arr::check($array, function ($value) { return boolval($value); }, Arr::CHECK_STRICT) -> true +// Above check will pass if we add CHECK_SOME flag cause of of the elements is exactly true +Arr::check($array, function ($value) { return $value; }, Arr::CHECK_STRICT | Arr::CHECK_SOME) -> true -// In case of callback supplied as condition, strict flag checks if return value is exactly true -Arr::check($array, function ($value) { return $value; }, true) -> false -Arr::check($array, function ($value) { return $value === 1; }, true) -> true +// Callback function arguments count is automatically detected +Arr::check($array, function ($value, $key) { return $value > $key; }) -> false +// First array element 1 is greater than its key 0 +Arr::check($array, function ($value, $key) { return $value > $key; }, Arr::CHECK_SOME) -> true ```