Create "Iterable" rule

CHANGELOG.md

@@ -19,6 +19,7 @@ All notable changes of the Respect\Validation releases are documented in this fi
 - Create "Identical" rule (#442)
 - Create "Infinite" rule (#397)
 - Create "IntType" rule (#451)
+- Create "Iterable" rule (#570)
 - Create "KeyNested" rule (#429)
 - Create "KeySet" rule (#374)
 - Create "KeyValue" rule (#441)

docs/Countable.md

@@ -15,3 +15,5 @@ v::countable()->validate('string'); // false
 See also:
 
   * [ArrayVal](ArrayVal.md)
+  * [Instance](Instance.md)
+  * [Iterable](Iterable.md)

docs/Iterable.md

@@ -0,0 +1,20 @@
+# Iterable
+
+- `v::iterable()`
+
+Validates if the input is iterable, in other words, if you're able to iterate
+over it with [foreach](http://php.net/foreach) language construct.
+
+```php
+v::iterable()->validate([]); // true
+v::iterable()->validate(new ArrayObject()); // true
+v::iterable()->validate(new stdClass()); // true
+v::iterable()->validate('string'); // false
+```
+
+***
+See also:
+
+  * [ArrayVal](ArrayVal.md)
+  * [Countable](Countable.md)
+  * [Instance](Instance.md)

docs/VALIDATORS.md

@@ -13,6 +13,7 @@
   * [Instance](Instance.md)
   * [IntVal](IntVal.md)
   * [IntType](IntType.md)
+  * [Iterable](Iterable.md)
   * [NullType](NullType.md)
   * [Numeric](Numeric.md)
   * [ObjectType](ObjectType.md)
@@ -241,6 +242,7 @@
   * [IntVal](IntVal.md)
   * [IntType](IntType.md)
   * [Ip](Ip.md)
+  * [Iterable](Iterable.md)
   * [Json](Json.md)
   * [Key](Key.md)
   * [KeyNested](KeyNested.md)

library/Exceptions/IterableException.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of Respect/Validation.
+ *
+ * (c) Alexandre Gomes Gaigalas <alexandre@gaigalas.net>
+ *
+ * For the full copyright and license information, please view the "LICENSE.md"
+ * file that was distributed with this source code.
+ */
+
+namespace Respect\Validation\Exceptions;
+
+class IterableException extends ValidationException
+{
+    public static $defaultTemplates = [
+        self::MODE_DEFAULT => [
+            self::STANDARD => '{{name}} must be iterable',
+        ],
+        self::MODE_NEGATIVE => [
+            self::STANDARD => '{{name}} must not be iterable',
+        ],
+    ];
+}

library/Rules/Iterable.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of Respect/Validation.
+ *
+ * (c) Alexandre Gomes Gaigalas <alexandre@gaigalas.net>
+ *
+ * For the full copyright and license information, please view the "LICENSE.md"
+ * file that was distributed with this source code.
+ */
+
+namespace Respect\Validation\Rules;
+
+class Iterable extends AbstractRule
+{
+    public function validate($input)
+    {
+        return is_array($input) ||
+            $input instanceof \stdClass ||
+            $input instanceof \Traversable;
+    }
+}

library/Validator.php

@@ -73,6 +73,7 @@ use Respect\Validation\Rules\Key;
  * @method static Validator intVal()
  * @method static Validator intType()
  * @method static Validator ip(mixed $ipOptions = null)
+ * @method static Validator iterable()
  * @method static Validator json()
  * @method static Validator key(string $reference, Validatable $referenceValidator = null, bool $mandatory = true)
  * @method static Validator keyNested(string $reference, Validatable $referenceValidator = null, bool $mandatory = true)

tests/integration/iterable_1.phpt

@@ -0,0 +1,11 @@
+--FILE--
+<?php
+
+require 'vendor/autoload.php';
+
+use Respect\Validation\Validator as v;
+
+v::iterable()->assert([1, 2, 3]);
+v::iterable()->check(new ArrayObject);
+?>
+--EXPECTF--

tests/integration/iterable_2.phpt

@@ -0,0 +1,16 @@
+--FILE--
+<?php
+
+require 'vendor/autoload.php';
+
+use Respect\Validation\Exceptions\IterableException;
+use Respect\Validation\Validator as v;
+
+try {
+    v::iterable()->check(3);
+} catch (IterableException $exception) {
+    echo $exception->getMainMessage();
+}
+?>
+--EXPECTF--
+3 must be iterable

tests/integration/iterable_3.phpt

@@ -0,0 +1,16 @@
+--FILE--
+<?php
+
+require 'vendor/autoload.php';
+
+use Respect\Validation\Exceptions\IterableException;
+use Respect\Validation\Validator as v;
+
+try {
+    v::not(v::iterable())->check([2, 3]);
+} catch (IterableException $exception) {
+    echo $exception->getMainMessage();
+}
+?>
+--EXPECTF--
+{ 2, 3 } must not be iterable

tests/integration/iterable_4.phpt

@@ -0,0 +1,16 @@
+--FILE--
+<?php
+require 'vendor/autoload.php';
+
+use Respect\Validation\Exceptions\AllOfException;
+use Respect\Validation\Validator as v;
+
+try {
+    v::iterable()->assert('String');
+} catch (AllOfException $exception) {
+    echo $exception->getFullMessage();
+}
+
+?>
+--EXPECTF--
+\-"String" must be iterable

tests/integration/iterable_5.phpt

@@ -0,0 +1,16 @@
+--FILE--
+<?php
+require 'vendor/autoload.php';
+
+use Respect\Validation\Exceptions\AllOfException;
+use Respect\Validation\Validator as v;
+
+try {
+    v::not(v::iterable())->assert(new stdClass());
+} catch (AllOfException $exception) {
+    echo $exception->getFullMessage();
+}
+
+?>
+--EXPECTF--
+\-`[object] (stdClass: { })` must not be iterable

tests/unit/Rules/IterableTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of Respect/Validation.
+ *
+ * (c) Alexandre Gomes Gaigalas <alexandre@gaigalas.net>
+ *
+ * For the full copyright and license information, please view the "LICENSE.md"
+ * file that was distributed with this source code.
+ */
+
+namespace Respect\Validation\Rules;
+
+/**
+ * @group  rule
+ * @covers Respect\Validation\Rules\Iterable
+ */
+class IterableTest extends RuleTestCase
+{
+    public function providerForValidInput()
+    {
+        $rule = new Iterable();
+
+        return [
+            [$rule, [1, 2, 3]],
+            [$rule, new \stdClass],
+            [$rule, new \ArrayIterator]
+        ];
+    }
+
+    public function providerForInvalidInput()
+    {
+        $rule = new Iterable();
+
+        return [
+            [$rule, 3],
+            [$rule, 'asdf'],
+            [$rule, 9.85],
+            [$rule, null],
+            [$rule, true]
+        ];
+    }
+}