[DOC-CVS] [doc-en] master: parse_url: Expand caution note and reference ext/uri (#5477)

Author: Tim Düsterhus (TimWolla)
Committer: GitHub (web-flow)
Pusher: kocsismate
Date: 2026-04-07T08:14:44+02:00

Commit: https://github.com/php/doc-en/commit/b3194d54645b22d5f229fcac3b4baf0d7b85ac8d
Raw diff: https://github.com/php/doc-en/commit/b3194d54645b22d5f229fcac3b4baf0d7b85ac8d.diff

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

Fixes php/doc-en#5450.

Changed paths:
  M  reference/url/functions/parse-url.xml


Diff:

diff --git a/reference/url/functions/parse-url.xml b/reference/url/functions/parse-url.xml
index 4e096a9164ff..34ccd914949a 100644
--- a/reference/url/functions/parse-url.xml
+++ b/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>