Add isValidEmail method for email validation and update README

Author: k2gl

README.md

@@ -172,6 +172,9 @@ fact('')->isNotEmptyString(); // Fails
 
 fact('{"key": "value"}')->isJson(); // Passes
 fact('invalid json')->isJson(); // Fails
+
+fact('user@example.com')->isValidEmail(); // Passes
+fact('invalid-email')->isValidEmail(); // Fails
 ```
 
 ### Type Checking assertions

src/Traits/StringAssertions.php

@@ -313,5 +313,25 @@ public function isJson(string $message = ''): self
         return $this;
     }
 
+    /**
+     * Asserts that a string is a valid email address.
+     *
+     * This method checks if the actual string is a valid email format.
+     *
+     * Example usage:
+     * fact('user@example.com')->isValidEmail(); // Passes
+     * fact('invalid-email')->isValidEmail(); // Fails
+     *
+     * @param string $message Optional custom error message.
+     *
+     * @return self Enables fluent chaining of assertion methods.
+     */
+    public function isValidEmail(string $message = ''): self
+    {
+        Assert::assertTrue(filter_var($this->variable, FILTER_VALIDATE_EMAIL) !== false, $message ?: 'String is not a valid email address.');
+
+        return $this;
+    }
+
     // endregion Length Methods
 }

tests/FluentAssertions/Asserts/IsValidEmail/IsValidEmailTest.php

@@ -0,0 +1,52 @@
+<?php declare(strict_types=1);
+
+namespace K2gl\PHPUnitFluentAssertions\Tests\FluentAssertions\Asserts\IsValidEmail;
+
+use K2gl\PHPUnitFluentAssertions\Tests\FluentAssertions\FluentAssertionsTestCase;
+use K2gl\PHPUnitFluentAssertions\FluentAssertions;
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+use function K2gl\PHPUnitFluentAssertions\fact;
+
+#[CoversMethod(className: FluentAssertions::class, methodName: 'isValidEmail')]
+final class IsValidEmailTest extends FluentAssertionsTestCase
+{
+    #[DataProvider('isValidEmailDataProvider')]
+    public function testIsValidEmail(mixed $variable): void
+    {
+        // act
+        fact($variable)->isValidEmail();
+
+        // assert
+        $this->correctAssertionExecuted();
+    }
+
+    #[DataProvider('notIsValidEmailDataProvider')]
+    public function testNotIsValidEmail(mixed $variable): void
+    {
+        // assert
+        $this->incorrectAssertionExpected();
+
+        // act
+        fact($variable)->isValidEmail();
+    }
+
+    public static function isValidEmailDataProvider(): array
+    {
+        return [
+            ['user@example.com'],
+            ['test.email+tag@domain.co.uk'],
+        ];
+    }
+
+    public static function notIsValidEmailDataProvider(): array
+    {
+        return [
+            ['invalid-email'],
+            ['@example.com'],
+            ['user@'],
+            [''],
+        ];
+    }
+}