Adding new URI related 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;
+}

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;
+}

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