From 081760c53a4ce76c9935a755a21353610f5495f6 Mon Sep 17 00:00:00 2001 From: Ignace Nyamagana Butera Date: Mon, 5 Nov 2018 14:55:40 +0100 Subject: [PATCH] improve deprecation --- .php_cs | 5 +- CHANGELOG.md | 18 +++ README.md | 7 +- src/Interfaces/Uri.php | 320 +---------------------------------------- src/UriInterface.php | 2 +- 5 files changed, 30 insertions(+), 322 deletions(-) diff --git a/.php_cs b/.php_cs index 54a762d..4c7e007 100644 --- a/.php_cs +++ b/.php_cs @@ -20,7 +20,6 @@ $finder = PhpCsFixer\Finder::create() ; return PhpCsFixer\Config::create() - ->setUsingCache(false) ->setRules([ '@PSR2' => true, 'array_syntax' => ['syntax' => 'short'], @@ -37,14 +36,16 @@ return PhpCsFixer\Config::create() 'no_empty_comment' => true, 'no_leading_import_slash' => true, 'no_trailing_comma_in_singleline_array' => true, + 'no_superfluous_phpdoc_tags' => true, 'no_unused_imports' => true, - 'ordered_imports' => ['importsOrder' => null, 'sortAlgorithm' => 'alpha'], + 'ordered_imports' => ['imports_order' => ['class', 'function', 'const'], 'sort_algorithm' => 'alpha'], 'phpdoc_add_missing_param_annotation' => ['only_untyped' => false], 'phpdoc_align' => true, 'phpdoc_no_empty_return' => true, 'phpdoc_order' => true, 'phpdoc_scalar' => true, 'phpdoc_to_comment' => true, + 'phpdoc_summary' => true, 'psr0' => true, 'psr4' => true, 'return_type_declaration' => ['space_before' => 'none'], diff --git a/CHANGELOG.md b/CHANGELOG.md index f5604a9..c07ca93 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,24 @@ All Notable changes to `League\Uri\Interfaces` will be documented in this file +## 1.1.1 - 2018-11-05 + +### Added + +- None + +### Fixed + +- Make `League\Uri\Interfaces\Uri` implements `League\Uri\UriInterface` + +### Deprecated + +- None + +### Removed + +- None + ## 1.1.0 - 2018-05-22 ### Added diff --git a/README.md b/README.md index cee14fc..79185fa 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,10 @@ $ composer require league/uri-interfaces Documentation -------- -### League\Uri\Interfaces\Uri +**WARNING: since version 1.1.1 The `League\Uri\Interfaces\Uri` extends the `League\Uri\UriInterface` interface. +You shoud implements the `League\Uri\UriInterface`**. + +### League\Uri\UriInterface The `Uri` interface models generic URIs as specified in [RFC 3986](http://tools.ietf.org/html/rfc3986). The interface provides methods for interacting with the various URI parts, which will obviate the need for repeated parsing of the URI. It also specifies a `__toString()` method for casting the modeled URI to its string representation. @@ -64,7 +67,7 @@ public Uri::withFragment(string $fragment): self #### Relation with [PSR-7](http://www.php-fig.org/psr/psr-7/#3-5-psr-http-message-uriinterface) -This interface exposes the same methods as `Psr\Http\Message\UriInterface`. But, unlike the `UriInterface`, this interface does not require the `http` and `https` schemes to be supported. The supported schemes are determined by the each concrete implementation. +This interface exposes the same methods as `Psr\Http\Message\UriInterface`. But, unlike the `UriInterface`, this interface does not require the `http` and `https` schemes to be supported. The supported schemes are determined by each concrete implementation. Contributing ------- diff --git a/src/Interfaces/Uri.php b/src/Interfaces/Uri.php index 95aabeb..0123736 100644 --- a/src/Interfaces/Uri.php +++ b/src/Interfaces/Uri.php @@ -1,7 +1,7 @@ * @since 1.0.0 */ -interface Uri +interface Uri extends UriInterface { - /** - * Retrieve the scheme component of the URI. - * - * If no scheme is present, this method MUST return an empty string. - * - * The value returned MUST be normalized to lowercase, per RFC 3986 - * Section 3.1. - * - * The trailing ":" character is not part of the scheme and MUST NOT be - * added. - * - * @see https://tools.ietf.org/html/rfc3986#section-3.1 - * - * @return string The URI scheme. - */ - public function getScheme(); - - /** - * Retrieve the authority component of the URI. - * - * If no authority information is present, this method MUST return an empty - * string. - * - * The authority syntax of the URI is: - * - * 
-     * [user-info@]host[:port]
-     *
- * - * If the port component is not set or is the standard port for the current - * scheme, it SHOULD NOT be included. - * - * @see https://tools.ietf.org/html/rfc3986#section-3.2 - * - * @return string The URI authority, in "[user-info@]host[:port]" format. - */ - public function getAuthority(); - - /** - * Retrieve the user information component of the URI. - * - * If no user information is present, this method MUST return an empty - * string. - * - * If a user is present in the URI, this will return that value; - * additionally, if the password is also present, it will be appended to the - * user value, with a colon (":") separating the values. - * - * The trailing "@" character is not part of the user information and MUST - * NOT be added. - * - * @return string The URI user information, in "username[:password]" format. - */ - public function getUserInfo(); - - /** - * Retrieve the host component of the URI. - * - * If no host is present, this method MUST return an empty string. - * - * The value returned MUST be normalized to lowercase, per RFC 3986 - * Section 3.2.2. - * - * @see http://tools.ietf.org/html/rfc3986#section-3.2.2 - * - * @return string The URI host. - */ - public function getHost(); - - /** - * Retrieve the port component of the URI. - * - * If a port is present, and it is non-standard for the current scheme, - * this method MUST return it as an integer. If the port is the standard port - * used with the current scheme, this method SHOULD return null. - * - * If no port is present, and no scheme is present, this method MUST return - * a null value. - * - * If no port is present, but a scheme is present, this method MAY return - * the standard port for that scheme, but SHOULD return null. - * - * @return null|int The URI port. - */ - public function getPort(); - - /** - * Retrieve the path component of the URI. - * - * The path can either be empty or absolute (starting with a slash) or - * rootless (not starting with a slash). Implementations MUST support all - * three syntaxes. - * - * Normally, the empty path "" and absolute path "/" are considered equal as - * defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically - * do this normalization because in contexts with a trimmed base path, e.g. - * the front controller, this difference becomes significant. It's the task - * of the user to handle both "" and "/". - * - * The value returned MUST be percent-encoded, but MUST NOT double-encode - * any characters. To determine what characters to encode, please refer to - * RFC 3986, Sections 2 and 3.3. - * - * As an example, if the value should include a slash ("/") not intended as - * delimiter between path segments, that value MUST be passed in encoded - * form (e.g., "%2F") to the instance. - * - * @see https://tools.ietf.org/html/rfc3986#section-2 - * @see https://tools.ietf.org/html/rfc3986#section-3.3 - * - * @return string The URI path. - */ - public function getPath(); - - /** - * Retrieve the query string of the URI. - * - * If no query string is present, this method MUST return an empty string. - * - * The leading "?" character is not part of the query and MUST NOT be - * added. - * - * The value returned MUST be percent-encoded, but MUST NOT double-encode - * any characters. To determine what characters to encode, please refer to - * RFC 3986, Sections 2 and 3.4. - * - * As an example, if a value in a key/value pair of the query string should - * include an ampersand ("&") not intended as a delimiter between values, - * that value MUST be passed in encoded form (e.g., "%26") to the instance. - * - * @see https://tools.ietf.org/html/rfc3986#section-2 - * @see https://tools.ietf.org/html/rfc3986#section-3.4 - * - * @return string The URI query string. - */ - public function getQuery(); - - /** - * Retrieve the fragment component of the URI. - * - * If no fragment is present, this method MUST return an empty string. - * - * The leading "#" character is not part of the fragment and MUST NOT be - * added. - * - * The value returned MUST be percent-encoded, but MUST NOT double-encode - * any characters. To determine what characters to encode, please refer to - * RFC 3986, Sections 2 and 3.5. - * - * @see https://tools.ietf.org/html/rfc3986#section-2 - * @see https://tools.ietf.org/html/rfc3986#section-3.5 - * - * @return string The URI fragment. - */ - public function getFragment(); - - /** - * Return an instance with the specified scheme. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified scheme. - * - * An empty scheme is equivalent to removing the scheme. - * - * @param string $scheme The scheme to use with the new instance. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * @return self A new instance with the specified scheme. - */ - public function withScheme($scheme); - - /** - * Return an instance with the specified user information. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified user information. - * - * Password is optional, but the user information MUST include the - * user; an empty string for the user is equivalent to removing user - * information. - * - * @param string $user The user name to use for authority. - * @param null|string $password The password associated with $user. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * @return self A new instance with the specified user information. - */ - public function withUserInfo($user, $password = null); - - /** - * Return an instance with the specified host. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified host. - * - * An empty host value is equivalent to removing the host. - * - * @param string $host The hostname to use with the new instance. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * - * @return self A new instance with the specified host. - */ - public function withHost($host); - - /** - * Return an instance with the specified port. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified port. - * - * Implementations MUST raise an exception for ports outside the - * established TCP and UDP port ranges. - * - * A null value provided for the port is equivalent to removing the port - * information. - * - * @param null|int $port The port to use with the new instance; a null value - * removes the port information. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * @return self A new instance with the specified port. - */ - public function withPort($port); - - /** - * Return an instance with the specified path. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified path. - * - * The path can either be empty or absolute (starting with a slash) or - * rootless (not starting with a slash). Implementations MUST support all - * three syntaxes. - * - * Users can provide both encoded and decoded path characters. - * Implementations ensure the correct encoding as outlined in getPath(). - * - * @param string $path The path to use with the new instance. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * @return self A new instance with the specified path. - */ - public function withPath($path); - - /** - * Return an instance with the specified query string. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified query string. - * - * Users can provide both encoded and decoded query characters. - * Implementations ensure the correct encoding as outlined in getQuery(). - * - * An empty query string value is equivalent to removing the query string. - * - * @param string $query The query string to use with the new instance. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * @return self A new instance with the specified query string. - */ - public function withQuery($query); - - /** - * Return an instance with the specified URI fragment. - * - * This method MUST retain the state of the current instance, and return - * an instance that contains the specified URI fragment. - * - * Users can provide both encoded and decoded fragment characters. - * Implementations ensure the correct encoding as outlined in getFragment(). - * - * An empty fragment value is equivalent to removing the fragment. - * - * @param string $fragment The fragment to use with the new instance. - * - * @throws InvalidArgumentException for invalid component or transformations - * that would result in a object in invalid state. - * - * @return self A new instance with the specified fragment. - */ - public function withFragment($fragment); - - /** - * Return the string representation as a URI reference. - * - * Depending on which components of the URI are present, the resulting - * string is either a full URI or relative reference according to RFC 3986, - * Section 4.1. The method concatenates the various components of the URI, - * using the appropriate delimiters: - * - * - If a scheme is present, it MUST be suffixed by ":". - * - If an authority is present, it MUST be prefixed by "//". - * - The path is concatenated without delimiters. - * - If a query is present, it MUST be prefixed by "?". - * - If a fragment is present, it MUST be prefixed by "#". - * - * @see http://tools.ietf.org/html/rfc3986#section-4.1 - * - * @return string - */ - public function __toString(); } diff --git a/src/UriInterface.php b/src/UriInterface.php index 94cf9f5..fd361be 100644 --- a/src/UriInterface.php +++ b/src/UriInterface.php @@ -1,7 +1,7 @@