Merge pull request #47 from programmatordev/YAPV-21-create-url-rule

Create URL rule

Author: andrepimpao

docs/03-rules.md

@@ -15,6 +15,7 @@
 ## String Rules
 
 - [Email](03x-rules-email.md)
+- [URL](03x-rules-url.md)
 
 ## Comparison Rules
 

docs/03x-rules-url.md

@@ -0,0 +1,75 @@
+# URL
+
+Validates that a value is a valid URL address.
+
+```php
+Url(
+    array $protocols = ['http', 'https'],
+    bool $allowRelativeProtocol = false,
+    ?callable $normalizer = null,
+    string $message = 'The {{ name }} value is not a valid URL address, {{ value }} given.'
+);
+```
+
+## Basic Usage
+
+```php
+Validator::url()->validate('https://example.com'); // true
+
+// Only allow the https protocol
+Validator::url(protocols: ['https'])->validate('http://example.com'); // false
+// Or allow the ftp protocol too
+Validator::url(protocols: ['https', 'ftp'])->validate('ftp://example.com'); // true
+
+// Allow relative protocol
+Validator::url()->validate('//example.com'); // false
+Validator::url(allowRelativeProtocol: true)->validate('//example.com'); // true
+Validator::url(allowRelativeProtocol: true)->validate('https://example.com'); // true
+```
+
+## Options
+
+### `protocols`
+
+type: `array` default: `['http', 'https']`
+
+Set this option to define the allowed protocols.
+
+### `allowRelativeProtocol`
+
+type: `bool` default: `false`
+
+If this option is `true`, inclusion of a protocol in the URL will be optional.
+
+### `normalizer`
+
+type: `callable` default: `null`
+
+Allows to define a `callable` that will be applied to the value before checking if it is valid.
+
+For example, use `trim`, or pass your own function, to ignore whitespace in the beginning or end of a URL address:
+
+```php
+Validator::url()->validate('https://example.com '); // false
+
+Validator::url(normalizer: 'trim')->validate('https://example.com '); // true
+Validator::url(normalizer: fn($value) => trim($value))->validate('https://example.com '); // true
+```
+
+### `message`
+
+type `string` default: `The {{ name }} value is not a valid URL address, {{ value }} given.`
+
+Message that will be shown if the input value is not a valid URL address.
+
+The following parameters are available:
+
+| Parameter         | Description               |
+|-------------------|---------------------------|
+| `{{ value }}`     | The current invalid value |
+| `{{ name }}`      | Name of the invalid value |
+| `{{ protocols }}` | Allowed protocols         |
+
+## Changelog
+
+- `0.6.0` Created

src/ChainedValidatorInterface.php

@@ -84,4 +84,11 @@ public function type(
         string|array $constraint,
         string $message = 'The {{ name }} value should be of type {{ constraint }}, {{ value }} given.'
     ): ChainedValidatorInterface&Validator;
+
+    public function url(
+        array $protocols = ['http', 'https'],
+        bool $allowRelativeProtocol = false,
+        ?callable $normalizer = null,
+        string $message = 'The {{ name }} value is not a valid URL address, {{ value }} given.'
+    ): ChainedValidatorInterface&Validator;
 }

src/Exception/UrlException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Exception;
+
+class UrlException extends ValidationException {}

src/Rule/Url.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
+
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedTypeException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UrlException;
+
+class Url extends AbstractRule implements RuleInterface
+{
+    // https://github.com/symfony/validator/blob/7.0/Constraints/UrlValidator.php
+    private const PATTERN = '~^
+            (%s)://   # protocol
+            (((?:[\_\.\pL\pN-]|%%[0-9A-Fa-f]{2})+:)?((?:[\_\.\pL\pN-]|%%[0-9A-Fa-f]{2})+)@)?   # basic auth
+            (
+                (?:
+                    (?:xn--[a-z0-9-]++\.)*+xn--[a-z0-9-]++      # a domain name using punycode
+                        |
+                    (?:[\pL\pN\pS\pM\-\_]++\.)+[\pL\pN\pM]++    # a multi-level domain name
+                        |
+                    [a-z0-9\-\_]++                              # a single-level domain name
+                )\.?
+                    |                                           # or
+                \d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}              # an IP address
+                    |                                           # or
+                \[
+                    (?:(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){6})(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:::(?:(?:(?:[0-9a-f]{1,4})):){5})(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:[0-9a-f]{1,4})))?::(?:(?:(?:[0-9a-f]{1,4})):){4})(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){0,1}(?:(?:[0-9a-f]{1,4})))?::(?:(?:(?:[0-9a-f]{1,4})):){3})(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){0,2}(?:(?:[0-9a-f]{1,4})))?::(?:(?:(?:[0-9a-f]{1,4})):){2})(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){0,3}(?:(?:[0-9a-f]{1,4})))?::(?:(?:[0-9a-f]{1,4})):)(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){0,4}(?:(?:[0-9a-f]{1,4})))?::)(?:(?:(?:(?:(?:[0-9a-f]{1,4})):(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){0,5}(?:(?:[0-9a-f]{1,4})))?::)(?:(?:[0-9a-f]{1,4})))|(?:(?:(?:(?:(?:(?:[0-9a-f]{1,4})):){0,6}(?:(?:[0-9a-f]{1,4})))?::))))
+                \]  # an IPv6 address
+            )
+            (:[0-9]+)?                                                          # a port (optional)
+            (?:/ (?:[\pL\pN\-._\~!$&\'()*+,;=:@]|%%[0-9A-Fa-f]{2})* )*          # a path
+            (?:\? (?:[\pL\pN\-._\~!$&\'\[\]()*+,;=:@/?]|%%[0-9A-Fa-f]{2})* )?   # a query (optional)
+            (?:\# (?:[\pL\pN\-._\~!$&\'()*+,;=:@/?]|%%[0-9A-Fa-f]{2})* )?       # a fragment (optional)
+        $~ixu';
+
+    // Using array to bypass unallowed callable type in properties
+    private array $normalizer;
+
+    public function __construct(
+        private readonly array $protocols = ['http', 'https'],
+        private readonly bool $allowRelativeProtocol = false,
+        ?callable $normalizer = null,
+        private readonly string $message = 'The {{ name }} value is not a valid URL address, {{ value }} given.'
+    )
+    {
+        $this->normalizer['callable'] = $normalizer;
+    }
+
+    public function assert(mixed $value, ?string $name = null): void
+    {
+        if (!\is_string($value)) {
+            throw new UnexpectedTypeException('string', get_debug_type($value));
+        }
+
+        if ($this->normalizer['callable'] !== null) {
+            $value = ($this->normalizer['callable'])($value);
+        }
+
+        $pattern = $this->allowRelativeProtocol ? \str_replace('(%s):', '(?:(%s):)?', self::PATTERN) : self::PATTERN;
+        $pattern = \sprintf($pattern, \implode('|', $this->protocols));
+
+        if (!\preg_match($pattern, $value)) {
+            throw new UrlException(
+                message: $this->message,
+                parameters: [
+                    'value' => $value,
+                    'name' => $name,
+                    'protocols' => $this->protocols
+                ]
+            );
+        }
+    }
+}

src/StaticValidatorInterface.php

@@ -83,4 +83,11 @@ public static function type(
         string|array $constraint,
         string $message = 'The {{ name }} value should be of type {{ constraint }}, {{ value }} given.'
     ): ChainedValidatorInterface&Validator;
+
+    public static function url(
+        array $protocols = ['http', 'https'],
+        bool $allowRelativeProtocol = false,
+        ?callable $normalizer = null,
+        string $message = 'The {{ name }} value is not a valid URL address, {{ value }} given.'
+    ): ChainedValidatorInterface&Validator;
 }

tests/UrlTest.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Test;
+
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UrlException;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule\Url;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleMessageOptionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleSuccessConditionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleUnexpectedValueTrait;
+
+class UrlTest extends AbstractTest
+{
+    use TestRuleUnexpectedValueTrait;
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleUnexpectedValueData(): \Generator
+    {
+        $typeMessage = '/Expected value of type "string", "(.*)" given./';
+
+        yield 'invalid type' => [new Url(), 1, $typeMessage];
+    }
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $exception = UrlException::class;
+        $message = '/The (.*) value is not a valid URL address, (.*) given./';
+
+        yield 'invalid url' => [new URL(), 'invalid', $exception, $message];
+        yield 'unallowed protocol' => [new URL(protocols: ['https']), 'http://test.com', $exception, $message];
+        yield 'unallowed relative protocol' => [new URL(), '//test.com', $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'domain' => [new URL(), 'https://test.com'];
+        yield 'multi-level domain' => [new URL(), 'https://multi.level.url.test.com'];
+        yield 'chars' => [new URL(), 'https://テスト.com'];
+        yield 'punycode' => [new URL(), 'https://xn--zckzah.com'];
+        yield 'port' => [new URL(), 'https://test.com:8000'];
+        yield 'path' => [new URL(), 'https://test.com/path'];
+        yield 'query' => [new URL(), 'https://test.com?test=1'];
+        yield 'fragment' => [new URL(), 'https://test.com#test'];
+        yield 'ipv4' => [new URL(), 'https://127.0.0.1'];
+        yield 'ipv6' => [new URL(), 'https://[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff]'];
+        yield 'basic auth' => [new URL(), 'https://username:password@test.com'];
+        yield 'full domain' => [new URL(), 'https://username:password@test.com:8000/path?test=1#test'];
+        yield 'full ipv4' => [new URL(), 'https://username:password@127.0.0.1:8000/path?test=1#test'];
+        yield 'full ipv6' => [new URL(), 'https://username:password@[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff]:8000/path?test=1#test'];
+        yield 'custom protocol' => [new URL(protocols: ['ftp']), 'ftp://test.com'];
+        yield 'allow relative protocol with protocol' => [new URL(allowRelativeProtocol: true), 'https://test.com'];
+        yield 'allow relative protocol without protocol' => [new URL(allowRelativeProtocol: true), '//test.com'];
+        yield 'allow relative protocol only' => [new URL(protocols: [], allowRelativeProtocol: true), '//test.com'];
+        yield 'normalizer' => [new URL(normalizer: 'trim'), 'https://test.com '];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new Url(
+                message: 'The {{ name }} value {{ value }} is not a valid URL address. Allowed protocols: {{ protocols }}.'
+            ),
+            'invalid',
+            'The test value "invalid" is not a valid URL address. Allowed protocols: ["http", "https"].'
+        ];
+    }
+}