Move extra string representation fron Uri to Modifier class

Author: nyamsprod

components/CHANGELOG.md

@@ -18,6 +18,8 @@ All Notable changes to `League\Uri\Components` will be documented in this file
 - `Modifier::wrap` static method which wraps the underlying URI object used by the Modifier class.
 - `Modifier::unwrap` method which returns the underlying URI object used by the Modifier class.
 - `Modifier::prefixQueryPairs` and `Modifier::prefixQueryParameters` to prefix Query using the pair key or the parameter names
+- `Modifier::toMarkdownAnchor` returns the Markdown string representation of the anchor tag with the current instance as its href attribute.
+- `Modifier::toHtmlAnchor` returns the HTML string representation of the anchor tag with the current instance as its href attribute.
 - `tryNew` named constructor added to all classes to return a new instance on success or `null` on failure.
 - `Query::decoded` the string representation of the component decoded.
 - `Query::normalized`

components/Modifier.php

@@ -115,9 +115,9 @@ public function toDisplayString(): string
     /**
      * Returns the Markdown string representation of the anchor tag with the current instance as its href attribute.
      */
-    public function toMarkdownAnchor(?string $linkTextTemplate = null): string
+    public function toMarkdownAnchor(?string $textContent = null): string
     {
-        return '['.strtr($linkTextTemplate ?? '{uri}', ['{uri}' => $this->toDisplayString()]).']('.$this->toString().')';
+        return '['.strtr($textContent ?? '{uri}', ['{uri}' => $this->toDisplayString()]).']('.$this->toString().')';
     }
 
     /**
@@ -127,14 +127,18 @@ public function toMarkdownAnchor(?string $linkTextTemplate = null): string
      *
      * @throws DOMException
      */
-    public function toHtmlAnchor(?string $linkTextTemplate = null, iterable $attributes = []): string
+    public function toHtmlAnchor(Stringable|string|null $textContent = null, iterable $attributes = []): string
     {
         FeatureDetection::supportsDom();
-
+        $uriString = $this->toString();
+        $rfc3987String = UriString::toIriString($uriString);
         $doc = class_exists(HTMLDocument::class) ? HTMLDocument::createEmpty() : new DOMDocument(encoding:'utf-8');
         $element = $doc->createElement('a');
-        $element->setAttribute('href', $this->toString());
-        $element->appendChild($doc->createTextNode(strtr($linkTextTemplate ?? '{uri}', ['{uri}' => $this->toDisplayString()])));
+        $element->setAttribute('href', $uriString);
+        $element->appendChild(match (true) {
+            null === $textContent => $doc->createTextNode($rfc3987String),
+            default => $doc->createTextNode(strtr((string) $textContent, ['{uri}' => $rfc3987String])),
+        });
 
         foreach ($attributes as $name => $value) {
             if ('href' === strtolower($name) || null === $value) {
@@ -154,8 +158,7 @@ public function toHtmlAnchor(?string $linkTextTemplate = null, iterable $attribu
             $element->setAttribute($name, $value);
         }
 
-        $html = $doc->saveHTML($element);
-        false !== $html || throw new DOMException('The HTML generation failed.');
+        false !== ($html = $doc->saveHTML($element)) || throw new DOMException('The HTML generation failed.');
 
         return $html;
     }

components/ModifierTest.php

@@ -11,6 +11,7 @@
 
 namespace League\Uri;
 
+use DOMException;
 use GuzzleHttp\Psr7\Utils;
 use League\Uri\Components\DataPath;
 use League\Uri\Components\FragmentDirectives;
@@ -1115,4 +1116,101 @@ public static function resolveProvider(): array
             'not same origin'         => [self::BASE_URI, 'ftp://a/b/c/d', 'ftp://a/b/c/d'],
         ];
     }
+
+    #[Test]
+    #[DataProvider('providesUriToMarkdown')]
+    public function it_will_generate_the_markdown_code_for_the_instance(string $uri, ?string $content, string $expected): void
+    {
+        self::assertSame($expected, Modifier::wrap($uri)->toMarkdownAnchor($content));
+    }
+
+    public static function providesUriToMarkdown(): iterable
+    {
+        yield 'empty string' => [
+            'uri' => '',
+            'content' => '',
+            'expected' => '[]()',
+        ];
+
+        yield 'URI with a specific content' => [
+            'uri' => 'http://example.com/foo/bar',
+            'content' => 'this is a link',
+            'expected' => '[this is a link](http://example.com/foo/bar)',
+        ];
+
+        yield 'URI without content' => [
+            'uri' => 'http://Bébé.be',
+            'content' => null,
+            'expected' => '[http://bébé.be](http://xn--bb-bjab.be)',
+        ];
+    }
+
+    #[Test]
+    #[DataProvider('providesUriToAnchorTagHTML')]
+    public function it_will_generate_the_html_anchor_tag_code_for_the_instance(string $uri, ?string $content, array $parameters, string $expected): void
+    {
+        self::assertSame($expected, Modifier::wrap($uri)->toHtmlAnchor($content, $parameters));
+    }
+
+    public static function providesUriToAnchorTagHTML(): iterable
+    {
+        yield 'empty string' => [
+            'uri' => '',
+            'content' => '',
+            'parameters' => [],
+            'expected' => '<a href=""></a>',
+        ];
+
+        yield 'URI with a specific content' => [
+            'uri' => 'http://example.com/foo/bar',
+            'content' => 'this is a link',
+            'parameters' => [],
+            'expected' => '<a href="http://example.com/foo/bar">this is a link</a>',
+        ];
+
+        yield 'URI without content' => [
+            'uri' => 'http://Bébé.be',
+            'content' => null,
+            'parameters' => [],
+            'expected' => '<a href="http://xn--bb-bjab.be">http://bébé.be</a>',
+        ];
+
+        yield 'URI without content and with class' => [
+            'uri' => 'http://Bébé.be',
+            'content' => null,
+            'parameters' => [
+                'class' => ['foo', 'bar'],
+                'target' => null,
+            ],
+            'expected' => '<a href="http://xn--bb-bjab.be" class="foo bar">http://bébé.be</a>',
+        ];
+
+        yield 'URI without content and with target' => [
+            'uri' => 'http://Bébé.be',
+            'content' => null,
+            'parameters' => [
+                'class' => null,
+                'target' => '_blank',
+            ],
+            'expected' => '<a href="http://xn--bb-bjab.be" target="_blank">http://bébé.be</a>',
+        ];
+
+        yield 'URI without content, with target and class' => [
+            'uri' => 'http://Bébé.be',
+            'content' => null,
+            'parameters' => [
+                'class' => 'foo bar',
+                'target' => '_blank',
+            ],
+            'expected' => '<a href="http://xn--bb-bjab.be" class="foo bar" target="_blank">http://bébé.be</a>',
+        ];
+    }
+
+    #[Test]
+    public function it_will_fail_to_generate_an_anchor_tag_html_for_the_instance(): void
+    {
+        $this->expectException(DOMException::class);
+
+        Modifier::wrap('https://example.com')->toHtmlAnchor(attributes: ["bébé\r\n" => 'yes']);
+    }
 }

components/composer.json

@@ -38,6 +38,7 @@
         "ext-gmp": "to improve IPV4 host parsing",
         "ext-intl": "to handle IDN host with the best performance",
         "jeremykendall/php-domain-parser": "to resolve Public Suffix and Top Level Domain",
+        "league/uri-polyfill" : "Needed to backport the PHP URI extension for older versions of PHP",
         "php-64bit": "to improve IPV4 host parsing",
         "symfony/polyfill-intl-idn": "to handle IDN host via the Symfony polyfill if ext-intl is not present",
         "rowbot/url": "to handle WHATWG URL",

docs/uri/7.0/rfc3986.md

@@ -105,19 +105,6 @@ echo $uri = //returns 'file:///etc/fstab'
 
 <p class="message-info"><code>fromRfc8089</code> is added since version <code>7.4.0</code></p>
 
-It is also possible to instantiate a new instance from the following HTTP related object or string>
-
-~~~php
-$uri = Uri::fromMarkdownAnchor('[overview](https://uri.thephpleague.com/uri/7.0/)');
-echo $uri; //returns 'https://uri.thephpleague.com/uri/7.0/'
-
-$uri = Uri::fromHtmlAnchor('<a href="/domain-parser/1.0/">uri-hostname-parser</a>');
-echo $uri; //returns '/domain-parser/1.0/'
-~~~
-
-<p class="message-info">The named constructor are available since version <code>7.6.0</code></p>
-<p class="message-notice">To use the named constructor in relation to HTML tag, the <code>ext-dom</code> extension must be present.</p>
-
 ## URI string representation
 
 The `Uri` class handles URI according to RFC3986 as such you can retrieve its string representation using the
@@ -133,7 +120,7 @@ echo $uri;             //displays RFC3986 string representation
 But `Uri` can have multiple string representation depending on its scheme or context. As
 such the package provides several other string representations.
 
-The `Uri` instance can be json encoded using the same URI representation from JavaScript to allow
+The `Uri` instance can be JSON encoded using the same URI representation from JavaScript to allow
 easier interoperability
 
 ```php
@@ -154,21 +141,7 @@ echo $uri->toString();        //displays 'example://a/./b/../b/%63/%7bfoo%7d?foo
 echo $uri->toDisplayString(); //displays 'example://a/./b/../b/c/{foo}?foo[]=bar'
 ````
 
-HTML specific representation are added to allow adding URI to your HTML/Markdown page.
-
-```php
-$uri = Uri::new('eXAMPLE://a/./b/../b/%63/%7bfoo%7d?foo[]=bar');
-echo $uri->toMarkdownAnchor(); 
-//display '[example://a/b/c/{foo}?foo[]=bar](example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar)
-echo $uri->toMarkdownAnchor('my link'); 
-//display '[my link](example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar)
-echo $uri->toHtmlAnchor(); 
-// display '<a href="example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar">example://a/b/c/{foo}?foo[]=bar</a>'
-echo $uri->toHtmlAnchor('my link', ['class' => ['red', 'notice']]); 
-// display '<a class="red notice" href="example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar">my link</a>'
-```
-
-File specific representation are added to allow representing Unix and Windows Path.
+For `file` scheme, specifics representations are added to allow representing Unix and Windows Path.
 
 ```php
 $uri = Uri::new('file:///c:/windows/My%20Documents%20100%2520/foo.txt');

interfaces/UriString.php

@@ -20,6 +20,7 @@
 use Stringable;
 use Throwable;
 
+use function array_map;
 use function array_merge;
 use function array_pop;
 use function array_reduce;
@@ -33,6 +34,7 @@
 use function preg_match;
 use function rawurldecode;
 use function sprintf;
+use function str_replace;
 use function strpos;
 use function strtolower;
 use function substr;
@@ -194,6 +196,45 @@ final class UriString
      */
     private const MAXIMUM_HOST_CACHED = 100;
 
+    /**
+     * Generate an IRI string representation (RFC3987) from its parsed representation
+     * returned by League\UriString::parse() or PHP's parse_url.
+     *
+     * If you supply your own array, you are responsible for providing
+     * valid components without their URI delimiters.
+     *
+     * @link https://tools.ietf.org/html/rfc3986#section-5.3
+     * @link https://tools.ietf.org/html/rfc3986#section-7.5
+     */
+    public static function toIriString(Stringable|string $uri): string
+    {
+        $components = UriString::parse($uri);
+        $port = null;
+        if (isset($components['port'])) {
+            $port = (int) $components['port'];
+            unset($components['port']);
+        }
+
+        if (null !== $components['host']) {
+            $components['host'] = IdnaConverter::toUnicode($components['host'])->domain();
+        }
+
+        $components['path'] = Encoder::decodePath($components['path']);
+        $components['user'] = Encoder::decodeNecessary($components['user']);
+        $components['pass'] = Encoder::decodeNecessary($components['pass']);
+        $components['query'] = Encoder::decodeQuery($components['query']);
+        $components['fragment'] = Encoder::decodeFragment($components['fragment']);
+
+        return self::build([
+            ...array_map(fn (?string $value) => match (true) {
+                null === $value,
+                !str_contains($value, '%20') => $value,
+                default => str_replace('%20', ' ', $value),
+            }, $components),
+            ...['port' => $port],
+        ]);
+    }
+
     /**
      * Generate a URI string representation from its parsed representation
      * returned by League\UriString::parse() or PHP's parse_url.

phpstan-dist.neon

@@ -8,6 +8,7 @@ parameters:
 		- uri
 		- components
 		- interfaces
+		- polyfill
 	ignoreErrors:
 		- message: '#Cannot cast mixed to string.#'
 		  path: interfaces/IPv4/BCMathCalculator.php
@@ -18,6 +19,5 @@ parameters:
 		- identifier: missingType.iterableValue
 		- '#deprecated class League\\Uri\\BaseUri#'
 		- '#deprecated interface League\\Uri\\Contracts\\UriAccess#'
-		- '#\Dom\\HTMLDocument#'
 	reportUnmatchedIgnoredErrors: true
 	treatPhpDocTypesAsCertain: false

phpstan.neon

@@ -20,6 +20,5 @@ parameters:
 		- '#Attribute class Deprecated does not exist.#'
 		- '#deprecated class League\\Uri\\BaseUri#'
 		- '#deprecated interface League\\Uri\\Contracts\\UriAccess#'
-		- '#\Dom\\HTMLDocument#'
 	reportUnmatchedIgnoredErrors: true
 	treatPhpDocTypesAsCertain: false

polyfill/lib/WhatWg/Url.php

@@ -223,7 +223,7 @@ private function setUnicodeHost(): ?string
             return $result->getDomain();
         }
 
-        private function setAsciiHost(): ?string
+        private function setAsciiHost(): string
         {
             $host = $this->url->hostname;
             if ('' === $host || null === $host || 1 !== preg_match(self::REGEXP_IDNA_PATTERN, $host)) {

uri/CHANGELOG.md

@@ -23,8 +23,6 @@ All Notable changes to `League\Uri` will be documented in this file
 - `Uri::isSameOrigin` tells whether two URI share the same origin.
 - `Uri::getOrigin` returns the URI origin as described in the WHATWG URL Living standard specification.
 - `Uri::toDisplayString` returns the human-readable string representation of the URI as an IRI.
-- `Uri::toMarkdownAnchor` returns the Markdown string representation of the anchor tag with the current instance as its href attribute.
-- `Uri::toHtmlAnchor` returns the HTML string representation of the anchor tag with the current instance as its href attribute.
 - `Uri::fromMarkdownAnchor` create a new instance from a Markdown code. The first URI found is returned.
 - `Uri::fromHtmlAnchor`  create a new instance from an HTML code. The first URI found is returned.
 - `Uri::toRfc8089` The method will return null if the URI scheme is not the `file` scheme