Add StringUrl type with tryFromString, alias, and unit tests

- Implemented `StringUrl` class to represent validated absolute URLs, using `FILTER_VALIDATE_URL` for pragmatic validation.
- Added `fromString` and `tryFromString` methods, returning `Undefined` for invalid URLs.
- Introduced `UrlStringTypeException` to handle invalid URL inputs.
- Created alias `Url` as a readonly extension of `StringUrl`.
- Updated `Usage` examples to demonstrate `StringUrl` and `tryFromString` behavior.
- Included unit tests to validate creation, exception handling, alias behavior, and the `Undefined` return for invalid cases.

Author: georgedeploy

src/Exception/UrlStringTypeException.php

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

src/String/Alias/Url.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String\Alias;
+
+use PhpTypedValues\String\StringUrl;
+
+/**
+ * @psalm-immutable
+ */
+readonly class Url extends StringUrl
+{
+}

src/String/StringEmail.php

@@ -15,7 +15,7 @@
 use function sprintf;
 
 /**
- * Email address string (pragmatic validation).
+ * Email address string RFC 5322 (pragmatic validation).
  *
  * Example "user@example.com"
  *

src/String/StringUrl.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String;
+
+use const FILTER_VALIDATE_URL;
+
+use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Exception\UrlStringTypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+use function filter_var;
+use function sprintf;
+
+/**
+ * Absolute URL string (http/https recommended; uses FILTER_VALIDATE_URL for pragmatic validation).
+ *
+ * Example "https://example.com/path?x=1"
+ *
+ * @psalm-immutable
+ */
+readonly class StringUrl extends StrType
+{
+    /** @var non-empty-string */
+    protected string $value;
+
+    /**
+     * @throws UrlStringTypeException
+     */
+    public function __construct(string $value)
+    {
+        if (filter_var($value, FILTER_VALIDATE_URL) === false) {
+            throw new UrlStringTypeException(sprintf('Expected valid URL, got "%s"', $value));
+        }
+
+        /** @var non-empty-string $value */
+        $this->value = $value;
+    }
+
+    /**
+     * @throws UrlStringTypeException
+     */
+    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

@@ -6,12 +6,14 @@
 use PhpTypedValues\String\Alias\NonEmptyStr;
 use PhpTypedValues\String\Alias\Str;
 use PhpTypedValues\String\Alias\StrType;
+use PhpTypedValues\String\Alias\Url;
 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;
+use PhpTypedValues\String\StringUrl;
 use PhpTypedValues\String\StringUuidV4;
 use PhpTypedValues\String\StringUuidV7;
 use PhpTypedValues\Undefined\Alias\Undefined;
@@ -52,6 +54,14 @@
     echo $em->toString() . \PHP_EOL;
 }
 
+// URL (usage and try* for Psalm visibility)
+echo Url::fromString('https://example.com/path?x=1')->toString() . \PHP_EOL;
+echo StringUrl::fromString('https://example.com/path?x=1')->toString() . \PHP_EOL;
+$url = StringUrl::tryFromString('notaurl');
+if (!($url instanceof Undefined)) {
+    echo $url->toString() . \PHP_EOL;
+}
+
 /**
  * Artificial functions.
  */

tests/Unit/String/StringUrl/StringUrlTest.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\UrlStringTypeException;
+use PhpTypedValues\String\StringUrl;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('accepts valid URL, preserves value/toString and casts via __toString', function (): void {
+    $u = new StringUrl('https://example.com/path?x=1#anchor');
+
+    expect($u->value())
+        ->toBe('https://example.com/path?x=1#anchor')
+        ->and($u->toString())
+        ->toBe('https://example.com/path?x=1#anchor')
+        ->and((string) $u)
+        ->toBe('https://example.com/path?x=1#anchor');
+});
+
+it('throws UrlStringTypeException on empty or invalid URLs', function (): void {
+    expect(fn() => new StringUrl(''))
+        ->toThrow(UrlStringTypeException::class, 'Expected valid URL, got ""')
+        ->and(fn() => StringUrl::fromString('not-a-url'))
+        ->toThrow(UrlStringTypeException::class, 'Expected valid URL, got "not-a-url"');
+});
+
+it('tryFromString returns instance for valid and Undefined for invalid', function (): void {
+    $ok = StringUrl::tryFromString('https://www.example.org');
+    $bad = StringUrl::tryFromString('notaurl');
+
+    expect($ok)
+        ->toBeInstanceOf(StringUrl::class)
+        ->and($ok->value())
+        ->toBe('https://www.example.org')
+        ->and($bad)
+        ->toBeInstanceOf(Undefined::class);
+});