parse_url: Expand caution note and reference ext/uri (#5477)

Fixes #5450.

Author: TimWolla

reference/url/functions/parse-url.xml

@@ -25,13 +25,29 @@
    parse them correctly.
   </para>
   <caution>
-   <para>
-    This function may not give correct results for relative or invalid URLs,
-    and the results may not even match common behavior of HTTP clients.
-    If URLs from untrusted input need to be parsed, extra validation is
-    required, e.g. by using <function>filter_var</function> with the
-    <constant>FILTER_VALIDATE_URL</constant> filter.
-   </para>
+   <simpara>
+    This function does not follow any established URI or URL standard.
+    It will return incorrect or non-sense results for relative or malformed
+    URLs. Even for valid URLs the result may differ from that of a
+    different URL parser, since there are multiple different URL-related
+    standards that target different use cases and that differ in their
+    requirements.
+   </simpara>
+   <simpara>
+    Processing an URL with parsers following different URL standards is a
+    common source of security vulnerabilities. As an example, validating
+    an URL against an allow-list of acceptable hostnames with parser A
+    might be ineffective when the actual retrieval of the resource uses
+    parser B that extracts hostnames differently.
+   </simpara>
+   <simpara>
+    The <classname>Uri\Rfc3986\Uri</classname> and <classname>Uri\WhatWg\Url</classname>
+    classes strictly follow the RFC 3986 and WHATWG URL Standards respectively.
+    It is strongly recommended to use these classes for all newly written code
+    and to migrate existing uses of the <function>parse_url</function> function
+    to these classes, unless the <function>parse_url</function> behavior needs
+    to be preserved for compatibility reasons.
+   </simpara>
   </caution>
  </refsect1>