Merge pull request #38 from chadicus/email

Add email filter

Author: Jonathan Gaillard

README.md

@@ -198,6 +198,14 @@ The following checks that `$value` is a URL.
 \DominionEnterprises\Filter\Url::filter($value);
 ```
 
+#### Email::filter
+Aliased in the filterer as `email`, this filter verifies that the argument is an email.
+
+The following checks that `$value` is an email.
+```php
+\DominionEnterprises\Filter\Email::filter($value);
+```
+
 ##Contact
 Developers may be contacted at:
 

src/Filter/Email.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Defines the DominionEnterprises\Filter\Email class.
+ */
+
+namespace DominionEnterprises\Filter;
+
+/**
+ * A collection of filters for emails.
+ */
+final class Email
+{
+    /**
+     * Filter an email
+     *
+     * The return value is the email, as expected by the \DominionEnterprises\Filterer class.
+     *
+     * @param mixed $value The value to filter.
+     *
+     * @return string The passed in $value.
+     *
+     * @throws \Exception if the value did not pass validation.
+     */
+    public static function filter($value)
+    {
+        if (!is_string($value)) {
+            throw new \Exception("Value '" . var_export($value, true) . "' is not a string");
+        }
+
+        $filteredEmail = filter_var($value, FILTER_VALIDATE_EMAIL);
+        if ($filteredEmail === false) {
+            throw new \Exception("Value '{$value}' is not a valid email");
+        }
+
+        return $filteredEmail;
+    }
+}

src/Filterer.php

@@ -22,6 +22,7 @@ final class Filterer
         'ofArrays' => '\DominionEnterprises\Filter\Arrays::ofArrays',
         'ofArray' => '\DominionEnterprises\Filter\Arrays::ofArray',
         'url' => '\DominionEnterprises\Filter\Url::filter',
+        'email' => '\DominionEnterprises\Filter\Email::filter',
     );
 
     /**

tests/Filter/EmailTest.php

@@ -0,0 +1,41 @@
+<?php
+namespace DominionEnterprises\Filter;
+use DominionEnterprises\Filter\Email as E;
+
+/**
+ * @coversDefaultClass \DominionEnterprises\Filter\Email
+ */
+final class EmailTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filter()
+    {
+        $email = 'first.last@email.com';
+        $this->assertSame($email, E::filter($email));
+    }
+
+    /**
+     * @test
+     * @expectedException Exception
+     * @expectedExceptionMessage Value '1' is not a string
+     * @covers ::filter
+     */
+    public function filter_nonstring()
+    {
+        E::filter(1);
+    }
+
+    /**
+     * @test
+     * @expectedException Exception
+     * @expectedExceptionMessage Value '@email.com' is not a valid email
+     * @covers ::filter
+     */
+    public function filter_notValid()
+    {
+        E::filter('@email.com');
+    }
+}