Adding new URIrenderer methods

composer.json

@@ -29,19 +29,20 @@
         "ext-fileinfo": "*",
         "ext-gmp": "*",
         "ext-intl": "*",
-        "friendsofphp/php-cs-fixer": "^3.64.0",
+        "ext-mbstring": "*",
+        "friendsofphp/php-cs-fixer": "^3.65.0",
         "guzzlehttp/psr7": "^2.7.0",
-        "laminas/laminas-diactoros": "^3.4.0",
+        "laminas/laminas-diactoros": "^3.5.0",
         "nyholm/psr7": "^1.8.2",
         "phpbench/phpbench": "^1.3.1",
-        "phpstan/phpstan": "^1.12.4",
+        "phpstan/phpstan": "^1.12.13",
         "phpstan/phpstan-deprecation-rules": "^1.2.1",
-        "phpstan/phpstan-phpunit": "^1.4.0",
-        "phpstan/phpstan-strict-rules": "^1.6.0",
-        "phpunit/phpunit": "^10.5.17 || ^11.3.6",
+        "phpstan/phpstan-phpunit": "^1.4.2",
+        "phpstan/phpstan-strict-rules": "^1.6.1",
+        "phpunit/phpunit": "^10.5.17 || ^11.5.2",
         "psr/http-factory": "^1.1.0",
         "psr/http-message": "^1.1.0 || ^2.0",
-        "symfony/var-dumper": "^6.4.11",
+        "symfony/var-dumper": "^6.4.15",
         "uri-templates/uritemplate-test": "dev-master"
     },
     "repositories": [

docs/uri/7.0/index.md

@@ -46,9 +46,12 @@ as an IPv4 address.
 In order to create Data URI from the content of a file you are required to also
 install the `fileinfo` extension otherwise an exception will be thrown.
 
-To use the `toAnchor` method you need to have the `ext-dom` extension
+To convert a URI into an HTML anchor tag you need to have the `ext-dom` extension
 installed in your system.
 
+To enable URI normalization, the `ext-mbstring` extension or a polyfill
+like `symfony/polyfill-mbstring` must be present in your system.
+
 Installation
 --------
 

docs/uri/7.0/rfc3986.md

@@ -180,6 +180,18 @@ echo $uri->toAnchorTag('my link');
 // display '<a href="example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar">my link</a>'
 ```
 
+You can also generate the Link `tag` and/or `header` depending on how you want your URI link to be rendered:
+
+```php
+use League\Uri\Uri;
+
+$uri = Uri::new('https://example.com/my/css/v1.3');
+echo $uri->toLinkTag(['rel' => 'stylesheet']); 
+//display '<link href="https://example.com/my/css/v1.3" rel="stylesheet">
+echo $uri->toLinkFieldValue(['rel' => 'stylesheet']); 
+//display 'https://example.com/my/css/v1.3 ;rel=stylesheet'
+```
+
 ## Accessing URI properties
 
 Let's examine the result of building a URI:

interfaces/CHANGELOG.md

@@ -14,6 +14,7 @@ All Notable changes to `League\Uri\Interfaces` will be documented in this file
 - `UriInterface::equals`
 - `UriInterface::toNormalizedString`
 - `UriInterface::getUser`
+- `League\Uri\IPv6\Converter::isIpv6`
 
 ### Fixed
 

interfaces/Contracts/UriEncoder.php → interfaces/Contracts/UriRenderer.php

@@ -16,11 +16,15 @@
 use DOMException;
 use JsonSerializable;
 use League\Uri\UriString;
+use RuntimeException;
+use SplFileInfo;
+use SplFileObject;
+use Stringable;
 
 /**
  * @phpstan-import-type ComponentMap from UriString
  */
-interface UriEncoder extends JsonSerializable
+interface UriRenderer extends JsonSerializable
 {
     /**
      * Returns the string representation as a URI reference.
@@ -51,19 +55,37 @@ public function toDisplayString(): ?string;
      */
     public function jsonSerialize(): string;
 
+    /**
+     * Returns the markdown string representation of the anchor tag with the current instance as its href attribute.
+     */
+    public function toMarkdown(?string $linkTextTemplate = null): string;
+
     /**
      * Returns the HTML string representation of the anchor tag with the current instance as its href attribute.
      *
-     * @param list<string>|string|null $class
+     * @param iterable<string, string|null> $attributes an ordered map of key value. you must quote the value if needed
      *
      * @throws DOMException
      */
-    public function toAnchorTag(?string $linkText = null, array|string|null $class = null, ?string $target = null): string;
+    public function toAnchorTag(?string $linkTextTemplate = null, iterable $attributes = []): string;
 
     /**
-     * Returns the markdown string representation of the anchor tag with the current instance as its href attribute.
+     * Returns the Link tag content for the current instance.
+     *
+     * @param iterable<string, string|null> $attributes an ordered map of key value. you must quote the value if needed
+     *
+     * @throws DOMException
      */
-    public function toMarkdown(?string $linkText = null): string;
+    public function toLinkTag(iterable $attributes = []): string;
+
+    /**
+     * Returns the Link header content for a single item.
+     *
+     * @param iterable<string, string|int|float|bool> $parameters an ordered map of key value. you must quote the value if needed
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.6
+     */
+    public function toLinkFieldValue(iterable $parameters = []): string;
 
     /**
      * Returns the Unix filesystem path. The method returns null for any other scheme except the file scheme.
@@ -81,4 +103,23 @@ public function toWindowsPath(): ?string;
      * @return ComponentMap
      */
     public function toComponents(): array;
+
+    /**
+     * Returns a string representation of a File URI according to RFC8089.
+     *
+     * The method will return null if the URI scheme is not the `file` scheme
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8089
+     */
+    public function toRfc8089(): ?string;
+
+    /**
+     * Save the data to a specific file. The method returns null for any other scheme except the data scheme.
+     *
+     * @param SplFileInfo|SplFileObject|resource|Stringable|string $destination
+     * @param ?resource $context
+     *
+     * @throws RuntimeException if the content can not be saved.
+     */
+    public function toFileContents(mixed $destination, $context = null): ?int;
 }

interfaces/IPv6/Converter.php

@@ -134,4 +134,12 @@ private static function parse(Stringable|string|null $host): array
             default => ['ipAddress' => null, 'zoneIdentifier' => null],
         };
     }
+
+    /**
+     * Tells whether the host is an IPv6.
+     */
+    public static function isIpv6(Stringable|string|null $host): bool
+    {
+        return null !== self::parse($host)['ipAddress'];
+    }
 }

interfaces/IPv6/ConverterTest.php

@@ -81,4 +81,23 @@ public static function invalidIpv6(): iterable
 
         yield 'IPv6 with zoneIdentifier' => ['invalidIp' => 'fe80::a%25en1'];
     }
+
+    #[DataProvider('providerInvalidHost')]
+    public function testParseWithInvalidHost(?string $input): void
+    {
+        self::assertFalse(Converter::isIpv6($input));
+    }
+
+    public static function providerInvalidHost(): array
+    {
+        return [
+            'null host' => ['input' => null],
+            'empty host' => ['input' => ''],
+            'non ip host' => ['input' => 'ulb.ac.be'],
+            'invalid host (0)' => ['input' => '192.168.1.1'],
+            'invalid host (1)' => ['input' => '[192.168.1.1]'],
+            'invalid host (2)' => ['input' => 'v42.fdfsffd'],
+            'invalid host (3)' => ['input' => '::1'],
+        ];
+    }
 }

uri/BaseUri.php

@@ -24,6 +24,7 @@
 use Psr\Http\Message\UriFactoryInterface;
 use Psr\Http\Message\UriInterface as Psr7UriInterface;
 use Stringable;
+use Throwable;
 
 use function array_map;
 use function array_pop;
@@ -71,6 +72,15 @@ public static function from(Stringable|string $uri, ?UriFactoryInterface $uriFac
         return new static(static::formatHost(static::filterUri($uri, $uriFactory)), $uriFactory);
     }
 
+    public static function tryFrom(Stringable|string $uri, ?UriFactoryInterface $uriFactory = null): ?static
+    {
+        try {
+            return self::from($uri, $uriFactory);
+        } catch (Throwable) {
+            return null;
+        }
+    }
+
     public function withUriFactory(UriFactoryInterface $uriFactory): static
     {
         return new static($this->uri, $uriFactory);

uri/CHANGELOG.md

@@ -6,33 +6,15 @@ All Notable changes to `League\Uri` will be documented in this file
 
 ### Added
 
+- Added methods to align with the upcoming `Uri\Rfc3986Uri` PHP native class (see: https://wiki.php.net/rfc/url_parsing_api#proposal)
+- `Uri::tryNew` returns a new `Uri` instance on success or null on failure (ie: a Relax version of `Uri::new`).
+- `Http::tryNew` returns a new `Uri` instance on success or null on failure (ie: a Relax version of `Http::new`).
+- `BaseUri::tryfrom` returns a new `BaseUri` instance on success or null on failure (ie: a Relax version of `BaseUri::from`).
 - `BaseUri::when` conditional method to ease component building logic.
 - `Http::when` conditional method to ease component building logic.
-- `Http::tryNew` returns a new `Uri` instance on success or null on failure.
 - `Uri::when` conditional method to ease component building logic.
-- `Uri::tryNew` returns a new `Uri` instance on success or null on failure.
-- `Uri::resolve`
-- `Uri::relativize`
-- `Uri::isAbsolute`
-- `Uri::isNetworkPath`
-- `Uri::isAbsolutePath`
-- `Uri::isRelativePath`
-- `Uri::isSameDocument`
-- `Uri::equals`
-- `Uri::toNormalizedString`
-- `Uri::getOrigin`
-- `Uri::isSameOrigin`
-- `Uri::isCrossOrigin`
-- `Uri::todisplayString` shows the URI in a human-readable format which may be an invalid URI.
-- `Uri::toUnixPath` returns the URI path as a Unix Path or `null`
-- `Uri::toWindowsPath` returns the URI path as a Windows Path or `null`
-- `Uri::toRfc8089` return the URI in a RFC8089 formator `null`
-- `Uri::toAnchor` returns the HTML anchor string using the instance as the href attribute value
-- `Uri::toMarkdown` returns the markdown link construct using the instance as the href attribute value
-- `Uri::getUser` to be inline with PHP native URI interface
-- `Uri::withUser` to be inline with PHP native URI interface
-- `Uri::withPassword` to be inline with PHP native URI interface
-- `Uri::__serialize` and `Uri::__unserialize` methods
+- `Uri` implements the new `League\Uri\Contract\UriInspector` interface
+- `Uri` implements the new `League\Uri\Contract\UriRenderer` interface
 
 ### Fixed