Update Component::getContent signature

- Component::getContent now returns string depends on the selected encoding rules. RFC3986 or RFC3987 - Improve Interfaces docblock
thephpleague · Nov 29, 2016 · 823d257 · 823d257
1 parent d71f465
commit 823d257
Show file tree

Hide file tree

Showing 4 changed files with 62 additions and 25 deletions.
diff --git 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
@@ -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
@@ -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,23 +78,26 @@ 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();
 
     /**
      * 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
@@ -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 "#".
      *