Improve Interfaces documentation

Author: nyamsprod

docs/interfaces/7.0/encoder.md

@@ -6,11 +6,11 @@ title: URI component encoder and decoder
 URI component encoder and decoder
 =======
 
-In order to safely encode and/or decode a URI component, we need a tool to correctly perform the conversion.
-To do so the package provides an enhanced OOP wrapper around PHP's `rawurlencode` and `rawurldecode` functions
+To safely encode and/or decode a URI component, we need a tool to correctly perform the conversion.
+To do so, the package provides an enhanced OOP wrapper around PHP's `rawurlencode` and `rawurldecode` functions
 using the `League\Uri\Encoder` helper class.
 
-The class provides encoding mechanism for the following URI components:
+The class provides an encoding mechanism for the following URI components:
 
 ```php
 <?php
@@ -26,7 +26,7 @@ echo Encoder::encodePath($component);        // returns "/thi:s/is/a%3Fsimple=pa
 echo Encoder::encodeQueryOrFragment($query); // returns "simple%23=path&k%C3%A9?=23"
 ````
 
-The class also provides a more specific encodage used for query string key/value pair.
+The class also provides a more specific encoding mechanism used for query-string key/value pair.
 
 ```php
 <?php
@@ -37,7 +37,7 @@ echo Encoder::encodeQueryKeyValue($queryKey);   // returns "k%C3%A9%23"
 echo Encoder::encodeQueryKeyValue($queryValue); // returns "%26foobar"
 ````
 
-Each static encoding method is component aware and will prevent encoding component special characters that must or 
+Each static encoding method is component-aware and will prevent encoding component special characters that must or 
 must not be encoded in the context of a full URI.
 
 To complete the encoding methods, the class also exposes static decoding methods to safely decode URI components:
@@ -56,7 +56,8 @@ echo Encoder::decodePath($component);                 // returns "%2Fthi:s%2Fis%
 echo Encoder::decodeQuery($component);                // returns "/thi:s/is/a?simple%23=%20path"
 echo Encoder::decodeFragment($component);             // returns "/thi:s/is/a?simple#=%20path"
 ````
-Each static decoding method is component aware and will prevent decoding component specific characters in the context
+
+Each static decoding method is component-aware and will prevent decoding component-specific characters in the context
 of a full URI.
 
 <p class="message-info">The <code>scheme</code> and <code>port</code> do not requires a specific class to be correctly

docs/interfaces/7.0/uri-parser-builder.md

@@ -8,19 +8,10 @@ URI Parser and Builder
 
 PHP has been relying on the `parse_url` function to split URI into its component. But the
 function predates RFC3986 and as such does not fully comply to the specification. To work
-around this limitation the tooklit provides the `League\Uri\UriString` class. It is a
+around the limitation the tooklit provides the `League\Uri\UriString` class. It is a
 user-land PHP URI parser and builder compliant with [RFC 3986](http://tools.ietf.org/html/rfc3986) and [RFC 3987](http://tools.ietf.org/html/rfc3987)
-The class act as a drop-in replacement for PHP's `parse_url` feature.
-
-## URI parsing
-
-~~~php
-UriString::parse(string $uri): array
-UriString::parseAuthority(string $autority): array
-UriString::normalize(string $uri): string
-UriString::normalizeAuthority(string $autority): string
-UriString::resolve(string $uri, ?string $baseUri = null): string
-~~~
+The class act as a drop-in replacement for PHP's `parse_url` feature. And expand on
+the feature to provide RFC3986 features:
 
 The parser is:
 
@@ -30,6 +21,22 @@ The parser is:
 - makes a distinction between empty and undefined components;
 - the parser throws a `League\Uri\Contracts\UriException` exception instead of returning `false` on error;
 
+## URI parsing
+
+The class covers parsing URI in different context:
+
+~~~php
+UriString::parse(Stringable|string $uri): array
+UriString::parseAuthority(Stringable|string $autority): array
+UriString::parseNormalized(Stringable|string $uri): array
+UriString::normalize(Stringable|string $uri): string
+UriString::normalizeAuthority(Stringable|string $autority): string
+UriString::resolve(Stringable|string $uri, Stringable|string|null $baseUri = null): string
+~~~
+
+The `Uri::parse` method is an RFC compliant replacement to `parse_url`. It returns the same array
+but the parsed data is fully compliant with the RFC specificaition.
+
 ~~~php
 <?php
 
@@ -50,7 +57,7 @@ var_export(UriString::parse('http://[email protected]/#'));
 ~~~
 
 <p class="message-warning">Just like <code>parse_url</code>, the <code>League\Uri\UriString</code> only
-parses and extracts from the URI its components. Validating against scheme specific rules is still a requirement.</p>
+parses and extracts from the URI its components. Validating against scheme-specific rules is still a requirement.</p>
 
 ~~~php
 var_export(UriString::parse('http:www.example.com'));
@@ -70,18 +77,25 @@ var_export(UriString::parse('http:www.example.com'));
 <p class="message-warning">This invalid HTTP URI is successfully parsed.</p>
 <p class="message-notice">The class also exposes a <code>UriString::parseAuthority</code> you can use to parse an authority string.</p>
 
+### URI resolution
+
+<p class="message-notice">Available since version <code>7.6</code></p>
+
 If you need to resolve your URI in the context of a Base URI the `resolve` public static method will let you
-do just that. The method expect either a full URI as its single parameter or a relative URI following by
+do just that. The method expects either a full URI as its single parameter or a relative URI followed by
 a base URI which must be absolute, the URI will then be resolved using the base URI.
 
 ```php
 $components = UriString::resolve("/foo", "https://example.com");
 //returns "https://example.com/foo"
 ```
 
-It is possible to normalize a URI against the RFC3986 rules using the `UriString::normalize` method.
-The method expects a string and will return the same array as `UriString::parse` but each component will
-have been normalized.
+### URI normalization
+
+It is possible to normalize a URI against the RFC3986 rules using two (2) methods:
+
+- `UriString::normalize` which returns the normalized string.
+- `UriString::parseNormalized`  which returns the same output as `Uri::parse` but each component is normalized.
 
 ```php
 use League\Uri\UriString;
@@ -99,21 +113,36 @@ $parsed = UriString::parse("https://EXAMPLE.COM/foo/../bar");
 //  'fragment' => null,
 //);
 
-$normalized = UriString::normalize("https://EXAMPLE.COM/foo/../bar");
+$normalized = UriString::parseNormalized("https://EXAMPLE.COM/foo/../bar");
+//returns the following array
+//array(
+//  'scheme' => 'https',
+//  'user' => null,
+//  'pass' => null,
+//  'host' => 'example.com',
+//  'port' => null,
+//  'path' => '/bar',
+//  'query' => null,
+//  'fragment' => null,
+//);
+
+$normalizedUri = UriString::normalize("https://EXAMPLE.COM/foo/../bar");
 //returns "https://example.com/bar"
 ```
 
+<p class="message-notice">The class also exposes a <code>UriString::normalizeAuthority</code> method, you can use to normalize an authority string.</p>
+
 ## URI Building
 
 ~~~php
 UriString::build(array $components): string
 UriString::buildAuthority(array $components): string
-UriString::buildUri(?string $scheme, ?string $authority, string $path, ?string $query, ?string $fragment): string
+UriString::buildUri(?string $scheme = null, ?string $authority = null, ?string $path = null, ?string $query = null, ?string $fragment = null): string
 ~~~
 
 You can rebuild a URI from its hash representation returned by the `UriString::parse` method or PHP's `parse_url` function using the `UriString::build` public static method.  
 
-<p class="message-notice">If you supply your own hash you are responsible for providing valid encoded components without their URI delimiters.</p>
+<p class="message-notice">If you supply your own hash, you are responsible for providing valid encoded components without their URI delimiters.</p>
 
 ~~~php
 $components = UriString::parse('http://hello:[email protected][email protected]/');
@@ -134,4 +163,42 @@ echo UriString::build($components); //displays http://hello:[email protected][email protected]
 
 The `build` method provides similar functionality to the `http_build_url()` function from v1.x of the [`pecl_http`](https://pecl.php.net/package/pecl_http) PECL extension.
 
-<p class="message-notice">The class also exposes a <code>UriString::buildAuthority</code> you can use to build an authority from its hash representation.</p>
+<p class="message-notice">The class also exposes a <code>UriString::buildAuthority</code> method you can use to build an authority from its hash representation.</p>
+<p class="message-notice">The class also exposes a <code>UriString::buildUri</code> method which strictly follow the specification.</p>
+
+## Removing dot segments
+
+<p class="message-notice">Available since version <code>7.6</code></p>
+
+To remove dot segments as per [RFC3986](https://tools.ietf.org/html/rfc3986#section-6), you need to explicitly call
+the `UriString::removeDotSegments` method. The method takes a single argument the path string and returns
+a new string which represents the path without dot segments.
+
+~~~php
+<?php
+
+use League\Uri\UriString;
+
+$path = UriString::removeDotSegments('path/to/./the/../the/sky%7bfoo%7d');
+echo $path;  //displays 'path/to/the/sky%7Bfoo%7D'
+~~~
+
+## Component and String Validation
+
+The class exposes static methods to validate that a string:
+
+- represents a valid scheme with the `isValidScheme()` method
+- represents a valid host according to RFC3986/RFC3987 with the `isValidHost()` method
+- contains RFC3986 characters only with the `containsValidRfc3986Characters()` method
+- contains RFC3987 characters only with the `containsValidRfc3987Characters()` method
+
+~~~php
+<?php
+
+use League\Uri\Uri;use League\Uri\UriString;
+
+UriString::isValidScheme('foo '); //returns false because of the trailing space
+UriString::isValidHost('333.333.333.1.333'); //returns true
+UriString::containsValidRfc3986Characters('http://bébé.be'); //returns false non-ascii character are not allowed
+UriString::containsValidRfc3987Characters('http://bébé.be'); //returns true
+~~~

interfaces/CHANGELOG.md

@@ -24,7 +24,6 @@ All Notable changes to `League\Uri\Interfaces` will be documented in this file
 - `UriString::containsValidRfc3987Characters`
 - `UriString::isValidScheme`
 - `UriString::isValidHost`
-- `UriString::buildUserInfo`
 - `FeatureDetection::supportsDom`
 - `Encoder::decodeNecessary`
 - `Encoder::decodePath`
@@ -47,7 +46,7 @@ All Notable changes to `League\Uri\Interfaces` will be documented in this file
 ### Fixed
 
 - `UriString::parse` will fail if the URI contains whitespace.
-- `UriString::buildUri` allows the `$path` argument to be `null`.
+- `UriString::buildUri` allows all arguments to be `null` including the `path`.
 - `UriString::buildAuthority` allows the `$user` argument to be `null` and still generate a user info component.
 
 ### Deprecated

interfaces/Encoder.php

@@ -287,7 +287,7 @@ public static function decodeQuery(Stringable|string|null $path): ?string
     }
 
     /**
-     * Normalize query component.
+     * Normalize the query component.
      *
      * The value returned MUST be percent-encoded, but MUST NOT double-encode
      * any characters. To determine what characters to encode, please refer to
@@ -317,7 +317,7 @@ public static function decodeFragment(Stringable|string|null $path): ?string
     }
 
     /**
-     * Normalize fragment component.
+     * Normalize the fragment component.
      *
      * The value returned MUST be percent-encoded, but MUST NOT double-encode
      * any characters. To determine what characters to encode, please refer to
@@ -329,7 +329,7 @@ public static function normalizeFragment(Stringable|string|null $fragment): ?str
     }
 
     /**
-     * Normalize host component.
+     * Normalize the host component.
      *
      * @see https://www.rfc-editor.org/rfc/rfc3986.html#section-3.2.2
      *

interfaces/UriString.php

@@ -218,20 +218,20 @@ public static function build(array $components): string
     }
 
     /**
-     * Generate a URI string representation based on RFC3986 algorithm.
+     * Generates a URI string representation based on RFC3986 algorithm.
      *
-     * valid URI component MUST be provided without their URI delimiters
+     * Valid URI component MUST be provided without their URI delimiters
      * but properly encoded.
      *
      * @link https://tools.ietf.org/html/rfc3986#section-5.3
      * @link https://tools.ietf.org/html/rfc3986#section-7.5§
      */
     public static function buildUri(
-        ?string $scheme,
-        ?string $authority,
-        ?string $path,
-        ?string $query,
-        ?string $fragment,
+        ?string $scheme = null,
+        ?string $authority = null,
+        ?string $path = null,
+        ?string $query = null,
+        ?string $fragment = null,
     ): string {
         self::validateComponents($scheme, $authority, $path);
         $uri = '';
@@ -284,25 +284,6 @@ public static function buildAuthority(array $components): ?string
         return $authority;
     }
 
-    /**
-     * Generate a URI UserInfo representation from the URI parsed representation.
-     *
-     * @param InputComponentMap $components
-     */
-    public static function buildUserInfo(array $components): ?string
-    {
-        if (!isset($components['user'])) {
-            return null;
-        }
-
-        $userInfo = $components['user'];
-        if (! isset($components['pass'])) {
-            return $userInfo;
-        }
-
-        return $userInfo.':'.$components['pass'];
-    }
-
     /**
      * Parses and normalizes the URI following RFC3986 destructive and non-destructive constraints.
      *