php · mmalferov · May 8, 2026 · May 9, 2026 · May 9, 2026 · May 12, 2026
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -4436,6 +4436,18 @@ local: {
   </simpara>
 '>
 
+<!ENTITY uri.normalization '
+  <simpara>
+   Hexadecimal triplets are converted to uppercase, percent-encoded unreserved characters are decoded, the scheme and host components are normalized to lowercase, and dot segments are removed from the path, per RFC 3986.
+  </simpara>
+'>
+
+<!ENTITY uri.non-normalization '
+  <simpara>
+   Hexadecimal triplets are not converted to uppercase, percent-encoded unreserved characters remain encoded, the scheme and host components keep the case they were given in, and dot segments are kept in the path.
+  </simpara>
+'>
+
 <!-- UOPZ snippets -->
 
 <!ENTITY uopz.warn.removed.function-5-0-0 '<warning

@@ -105,7 +105,7 @@
 
      <enumitem>
       <enumidentifier>Ipv4InIpv6InvalidCodePoint</enumidentifier>
-      <enumitemdescription>An IPv6 address with IPv4 address syntax.</enumitemdescription>
+      <enumitemdescription>An IPv6 address with IPv4 address syntax: an IPv4 part is empty, contains a non-ASCII digit or a leading zero, or there are too many IPv4 parts.</enumitemdescription>
      </enumitem>
 
      <enumitem>

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the normalized fragment component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the normalized host component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -15,6 +15,7 @@
    Retrieves the normalized password part (the text after the first <literal>:</literal> character)
    from the userinfo component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the normalized path component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the normalized query component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the raw (non-normalized) fragment component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the raw (non-normalized) host component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -15,6 +15,7 @@
    Retrieves the raw (non-normalized) password part (the text after the first <literal>:</literal> character)
    from the userinfo component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -25,7 +26,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the raw (non-normalized) password as a &string; if the userinfo component contains a <literal>:</literal> character.
+   Returns the raw password as a &string; if the userinfo component contains a <literal>:</literal> character.
    An empty string is returned when the userinfo component doesn't contain a <literal>:</literal> character.
    &null; is returned when the userinfo component doesn't exist.
   </simpara>

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the raw (non-normalized) path component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the raw (non-normalized) query component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the raw (non-normalized) scheme component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the raw (non-normalized) userinfo component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -15,6 +15,7 @@
    Retrieves the raw (non-normalized) username part (the text before the first <literal>:</literal> character)
    from userinfo component.
   </simpara>
+  &uri.non-normalization;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -25,7 +26,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the raw (non-normalized) username as a &string; if the userinfo component exists, &null; is returned otherwise.
+   Returns the raw username as a &string; if the userinfo component exists, &null; is returned otherwise.
   </simpara>
  </refsect1>
 

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the normalized scheme component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -14,6 +14,7 @@
   <simpara>
    Retrieves the normalized userinfo component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -15,6 +15,7 @@
    Retrieves the normalized username part (the text before the first <literal>:</literal> character)
    from the userinfo component.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -56,14 +56,14 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+
 $uri = \Uri\Rfc3986\Uri::parse("https://example.com");
 
 if ($uri !== null) {
     echo "Valid URI: " . $uri->toString();
 } else {
     echo "Invalid URI";
 }
-?>
 ]]>
    </programlisting>
    &example.outputs;

@@ -2,7 +2,7 @@
 <refentry xml:id="uri-rfc3986-uri.resolve" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Uri\Rfc3986\Uri::resolve</refname>
-  <refpurpose>Resolve a URI with the current object as the base URL</refpurpose>
+  <refpurpose>Resolve a URI with the current object as the base URI</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -12,7 +12,7 @@
    <methodparam><type>string</type><parameter>uri</parameter></methodparam>
   </methodsynopsis>
   <simpara>
-   Resolves a URI - which may potentially be a relative reference - with the current object as the base URL.
+   Resolves a URI - which may potentially be a relative reference - with the current object as the base URI.
   </simpara>
  </refsect1>
 
@@ -49,11 +49,11 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+
 $uri = new \Uri\Rfc3986\Uri("https://example.com");
 $uri = $uri->resolve("/foo");
 
 echo $uri->toRawString();
-?>
 ]]>
    </programlisting>
    &example.outputs;

@@ -14,6 +14,12 @@
   <simpara>
    Recomposes the raw (non-normalized) URI to a &string;.
   </simpara>
+  &uri.non-normalization;
+  <simpara>
+   An IPv6 host is an exception: it is recomposed from its parsed form, and is
+   therefore returned fully expanded and in lowercase, whatever notation the
+   input used.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -24,7 +30,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the recomposed raw (non-normalized) URI as a &string;.
+   Returns the recomposed raw URI as a &string;.
   </simpara>
  </refsect1>
 

@@ -14,6 +14,7 @@
   <simpara>
    Recomposes the normalized URI to a &string;.
   </simpara>
+  &uri.normalization;
  </refsect1>
 
  <refsect1 role="parameters">

@@ -49,11 +49,11 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+
 $uri = new \Uri\Rfc3986\Uri("https://example.com/#foo");
 $uri = $uri->withFragment("bar");
 
 echo $uri->getFragment();
-?>
 ]]>
    </programlisting>
    &example.outputs;

@@ -14,7 +14,7 @@
    <methodparam choice="opt"><type>array</type><parameter role="reference">softErrors</parameter><initializer>&null;</initializer></methodparam>
   </constructorsynopsis>
   <simpara>
-   Constructs the <classname>Uri\Rfc3986\Uri</classname> object.
+   Constructs the <classname>Uri\WhatWg\Url</classname> object.
   </simpara>
  </refsect1>
 
@@ -25,7 +25,10 @@
     <term><parameter>uri</parameter></term>
     <listitem>
      <simpara>
-      A valid URL string to parse (e.g. <literal>/foo</literal> or (e.g. <literal>https://example.com/foo</literal>).
+      A URL string to parse, for instance
+      <literal>https://example.com/foo</literal>. A relative-URL string such as
+      <literal>/foo</literal> is only accepted when
+      <parameter>baseUrl</parameter> is given.
      </simpara>
     </listitem>
    </varlistentry>

@@ -35,16 +35,16 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-$url = new \Uri\WhatWg\Url("https://example.com");
+
+$url = new \Uri\WhatWg\Url("https://täst.example.com");
 
 echo $url->getAsciiHost();
-?>
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-example.com
+xn--tst-qla.example.com
 ]]>
    </screen>
   </example>

@@ -25,7 +25,10 @@
     <term><parameter>uri</parameter></term>
     <listitem>
      <simpara>
-      A valid URL string to parse (e.g. <literal>/foo</literal> or (e.g. <literal>https://example.com/foo</literal>).
+      A URL string to parse, for instance
+      <literal>https://example.com/foo</literal>. A relative-URL string such as
+      <literal>/foo</literal> is only accepted when
+      <parameter>baseUrl</parameter> is given.
      </simpara>
     </listitem>
    </varlistentry>
@@ -66,14 +69,14 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+
 $url = \Uri\WhatWg\Url::parse("https://example.com");
 
 if ($url !== null) {
     echo "Valid URL: " . $url->toAsciiString();
 } else {
     echo "Invalid URL";
 }
-?>
 ]]>
    </programlisting>
    &example.outputs;

@@ -24,7 +24,7 @@
     <term><parameter>uri</parameter></term>
     <listitem>
      <simpara>
-      A valid URL string (e.g. <literal>/foo</literal> or (e.g. <literal>https://example.com/foo</literal>) to apply on
+      A valid URL string (e.g. <literal>/foo</literal> or <literal>https://example.com/foo</literal>) to apply on
       the current object.
      </simpara>
     </listitem>

@@ -36,16 +36,16 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-$url = new \Uri\WhatWg\Url("https://example.com/foo/bar?baz");
+
+$url = new \Uri\WhatWg\Url("https://täst.example.com/foo/bar?baz");
 
 echo $url->toAsciiString();
-?>
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-https://example.com/foo/bar?baz
+https://xn--tst-qla.example.com/foo/bar?baz
 ]]>
    </screen>
   </example>

@@ -35,16 +35,16 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-$url = new \Uri\WhatWg\Url("https://example.com/foo/bar?baz");
+
+$url = new \Uri\WhatWg\Url("https://xn--tst-qla.example.com/foo/bar?baz");
 
 echo $url->toUnicodeString();
-?>
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-https://example.com/foo/bar?baz
+https://täst.example.com/foo/bar?baz
 ]]>
    </screen>
   </example>

@@ -2,7 +2,7 @@
 <refentry xml:id="uri-whatwg-url.unserialize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Uri\WhatWg\Url::__unserialize</refname>
-  <refpurpose>Deserialize the data parameter into a Url object</refpurpose>
+  <refpurpose>Deserialize the array from the data parameter into a Url object</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -12,7 +12,7 @@
    <methodparam><type>array</type><parameter>data</parameter></methodparam>
   </methodsynopsis>
   <simpara>
-   Deserializes a data parameter into a <classname>Uri\WhatWg\Url</classname> object.
+   Deserializes the &array; from the <parameter>data</parameter> parameter into a <classname>Uri\WhatWg\Url</classname> object.
   </simpara>
  </refsect1>