From 93ef923dd991f4a887101f509a0e970ff75172e6 Mon Sep 17 00:00:00 2001
From: ignace nyamagana butera <nyamsprod@gmail.com>
Date: Wed, 25 Dec 2024 12:45:14 +0100
Subject: [PATCH] Update documentation for the current release

---
 docs/uri/7.0/rfc3986.md | 85 ++++++++++++++++++++++++++++-------------
 1 file changed, 59 insertions(+), 26 deletions(-)

diff --git a/docs/uri/7.0/rfc3986.md b/docs/uri/7.0/rfc3986.md
index 900a0eb9..b7af78f7 100644
--- a/docs/uri/7.0/rfc3986.md
+++ b/docs/uri/7.0/rfc3986.md
@@ -105,6 +105,65 @@ echo $uri = //returns 'file:///etc/fstab'
 
 <p class="message-notice"><code>fromRfc8089</code> is added since version <code>7.4.0</code></p>
 
+## URI string representation
+
+The `Uri` class handles URI according to RFC3986 as such you can retrieve its string representation using the
+`toString` method. 
+
+```php
+use League\Uri\Uri;
+
+$uri = Uri::new("http://foo:bar@www.example.com:81/how/are/you?foo=baz#title");
+
+echo $uri->toString(); //displays RFC3986 string representation
+echo $uri;             //displays RFC3986 string representation
+```
+
+But `Uri` can have multiple string representation depending on its scheme or context. As
+such the package provides several other string representations.
+
+The `Uri` instance can be json encoded using the same URI representation from JavaScript to allow
+easier interoperability
+
+```php
+use League\Uri\Uri;
+
+$uri = Uri::new("http://foo:bar@www.example.com:81/how/are/you?foo=baz#title");
+json_encode($uri); //returns "http:\/\/foo:bar@www.example.com:81\/how\/are\/you?foo=baz#title"
+```
+
+<p class="message-info">Available since version <code>7.6.0</code></p>
+
+Two new URI string representation are added, the `toNormalizedString` normalizes the URI using
+destructive normalization. Please refer to the [URI normalization section](#uri-normalization-and-comparison) for more information.
+The `toDisplayString` returns a human-readable representation of the URI. The returned value
+may represent an invalid URI but can be used to display the URI to the client for instance as the
+content of a `a` HTML tag.
+
+```php
+use League\Uri\Uri;
+
+$uri = Uri::new('eXAMPLE://a/./b/../b/%63/%7bfoo%7d?foo[]=bar');
+echo $uri->toString();           //displays 'example://a/./b/../b/%63/%7bfoo%7d?foo%5B%5D=bar'
+echo $uri->toNormalizedString(); //displays 'example://a/b/c/%7Bfoo%7D?foo%5B%5D=bar'
+echo $uri->toDisplayString();    //displays 'example://a/b/c/{foo}?foo[]=bar'
+````
+
+File specific representation are also added to allow representing Unix and Windows Path.
+
+```php
+use League\Uri\Uri;
+
+$uri = Uri::new('file:///c:/windows/My%20Documents%20100%2520/foo.txt');
+echo $uri->toWindowsPath(); //display 'c:\windows\My Documents 100%20\foo.txt'
+
+$uri = Uri::new('file:///path%20empty/bar');
+echo $uri->toUnixPath(); // display '/path empty/bar'
+
+$uri = Uri::new('file://localhost/etc/fstab');
+echo $uri->toRfc8089();    //display 'file:/etc/fstab'
+```
+
 ## Accessing URI properties
 
 Let's examine the result of building a URI:
@@ -249,32 +308,6 @@ Uri::new('https://example.com/123')
 
 The method takes into account i18n while comparing both URI if the PHP's `idn_*` functions can be used.
 
-## URI string representation
-
-The `Uri` class handles URI according to RFC3986 as such you can retrieve its string representation using the
-`toString` method. But `URI` can have multiple string representation depending on its scheme or context. As
-such the package provides several other string representations:
-
-```php
-use League\Uri\Uri;
-
-$uri = Uri::new("http://foo:bar@www.example.com:81/how/are/you?foo=baz#title");
-
-echo $uri->toString(); //displays RFC3986 string representation
-echo $uri;             //displays RFC3986 string representation
-echo json_encode($uri); //display JSON encoded string representation
-
-/**
- * NEW in version 7.6+
- */
-
-echo $uri->toNormalizedString(); //displays the normalized URI string representation
-echo $uri->toDisplayString();    //displays the URI display representation
-echo $uri->toRfc8089String();    //display the string file representation according to RFC8089 or null if the scheme is not file
-echo $uri->toUnixPath();         //display the string path as a Unix Path or null if the scheme is not file
-echo $uri->toWindowsPath();      //display the string path as a Windows Path  or null if the scheme is not file
-```
-
 ## Modifying URI properties
 
 Use the modifying methods exposed by all URI instances to replace one of the URI component.