Adding new URI related interfaces

composer.json

@@ -25,6 +25,7 @@
     "require": {
         "php": "^8.1",
         "ext-bcmath": "*",
+        "ext-dom": "*",
         "ext-fileinfo": "*",
         "ext-gmp": "*",
         "ext-intl": "*",

docs/uri/7.0/index.md

@@ -46,6 +46,9 @@ 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
+installed in your system.
+
 Installation
 --------
 

docs/uri/7.0/rfc3986.md

@@ -149,7 +149,7 @@ echo $uri->toNormalizedString(); //displays 'example://a/b/c/%7Bfoo%7D?foo%5B%5D
 echo $uri->toDisplayString();    //displays 'example://a/b/c/{foo}?foo[]=bar'
 ````
 
-File specific representation are also added to allow representing Unix and Windows Path.
+File specific representation are added to allow representing Unix and Windows Path.
 
 ```php
 use League\Uri\Uri;
@@ -164,6 +164,22 @@ $uri = Uri::new('file://localhost/etc/fstab');
 echo $uri->toRfc8089();    //display 'file:/etc/fstab'
 ```
 
+HTML specific representation are added to allow adding URI to your HTML/Markdown page.
+
+```php
+use League\Uri\Uri;
+
+$uri = Uri::new('eXAMPLE://a/./b/../b/%63/%7bfoo%7d?foo[]=bar');
+echo $uri->toMarkdown(); 
+//display '[example://a/b/c/{foo}?foo[]=bar](example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar)
+echo $uri->toMarkdown('my link'); 
+//display '[my link](example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar)
+echo $uri->toAnchorTag(); 
+// display '<a href="example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar">example://a/b/c/{foo}?foo[]=bar</a>'
+echo $uri->toAnchorTag('my link'); 
+// display '<a href="example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar">my link</a>'
+```
+
 ## Accessing URI properties
 
 Let's examine the result of building a URI:

interfaces/Contracts/UriEncoder.php

@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * League.Uri (https://uri.thephpleague.com)
+ *
+ * (c) Ignace Nyamagana Butera <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace League\Uri\Contracts;
+
+use DOMException;
+use JsonSerializable;
+use League\Uri\UriString;
+
+/**
+ * @phpstan-import-type ComponentMap from UriString
+ */
+interface UriEncoder extends JsonSerializable
+{
+    /**
+     * Returns the string representation as a URI reference.
+     *
+     * @see http://tools.ietf.org/html/rfc3986#section-4.1
+     */
+    public function toString(): string;
+
+    /**
+     * Returns the normalized string representation of the URI.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc3986#section-6.2
+     */
+    public function toNormalizedString(): ?string;
+
+    /**
+     * Returns the human-readable string representation of the URI.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc3986#section-6.2
+     */
+    public function toDisplayString(): ?string;
+
+    /**
+     * Returns the string representation as a URI reference.
+     *
+     * @see http://tools.ietf.org/html/rfc3986#section-4.1
+     * @see ::__toString
+     */
+    public function jsonSerialize(): string;
+
+    /**
+     * Returns the HTML string representation of the anchor tag with the current instance as its href attribute.
+     *
+     * @param list<string>|string|null $class
+     *
+     * @throws DOMException
+     */
+    public function toAnchorTag(?string $linkText = null, array|string|null $class = null, ?string $target = null): string;
+
+    /**
+     * Returns the markdown string representation of the anchor tag with the current instance as its href attribute.
+     */
+    public function toMarkdown(?string $linkText = null): string;
+
+    /**
+     * Returns the Unix filesystem path. The method returns null for any other scheme except the file scheme.
+     */
+    public function toUnixPath(): ?string;
+
+    /**
+     * Returns the Windows filesystem path. The method returns null for any other scheme except the file scheme.
+     */
+    public function toWindowsPath(): ?string;
+
+    /**
+     * Returns an associative array containing all the URI components.
+     *
+     * @return ComponentMap
+     */
+    public function toComponents(): array;
+}

interfaces/Contracts/UriInspector.php

@@ -0,0 +1,76 @@
+<?php
+
+/**
+ * League.Uri (https://uri.thephpleague.com)
+ *
+ * (c) Ignace Nyamagana Butera <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace League\Uri\Contracts;
+
+interface UriInspector
+{
+    /**
+     * Tells whether the URI instance represents an opaque URI.
+     */
+    public function isOpaque(): bool;
+
+    /**
+     * Tells whether the URI represents an absolute URI.
+     */
+    public function isAbsolute(): bool;
+
+    /**
+     * Tells whether the URI represents a network path URI.
+     */
+    public function isNetworkPath(): bool;
+
+    /**
+     * Tells whether the URI represents an absolute URI path.
+     */
+    public function isAbsolutePath(): bool;
+
+    /**
+     * Tells whether the given URI object represents a relative path.
+     */
+    public function isRelativePath(): bool;
+
+    /**
+     * Tells whether the given URI object represents the same document.
+     *
+     * It never takes the fragment into account
+     */
+    public function isSameDocument(UriInterface $uri): bool;
+
+    /**
+     * Tells whether the given URI object represents the same document.
+     *
+     * It can take the fragment into account if it is explicitly specified
+     */
+    public function equals(UriInterface $uri, bool $excludeFragment): bool;
+
+    /**
+     * Tells whether the `file` scheme base URI represents a local file.
+     */
+    public function isLocalFile(): bool;
+
+    /**
+     * Tells whether the URI comes from a different origin than the current instance.
+     */
+    public function isCrossOrigin(UriInterface $uri): bool;
+
+    /**
+     * Tells whether the URI shares the same origin as the current instance.
+     */
+    public function isSameOrigin(UriInterface $uri): bool;
+
+    /**
+     * Returns the URI origin as described in the WHATWG URL Living standard specification.
+     */
+    public function getOrigin(): ?string;
+}

interfaces/Contracts/UriInterface.php

@@ -22,26 +22,14 @@
 /**
  * @phpstan-import-type ComponentMap from UriString
  *
- * @method string|null getUsername() returns the user component of the URI.
+ * @method string|null getUsername() returns the user component of the URI (deprecated).
+ * @method string|null getUser() returns the user component of the URI.
  * @method string|null getPassword() returns the scheme-specific information about how to gain authorization to access the resource.
- * @method string|null toUnixPath() returns the Unix filesystem path. The method returns null for any other scheme
- * @method string|null toWindowsPath() returns the Windows filesystem path. The method returns null for any other scheme
- * @method string|null toRfc8089() returns a string representation of a File URI according to RFC8089. The method returns null for any other scheme
  * @method string toNormalizedString() returns the normalized string representation of the URI
  * @method array toComponents() returns an associative array containing all the URI components.
  * @method self normalize() returns a new URI instance with normalized components
  * @method self resolve(UriInterface $uri) resolves a URI against a base URI using RFC3986 rules
  * @method self relativize(UriInterface $uri) relativize a URI against a base URI using RFC3986 rules
- * @method self|null getOrigin() returns the URI origin as described in the WHATWG URL Living standard specification
- * @method bool isOpaque() tells whether the given URI object represents an opaque URI.
- * @method bool isAbsolute() tells whether the URI represents an absolute URI.
- * @method bool isNetworkPath() tells whether the URI represents a network path URI.
- * @method bool isAbsolutePath() tells whether the URI represents an absolute URI path.
- * @method bool isRelativePath() tells whether the given URI object represents a relative path.
- * @method bool isCrossOrigin(UriInterface $uri) tells whether the URI comes from a different origin than the current instance.
- * @method bool isSameOrigin(UriInterface $uri) tells whether the URI comes from the same origin as the current instance.
- * @method bool isSameDocument(UriInterface $uri) tells whether the given URI object represents the same document.
- * @method bool isLocalFile() tells whether the `file` scheme base URI represents a local file.
  * @method bool equals(UriInterface $uri, bool $excludeFragment) tells whether the given URI object represents the same document. It can take the fragment in account if it is explicitly specified
  */
 interface UriInterface extends JsonSerializable, Stringable

uri/CHANGELOG.md

@@ -27,6 +27,8 @@ All Notable changes to `League\Uri` will be documented in this file
 - `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
 
 ### Fixed