Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/master'
Browse files Browse the repository at this point in the history
  • Loading branch information
@minwork
minwork committed Apr 21, 2020
2 parents 42e97a5 + 2adf0d4 commit cc85332
Showing 1 changed file with 116 additions and 10 deletions.
126 changes: 116 additions & 10 deletions docs/validating-array/check.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

<table>
<thead>
<tr>
<th style="text-align:left"><code>$condition</code> type</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>callable</code>
</td>
<td style="text-align:left">
<p><em>Callable </em>should return truthy or falsy value (while using <code>CHECK_STRICT</code> flag,
return values other than <code>true</code> are treated as <code>false</code>).</p>
<p></p>
<p><em>Callable</em> is supplied with either only element value (<code>function($value)</code>)
or pair of element value and key (<code>function($value, $key)</code>)
as arguments.
<br />Arguments amount depend on <em>callable </em>definition and is dynamically
resolved using <a href="https://www.php.net/manual/en/reflectionfunctionabstract.getnumberofparameters.php">reflection</a> (defaults
to 2 - value and key)</p>
</td>
</tr>
<tr>
<td style="text-align:left"><code>mixed</code>
</td>
<td style="text-align:left">
<p>If <em>condition</em> type is different than <code>callable</code> then every
array element is compared against it value.</p>
<p></p>
<p><code>$value == $condition</code> by default</p>
<p><code>$value === $condition</code>if <code>CHECK_STRICT</code> flag is enabled</p>
</td>
</tr>
</tbody>
</table>#### 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 %}

<table>
<thead>
<tr>
<th style="text-align:left">Constant name</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>CHECK_STRICT</code>
</td>
<td style="text-align:left">
<p>In case <em>condition</em> is <code>callable</code> check if it result is
exactly <code>true</code>
</p>
<p>
<br />If <em>condition</em> is not <code>callable</code>, then check if array element
is equal to it both by value and type</p>
<p></p>
<p>See <b>Condition</b> section for more info</p>
</td>
</tr>
<tr>
<td style="text-align:left"><code>CHECK_SOME</code>
</td>
<td style="text-align:left">
<p>Check will return <code>true</code> on first array element that match specified <em>condition</em> or
false if none of them matches it.</p>
<p></p>
<p>By default <code>check</code> method will return <code>true</code> only if
ALL of array elements meet specified <em>condition</em>
</p>
</td>
</tr>
</tbody>
</table>#### 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
```

0 comments on commit cc85332

Please sign in to comment.