Add StringEmail type with tryFromString and comprehensive tests

- Implemented `StringEmail` class for representing validated email addresses.
- Added `fromString` and `tryFromString` methods to validate and parse emails, returning `Undefined` for invalid cases.
- Introduced `EmailStringTypeException` to handle invalid email inputs.
- Updated `Usage` examples to demonstrate `StringEmail` usage and `tryFromString` behavior.
- Included robust unit tests to validate creation, exception handling, and `Undefined` behavior for invalid inputs.

Author: georgedeploy

.gitignore

@@ -1,2 +1,3 @@
 .idea
 /vendor/
+/cache/

src/Exception/EmailStringTypeException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Exception;
+
+class EmailStringTypeException extends TypeException
+{
+}

src/String/StringEmail.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String;
+
+use const FILTER_VALIDATE_EMAIL;
+
+use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\EmailStringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+use function filter_var;
+use function sprintf;
+
+/**
+ * Email address string (pragmatic validation).
+ *
+ * Example "user@example.com"
+ *
+ * @psalm-immutable
+ */
+readonly class StringEmail extends StrType
+{
+    /** @var non-empty-string */
+    protected string $value;
+
+    /**
+     * @throws EmailStringTypeException
+     */
+    public function __construct(string $value)
+    {
+        if (filter_var($value, FILTER_VALIDATE_EMAIL) === false) {
+            throw new EmailStringTypeException(sprintf('Expected valid email address, got "%s"', $value));
+        }
+
+        /** @var non-empty-string $value */
+        $this->value = $value;
+    }
+
+    /**
+     * @throws EmailStringTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        return new static($value);
+    }
+
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    /** @return non-empty-string */
+    public function value(): string
+    {
+        return $this->value;
+    }
+}

src/Usage/String.php

@@ -7,6 +7,7 @@
 use PhpTypedValues\String\Alias\StrType;
 use PhpTypedValues\String\Json;
 use PhpTypedValues\String\MariaDb\StringVarChar255;
+use PhpTypedValues\String\StringEmail;
 use PhpTypedValues\String\StringNonBlank;
 use PhpTypedValues\String\StringNonEmpty;
 use PhpTypedValues\String\StringStandard;
@@ -42,6 +43,13 @@
 echo json_encode(Json::fromString('{"a": 1}')->toObject(), \JSON_THROW_ON_ERROR) . \PHP_EOL;
 echo Json::tryFromString('{}')->toString() . \PHP_EOL;
 
+// Email (usage and try* for Psalm visibility)
+echo StringEmail::fromString('User@Example.COM')->toString() . \PHP_EOL; // normalized to lowercase
+$em = StringEmail::tryFromString('not-an-email');
+if (!($em instanceof Undefined)) {
+    echo $em->toString() . \PHP_EOL;
+}
+
 /**
  * Artificial functions.
  */

tests/Unit/String/StringEmail/StringEmailTest.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\EmailStringTypeException;
+use PhpTypedValues\String\StringEmail;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('accepts valid email, preserves value/toString', function (): void {
+    $e = new StringEmail('User.Name+tag@Example.COM');
+
+    expect($e->value())
+        ->toBe('User.Name+tag@Example.COM')
+        ->and($e->toString())
+        ->toBe('User.Name+tag@Example.COM')
+        ->and((string) $e)
+        ->toBe('User.Name+tag@Example.COM');
+});
+
+it('throws EmailStringTypeException on empty or invalid emails', function (): void {
+    expect(fn() => new StringEmail(''))
+        ->toThrow(EmailStringTypeException::class, 'Expected valid email address, got ""')
+        ->and(fn() => StringEmail::fromString(' User.Name+tag@Example.COM '))
+        ->toThrow(EmailStringTypeException::class, 'Expected valid email address, got " User.Name+tag@Example.COM "')
+        ->and(fn() => StringEmail::fromString('not-an-email'))
+        ->toThrow(EmailStringTypeException::class, 'Expected valid email address, got "not-an-email"');
+});
+
+it('tryFromString returns instance for valid and Undefined for invalid', function (): void {
+    $ok = StringEmail::tryFromString('admin@Example.org');
+    $bad = StringEmail::tryFromString('invalid');
+
+    expect($ok)
+        ->toBeInstanceOf(StringEmail::class)
+        ->and($ok->value())
+        ->toBe('admin@Example.org')
+        ->and($bad)
+        ->toBeInstanceOf(Undefined::class);
+});