Merge pull request #43 from nubs/master

Add String::explode and Arrays::flatten filters

Author: Jonathan Gaillard

README.md

@@ -152,6 +152,14 @@ $value = \DominionEnterprises\Filter\Arrays::ofArrays($value, ['id' => [['uint']
 Aliased in the filterer as `ofArray`, this filter verifies that the argument is an array that passes the given specification.  This is
 essentially a flipped version of `Filterer::filter` that allows for testing nested associative arrays.
 
+#### Arrays::flatten
+Aliased in the filterer as `flatten`, this filter flattens a multi-dimensional array to a single dimension.  The order of values will be
+maintained, but the keys themselves will not.  For example:
+```php
+$value = \DominionEnterprises\Filter\Arrays::flatten([[1, 2], [3, [4, 5]]]);
+assert($value === [1, 2, 3, 4, 5]);
+```
+
 #### Bool::filter
 Aliased in the filterer as `bool`, this filter verifies that the argument is a boolean value or a string that maps to one.  The second parameter
 can be set to `true` to allow null values through without an error (they will stay null and not get converted to false).  The last parameters
@@ -188,6 +196,14 @@ The following checks that `$value` is a non-empty string.
 \DominionEnterprises\Filter\String::filter($value);
 ```
 
+#### String::explode
+Aliased in the filterer as `explode`, this filter is essentially a wrapper around the built-in [`explode`](http://www.php.net/explode) method
+with the value first in order to work with the `Filterer`.  It also defaults to using `,` as a delimiter.  For example:
+```php
+$value = \DominionEnterprises\Filter\String::explode('abc,def,ghi');
+assert($value === ['abc', 'def', 'ghi']);
+```
+
 #### Url::filter
 Aliased in the filterer as `url`, this filter verifies that the argument is a URL string according to
 [RFC2396](http://www.faqs.org/rfcs/rfc2396).

src/Filter/Arrays.php

@@ -165,4 +165,29 @@ public static function ofArray(array $value, array $spec)
 
         return $result;
     }
+
+    /**
+     * Given a multi-dimensional array, flatten the array to a single level.
+     *
+     * The order of the values will be maintained, but the keys will not.
+     *
+     * For example, given the array [[1, 2], [3, [4, 5]]], this would result in the array [1, 2, 3, 4, 5].
+     *
+     * @param array $value The array to flatten.
+     *
+     * @return array The single-dimension array.
+     */
+    public static function flatten(array $value)
+    {
+        $result = array();
+
+        array_walk_recursive(
+            $value,
+            function($item) use(&$result) {
+                $result[] = $item;
+            }
+        );
+
+        return $result;
+    }
 }

src/Filter/String.php

@@ -57,4 +57,29 @@ public static function filter($value, $allowNull = false, $minLength = 1, $maxLe
 
         return $value;
     }
+
+    /**
+     * Explodes a string into an array using the given delimiter.
+     *
+     * For example, given the string 'foo,bar,baz', this would return the array ['foo', 'bar', 'baz'].
+     *
+     * @param string $value The string to explode.
+     * @param string $delimiter The non-empty delimiter to explode on.
+     * @return array The exploded values.
+     *
+     * @throws \Exception if the value is not a string.
+     * @throws \InvalidArgumentException if the delimiter does not pass validation.
+     */
+    public static function explode($value, $delimiter = ',')
+    {
+        if (!is_string($value)) {
+            throw new \Exception("Value '" . var_export($value, true) . "' is not a string");
+        }
+
+        if (!is_string($delimiter) || empty($delimiter)) {
+            throw new \InvalidArgumentException("Delimiter '" . var_export($delimiter, true) . "' is not a non-empty string");
+        }
+
+        return explode($delimiter, $value);
+    }
 }

src/Filterer.php

@@ -23,6 +23,8 @@ final class Filterer
         'ofArray' => '\DominionEnterprises\Filter\Arrays::ofArray',
         'url' => '\DominionEnterprises\Filter\Url::filter',
         'email' => '\DominionEnterprises\Filter\Email::filter',
+        'explode' => '\DominionEnterprises\Filter\String::explode',
+        'flatten' => '\DominionEnterprises\Filter\Arrays::flatten',
     );
 
     /**

tests/Filter/ArraysTest.php

@@ -325,4 +325,15 @@ public function ofArray_unknown()
             $this->assertSame($expected, $e->getMessage());
         }
     }
+
+    /**
+     * Verifies the basic behavior of the flatten filter.
+     *
+     * @test
+     * @covers ::flatten
+     */
+    public function flatten()
+    {
+        $this->assertSame(array(1, 2, 3, 4, 5), A::flatten(array(array(1, 2), array(array(3, array(4, 5))))));
+    }
 }

tests/Filter/StringTest.php

@@ -131,4 +131,65 @@ public function filter_maxLengthNegative()
     {
         S::filter('a', false, 1, -1);
     }
+
+    /**
+     * Verifies basic explode functionality.
+     *
+     * @test
+     * @covers ::explode
+     */
+    public function explode()
+    {
+        $this->assertSame(array('a', 'bcd', 'e'), S::explode('a,bcd,e'));
+    }
+
+    /**
+     * Verifies explode with a custom delimiter.
+     *
+     * @test
+     * @covers ::explode
+     */
+    public function explode_customDelimiter()
+    {
+        $this->assertSame(array('a', 'b', 'c', 'd,e'), S::explode('a b c d,e', ' '));
+    }
+
+    /**
+     * Verifies explode filter with a non-string value.
+     *
+     * @test
+     * @expectedException Exception
+     * @expectedExceptionMessage Value 'true' is not a string
+     * @covers ::explode
+     */
+    public function explode_nonStringValue()
+    {
+        S::explode(true);
+    }
+
+    /**
+     * Verifies explode filter with a non-string delimiter.
+     *
+     * @test
+     * @expectedException Exception
+     * @expectedExceptionMessage Delimiter '4' is not a non-empty string
+     * @covers ::explode
+     */
+    public function explode_nonStringDelimiter()
+    {
+        S::explode('test', 4);
+    }
+
+    /**
+     * Verifies explode filter with an empty delimiter.
+     *
+     * @test
+     * @expectedException Exception
+     * @expectedExceptionMessage Delimiter '''' is not a non-empty string
+     * @covers ::explode
+     */
+    public function explode_emptyDelimiter()
+    {
+        S::explode('test', '');
+    }
 }