feat/add-support-for-checking-emails (#19)

* Add tests.

* Update `README.md`.

* Add support for validating emails.

* Add "zero-to-prod/validate-email" dep.

---------

Co-authored-by: david_smith <[email protected]>

README.md

@@ -38,6 +38,7 @@ class DataModelHelper
 - [pregReplace](#pregreplace): Perform a regular expression search and replace.
 - [pregMatch](#pregmatch): Perform a regular expression match.
 - [isUrl](#isurl): Validates a url.
+- [isEmail](#isemail): Validates an email.
 
 ### `mapOf`
 
@@ -474,7 +475,7 @@ echo $User->name; // Outputs: 's'
 
 ### `isUrl`
 
-Use `isUrl` to perform validate a url.
+Use `isUrl` to validate a url.
 
 ```php
 class User
@@ -486,7 +487,27 @@ class User
         'cast' => [self::class, 'isUrl'],
         'protocols' => ['http', 'udp'], // Optional. Defaults to all.
         'on_fail' => [MyAction::class, 'method'], // Optional. Invoked when validation fails.
-        'exception' => InvalidUrlException::class, // Optional. Throws an exception when not url.
+        'exception' => MyCustomException::class, // Optional. Throws an exception when not url.
+        'required'  // Optional. Throws \Zerotoprod\DataModel\PropertyRequiredException::class
+    ])]
+    public string $url;
+}
+```
+
+### `isEmail`
+
+Use `isEmail` to validate an email.
+
+```php
+class User
+{
+    use \Zerotoprod\DataModel\DataModel;
+    use \Zerotoprod\DataModelHelper\DataModelHelper;
+
+    #[Describe([
+        'cast' => [self::class, 'isEmail'],
+        'on_fail' => [MyAction::class, 'method'], // Optional. Invoked when validation fails.
+        'exception' => MyCustomException::class, // Optional. Throws an exception when not url.
         'required'  // Optional. Throws \Zerotoprod\DataModel\PropertyRequiredException::class
     ])]
     public string $url;

composer.json

@@ -17,7 +17,8 @@
   "require": {
     "php": ">=8.1.0",
     "zero-to-prod/data-model": "^v81.0.0",
-    "zero-to-prod/validate-url": "^71.0"
+    "zero-to-prod/validate-url": "^71.0",
+    "zero-to-prod/validate-email": "^71.0"
   },
   "autoload": {
     "psr-4": {

src/DataModelHelper.php

@@ -5,6 +5,7 @@
 use ReflectionAttribute;
 use ReflectionProperty;
 use Zerotoprod\DataModel\PropertyRequiredException;
+use Zerotoprod\ValidateEmail\ValidateEmail;
 use Zerotoprod\ValidateUrl\ValidateUrl;
 
 /**
@@ -159,7 +160,7 @@ public static function pregMatch(mixed $value, array $context, ?ReflectionAttrib
      *       'cast' => [self::class, 'isUrl'],
      *       'protocols' => ['http', 'udp'], // Optional. Defaults to all.
      *       'on_fail' => [MyAction::class, 'method'], // Optional. Invoked when validation fails.
-     *       'exception' => InvalidUrlException::class, // Optional. Throws an exception when not url.
+     *       'exception' => MyException::class, // Optional. Throws an exception when not url.
      *   ])]
      *  ```
      */
@@ -195,4 +196,47 @@ public static function isUrl(mixed $value, array $context, ?ReflectionAttribute
 
         return $value;
     }
+
+    /**
+     * Determine if a given value is a valid URL.
+     *  ```
+     *   #[Describe([
+     *       'cast' => [self::class, 'isEmail'],
+     *       'on_fail' => [MyAction::class, 'method'], // Optional. Invoked when validation fails.
+     *       'exception' => MyException::class, // Optional. Throws an exception when not a valid email.
+     *   ])]
+     *  ```
+     */
+    public static function isEmail(mixed $value, array $context, ?ReflectionAttribute $Attribute, ReflectionProperty $Property): ?string
+    {
+        $args = $Attribute?->getArguments()[0];
+        if (!$value && $Property->getType()?->allowsNull()) {
+            return null;
+        }
+
+        if (!$value && in_array('required', $args, true)) {
+            throw new PropertyRequiredException("Property `\${$Property->getName()}` is required.");
+        }
+
+        if (!is_string($value)) {
+            if (isset($args['on_fail'])) {
+                call_user_func($args['on_fail'], $value, $context, $Attribute, $Property);
+            }
+
+            if (isset($args['exception'])) {
+                throw new $args['exception'];
+            }
+        }
+
+        if (!ValidateEmail::isEmail($value)) {
+            if (isset($args['on_fail'])) {
+                call_user_func($args['on_fail'], $value, $context, $Attribute, $Property);
+            }
+            if (isset($args['exception'])) {
+                throw new $args['exception'];
+            }
+        }
+
+        return $value;
+    }
 }

tests/Unit/IsEmail/Callable/InvalidEmail/BadEmailException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Callable\InvalidEmail;
+
+use RuntimeException;
+
+class BadEmailException extends RuntimeException
+{
+
+}

tests/Unit/IsEmail/Callable/InvalidEmail/InvalidEmailTest.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Callable\InvalidEmail;
+
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class InvalidEmailTest extends TestCase
+{
+    #[Test] public function invalid_email(): void
+    {
+        $this->expectException(BadEmailException::class);
+        User::from([
+            User::email => 'invalid email',
+        ]);
+    }
+}

tests/Unit/IsEmail/Callable/InvalidEmail/User.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Callable\InvalidEmail;
+
+use Zerotoprod\DataModel\DataModel;
+use Zerotoprod\DataModel\Describe;
+use Zerotoprod\DataModelHelper\DataModelHelper;
+
+class User
+{
+    use DataModel;
+    use DataModelHelper;
+
+    public const email = 'email';
+
+    #[Describe([
+        'cast' => [self::class, 'isEmail'],
+        'on_fail' => [self::class, 'failed'],
+    ])]
+    public string $email;
+
+    public static function failed(): string
+    {
+        throw new BadEmailException();
+    }
+}

tests/Unit/IsEmail/Callable/NotString/BadEmailException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Callable\NotString;
+
+use RuntimeException;
+
+class BadEmailException extends RuntimeException
+{
+
+}

tests/Unit/IsEmail/Callable/NotString/NotEmailStringTest.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Callable\NotString;
+
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class NotEmailStringTest extends TestCase
+{
+    #[Test] public function invalid_email(): void
+    {
+        $this->expectException(BadEmailException::class);
+        User::from([
+            User::email => 1,
+        ]);
+    }
+}

tests/Unit/IsEmail/Callable/NotString/User.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Callable\NotString;
+
+use Zerotoprod\DataModel\DataModel;
+use Zerotoprod\DataModel\Describe;
+use Zerotoprod\DataModelHelper\DataModelHelper;
+
+class User
+{
+    use DataModel;
+    use DataModelHelper;
+
+    public const email = 'email';
+
+    #[Describe([
+        'cast' => [self::class, 'isEmail'],
+        'on_fail' => [self::class, 'failed'],
+    ])]
+    public string $email;
+
+    public static function failed(): string
+    {
+        throw new BadEmailException();
+    }
+}

tests/Unit/IsEmail/Exception/InvalidUrl/BadEmailException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Exception\InvalidUrl;
+
+use RuntimeException;
+
+class BadEmailException extends RuntimeException
+{
+
+}

tests/Unit/IsEmail/Exception/InvalidUrl/CustomExceptionTest.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Exception\InvalidUrl;
+
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class CustomExceptionTest extends TestCase
+{
+    #[Test] public function invalid_email(): void
+    {
+        $this->expectException(BadEmailException::class);
+        User::from([
+            User::email => 'invalid email',
+        ]);
+    }
+}

tests/Unit/IsEmail/Exception/InvalidUrl/User.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Exception\InvalidUrl;
+
+use Zerotoprod\DataModel\DataModel;
+use Zerotoprod\DataModel\Describe;
+use Zerotoprod\DataModelHelper\DataModelHelper;
+
+class User
+{
+    use DataModel;
+    use DataModelHelper;
+
+    public const email = 'email';
+
+    #[Describe([
+        'cast' => [self::class, 'isEmail'],
+        'exception' => BadEmailException::class
+    ])]
+    public string $email;
+}

tests/Unit/IsEmail/Exception/NotString/BadEmailException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Exception\NotString;
+
+use RuntimeException;
+
+class BadEmailException extends RuntimeException
+{
+
+}

tests/Unit/IsEmail/Exception/NotString/NotStringEmailCustomExceptionTest.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Exception\NotString;
+
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class NotStringEmailCustomExceptionTest extends TestCase
+{
+    #[Test] public function not_string(): void
+    {
+        $this->expectException(BadEmailException::class);
+        User::from([
+            User::email => 1,
+        ]);
+    }
+}

tests/Unit/IsEmail/Exception/NotString/User.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Tests\Unit\IsEmail\Exception\NotString;
+
+use Zerotoprod\DataModel\DataModel;
+use Zerotoprod\DataModel\Describe;
+use Zerotoprod\DataModelHelper\DataModelHelper;
+
+class User
+{
+    use DataModel;
+    use DataModelHelper;
+
+    public const email = 'email';
+
+    #[Describe([
+        'cast' => [self::class, 'isEmail'],
+        'exception' => BadEmailException::class
+    ])]
+    public string $email;
+}

tests/Unit/IsEmail/NullUrl/NullUrlTest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Tests\Unit\IsEmail\NullUrl;
+
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class NullUrlTest extends TestCase
+{
+    #[Test] public function null_email(): void
+    {
+        $User = User::from();
+
+        self::assertNull($User->email);
+    }
+}

tests/Unit/IsEmail/NullUrl/User.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Tests\Unit\IsEmail\NullUrl;
+
+use Zerotoprod\DataModel\DataModel;
+use Zerotoprod\DataModel\Describe;
+use Zerotoprod\DataModelHelper\DataModelHelper;
+
+class User
+{
+    use DataModel;
+    use DataModelHelper;
+
+    public const email = 'email';
+
+    #[Describe([
+        'cast' => [self::class, 'isEmail']
+    ])]
+    public ?string $email;
+}