From ab996be9f2326eb29960b0871c83d770892f8612 Mon Sep 17 00:00:00 2001 From: ignace nyamagana butera Date: Wed, 25 Dec 2024 14:59:54 +0100 Subject: [PATCH] Adding new URI related interfaces --- Contracts/UriEncoder.php | 84 ++++++++++++++++++++++++++++++++++++++ Contracts/UriInspector.php | 76 ++++++++++++++++++++++++++++++++++ Contracts/UriInterface.php | 16 +------- 3 files changed, 162 insertions(+), 14 deletions(-) create mode 100644 Contracts/UriEncoder.php create mode 100644 Contracts/UriInspector.php diff --git a/Contracts/UriEncoder.php b/Contracts/UriEncoder.php new file mode 100644 index 0000000..b37286a --- /dev/null +++ b/Contracts/UriEncoder.php @@ -0,0 +1,84 @@ + + * + * 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|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; +} diff --git a/Contracts/UriInspector.php b/Contracts/UriInspector.php new file mode 100644 index 0000000..7e7b12d --- /dev/null +++ b/Contracts/UriInspector.php @@ -0,0 +1,76 @@ + + * + * 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; +} diff --git a/Contracts/UriInterface.php b/Contracts/UriInterface.php index 0cfafe7..688c30f 100644 --- a/Contracts/UriInterface.php +++ b/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