Rename "IterableType" into "IterableVal"

When we created this rule in version 1.0 in 2015, PHP was in version 5.6, and the `is_iterable()` function didn't exist. Only in version 7.1, released at the end of 2016, was the pseudo-type "iterable" introduced to PHP. This old "IterableType" rule is almost obsolete. Still, I decided to keep it because it is possible to use foreach in any object, as it will iterate over its public properties. I did rename the rule because that makes more sense. An "IterableType" rule should guarantee that the input type is the real-(pseudo)-iterable. Signed-off-by: Henrique Moody <[email protected]>
Respect · Feb 29, 2024 · 980ab28 · 980ab28
1 parent 471e147
commit 980ab28
Show file tree

Hide file tree

Showing 14 changed files with 76 additions and 70 deletions.
diff --git a/docs/08-list-of-rules-by-category.md b/docs/08-list-of-rules-by-category.md
@@ -263,7 +263,7 @@
 - [FloatVal](rules/FloatVal.md)
 - [IntType](rules/IntType.md)
 - [IntVal](rules/IntVal.md)
-- [IterableType](rules/IterableType.md)
+- [IterableVal](rules/IterableVal.md)
 - [NullType](rules/NullType.md)
 - [NumericVal](rules/NumericVal.md)
 - [ObjectType](rules/ObjectType.md)
@@ -342,7 +342,7 @@
 - [IntVal](rules/IntVal.md)
 - [Ip](rules/Ip.md)
 - [Isbn](rules/Isbn.md)
-- [IterableType](rules/IterableType.md)
+- [IterableVal](rules/IterableVal.md)
 - [Json](rules/Json.md)
 - [Key](rules/Key.md)
 - [KeyNested](rules/KeyNested.md)

diff --git a/docs/rules/ArrayType.md b/docs/rules/ArrayType.md
@@ -30,7 +30,7 @@ See also:
 - [Countable](Countable.md)
 - [FloatType](FloatType.md)
 - [IntType](IntType.md)
-- [IterableType](IterableType.md)
+- [IterableVal](IterableVal.md)
 - [NullType](NullType.md)
 - [ObjectType](ObjectType.md)
 - [ResourceType](ResourceType.md)

diff --git a/docs/rules/ArrayVal.md b/docs/rules/ArrayVal.md
@@ -32,7 +32,7 @@ See also:
 - [ArrayType](ArrayType.md)
 - [Countable](Countable.md)
 - [Each](Each.md)
-- [IterableType](IterableType.md)
+- [IterableVal](IterableVal.md)
 - [Key](Key.md)
 - [KeySet](KeySet.md)
 - [ScalarVal](ScalarVal.md)

diff --git a/docs/rules/Countable.md b/docs/rules/Countable.md
@@ -27,4 +27,4 @@ See also:
 - [ArrayType](ArrayType.md)
 - [ArrayVal](ArrayVal.md)
 - [Instance](Instance.md)
-- [IterableType](IterableType.md)
+- [IterableVal](IterableVal.md)
diff --git a/docs/rules/Each.md b/docs/rules/Each.md
@@ -21,7 +21,7 @@ v::call('array_keys', v::each(v::stringType()))->validate($releaseDates); // tru
 ```
 
 This rule will not validate values that are not iterable, to have a more detailed
-error message, add [IterableType](IterableType.md) to your chain, for example.
+error message, add [IterableVal](IterableVal.md) to your chain, for example.
 
 If the input is empty this rule will consider the value as valid, you use
 [NotEmpty](NotEmpty.md) if convenient:
@@ -49,7 +49,7 @@ See also:
 
 - [ArrayVal](ArrayVal.md)
 - [Call](Call.md)
-- [IterableType](IterableType.md)
+- [IterableVal](IterableVal.md)
 - [Key](Key.md)
 - [NotEmpty](NotEmpty.md)
 - [Unique](Unique.md)
diff --git a/docs/rules/Instance.md b/docs/rules/Instance.md
@@ -25,6 +25,6 @@ Version | Description
 See also:
 
 - [Countable](Countable.md)
-- [IterableType](IterableType.md)
+- [IterableVal](IterableVal.md)
 - [ObjectType](ObjectType.md)
 - [Type](Type.md)
diff --git a/docs/rules/IterableType.md b/docs/rules/IterableType.md
diff --git a/docs/rules/IterableVal.md b/docs/rules/IterableVal.md
@@ -0,0 +1,40 @@
+# IterableVal
+
+- `IterableVal()`
+
+Validates whether the input is an iterable value, in other words,  if you can iterate over it with the [foreach][] language construct.
+
+```php
+v::iterableVal()->validate([]); // true
+v::iterableVal()->validate(new ArrayObject()); // true
+v::iterableVal()->validate(new stdClass()); // true
+v::iterableVal()->validate('string'); // false
+```
+
+## Note
+
+This rule doesn't behave as PHP's [is_iterable() function because it considers that you can iterate over any object.
+
+## Categorization
+
+- Types
+
+## Changelog
+
+|  Version | Description                                  |
+|---------:|----------------------------------------------|
+|    3.0.0 | Renamed from `IterableType` to `IterableVal` |
+|    1.0.8 | Renamed from `Iterable` to `IterableType`    |
+|    1.0.0 | Created as `Iterable`                        |
+
+***
+See also:
+
+- [ArrayType](ArrayType.md)
+- [ArrayVal](ArrayVal.md)
+- [Countable](Countable.md)
+- [Each](Each.md)
+- [Instance](Instance.md)
+
+[is_iterable()]: https://www.php.net/is_iterable
+[foreach]: http://php.net/foreach
diff --git a/library/ChainedValidator.php b/library/ChainedValidator.php
@@ -157,7 +157,7 @@ public function ip(string $range = '*', ?int $options = null): ChainedValidator;
 
     public function isbn(): ChainedValidator;
 
-    public function iterableType(): ChainedValidator;
+    public function iterableVal(): ChainedValidator;
 
     public function json(): ChainedValidator;
 

diff --git a/library/Rules/IterableType.php → library/Rules/IterableVal.php b/library/Rules/IterableType.php → library/Rules/IterableVal.php
@@ -16,7 +16,7 @@
     '{{name}} must be iterable',
     '{{name}} must not be iterable',
 )]
-final class IterableType extends Simple
+final class IterableVal extends Simple
 {
     use CanValidateIterable;
 

diff --git a/library/StaticValidator.php b/library/StaticValidator.php
@@ -159,7 +159,7 @@ public static function ip(string $range = '*', ?int $options = null): ChainedVal
 
     public static function isbn(): ChainedValidator;
 
-    public static function iterableType(): ChainedValidator;
+    public static function iterableVal(): ChainedValidator;
 
     public static function json(): ChainedValidator;
 

diff --git a/tests/integration/rules/iterableType.phpt b/tests/integration/rules/iterableType.phpt
diff --git a/tests/integration/rules/iterableVal.phpt b/tests/integration/rules/iterableVal.phpt
@@ -0,0 +1,19 @@
+--FILE--
+<?php
+
+declare(strict_types=1);
+
+require 'vendor/autoload.php';
+
+use Respect\Validation\Validator as v;
+
+exceptionMessage(static fn() => v::iterableVal()->check(3));
+exceptionMessage(static fn() => v::not(v::iterableVal())->check([2, 3]));
+exceptionFullMessage(static fn() => v::iterableVal()->assert('String'));
+exceptionFullMessage(static fn() => v::not(v::iterableVal())->assert(new stdClass()));
+?>
+--EXPECT--
+3 must be iterable
+`[2, 3]` must not be iterable
+- "String" must be iterable
+- `stdClass {}` must not be iterable
diff --git a/tests/unit/Rules/IterableTypeTest.php → tests/unit/Rules/IterableValTest.php b/tests/unit/Rules/IterableTypeTest.php → tests/unit/Rules/IterableValTest.php
@@ -16,13 +16,13 @@
 use stdClass;
 
 #[Group('rule')]
-#[CoversClass(IterableType::class)]
-final class IterableTypeTest extends RuleTestCase
+#[CoversClass(IterableVal::class)]
+final class IterableValTest extends RuleTestCase
 {
-    /** @return iterable<array{IterableType, mixed}> */
+    /** @return iterable<array{IterableVal, mixed}> */
     public static function providerForValidInput(): iterable
     {
-        $rule = new IterableType();
+        $rule = new IterableVal();
 
         return [
             [$rule, [1, 2, 3]],
@@ -31,10 +31,10 @@ public static function providerForValidInput(): iterable
         ];
     }
 
-    /** @return iterable<array{IterableType, mixed}> */
+    /** @return iterable<array{IterableVal, mixed}> */
     public static function providerForInvalidInput(): iterable
     {
-        $rule = new IterableType();
+        $rule = new IterableVal();
 
         return [
             [$rule, 3],