diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c2f051..81afdf7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,27 @@ All Notable changes to `League\Uri\Interfaces` will be documented in this file +## 0.2.0 - 2016-11-29 + +### Added + +- `League\Uri\Interfaces\Component::RFC3986` to specify encoding according to RFC3986 rules +- `League\Uri\Interfaces\Component::RFC3987` to specify encoding according to RFC3987 rules + +### Fixed + +- `League\Uri\Interfaces\Component::getContent` now takes an optional `$enc_type` parameter +to specify the returned content encoding rules. +- `League\Uri\Interfaces\Uri` docblocks simplified around Exception thrown + +### Deprecated + +- None + +### Removed + +- None + ## 0.1.0 - 2016-10-17 ### Added diff --git a/src/CollectionComponent.php b/src/CollectionComponent.php index 7fe2652..24c48da 100644 --- a/src/CollectionComponent.php +++ b/src/CollectionComponent.php @@ -17,7 +17,7 @@ use IteratorAggregate; /** - * Value object representing a Collection. + * Value object representing a Collection Component. * * Instances of this interface are considered immutable; all methods that * might change state MUST be implemented such that they retain the internal @@ -63,7 +63,7 @@ public function hasKey($key); * @param callable $callable the callback function to use * @param int $flag flag to determine what argument are sent to callback * - * @throws InvalidArgumentException for transformations that would result in a invalid object. + * @throws InvalidArgumentException for transformations that would result in a object in invalid state. * * @return static */ @@ -77,6 +77,8 @@ public function filter(callable $callable, $flag = 0); * * @param array $keys the list of keys to remove from the collection * + * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * * @return static */ public function without(array $keys); diff --git a/src/Component.php b/src/Component.php index 64175b6..9490c50 100644 --- a/src/Component.php +++ b/src/Component.php @@ -15,7 +15,7 @@ use InvalidArgumentException; /** - * Value object representing a URI component or subcomponent + * Value object representing a URI component. * * Instances of this interface are considered immutable; all methods that * might change state MUST be implemented such that they retain the internal @@ -30,6 +30,10 @@ */ interface Component { + const RFC3986 = 'RFC3986'; + + const RFC3987 = 'RFC3987'; + /** * Returns whether or not the component is defined. * @@ -41,14 +45,18 @@ public function isDefined(); * Returns the instance content. * * If the instance is defined, 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. + * but MUST NOT double-encode any characters depending on the encoding type selected. + * + * To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3. + * or RFC 3987 Section 3. By default the content is encoded according to RFC3986 * * If the instance is not defined null is returned * + * @param int $enc_type + * * @return string|null */ - public function getContent(); + public function getContent($enc_type = self::RFC3986); /** * Returns the instance string representation. @@ -70,6 +78,8 @@ public function __toString(); * characters. To determine what characters to encode, please refer to RFC 3986, * Sections 2 and 3. * + * If the instance is not defined an empty string is returned + * * @return string */ public function getUriComponent(); @@ -77,16 +87,17 @@ public function getUriComponent(); /** * Returns an instance with the specified content. * - * 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. - * * This method MUST retain the state of the current instance, and return - * an instance that contains the modified data + * an instance that contains the specified content. + * + * Users can provide both encoded and decoded content characters. + * + * A null value is equivalent to removing the component content. * * @param string|null $content * - * @throws InvalidArgumentException for transformations that would result in a invalid object. + * @throws InvalidArgumentException for invalid component or transformations + * that would result in a object in invalid state. * * @return static */ diff --git a/src/Uri.php b/src/Uri.php index 58d2238..4259089 100644 --- a/src/Uri.php +++ b/src/Uri.php @@ -196,7 +196,8 @@ public function getFragment(); * * @param string $scheme The scheme to use with the new instance. * - * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * @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. */ @@ -215,7 +216,8 @@ public function withScheme($scheme); * @param string $user The user name to use for authority. * @param null|string $password The password associated with $user. * - * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * @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. */ @@ -231,7 +233,9 @@ public function withUserInfo($user, $password = null); * * @param string $host The hostname to use with the new instance. * - * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * @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. */ @@ -252,7 +256,8 @@ public function withHost($host); * @param null|int $port The port to use with the new instance; a null value * removes the port information. * - * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * @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. */ @@ -268,17 +273,13 @@ public function withPort($port); * rootless (not starting with a slash). Implementations MUST support all * three syntaxes. * - * If the path is intended to be domain-relative rather than path relative then - * it must begin with a slash ("/"). Paths not starting with a slash ("/") - * are assumed to be relative to some base path known to the application or - * consumer. - * * 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 transformations that would result in a object in invalid state. + * @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. */ @@ -297,7 +298,8 @@ public function withPath($path); * * @param string $query The query string to use with the new instance. * - * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * @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. */ @@ -316,7 +318,8 @@ public function withQuery($query); * * @param string $fragment The fragment to use with the new instance. * - * @throws InvalidArgumentException for transformations that would result in a object in invalid state. + * @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. */ @@ -332,7 +335,7 @@ public function withFragment($fragment); * * - If a scheme is present, it MUST be suffixed by ":". * - If an authority is present, it MUST be prefixed by "//". - * - The path can be concatenated without delimiters. + * - 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 "#". *