[DOC-CVS] [doc-en] master: Clarify behaviour of escape parameter and how it handles enclosure bytes (#5006)

Author: Narkunan (Narkunan)
Committer: GitHub (web-flow)
Pusher: Girgias
Date: 2026-01-09T12:54:39Z

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

Clarify behaviour of escape parameter and how it handles enclosure bytes (#5006)

Changed paths:
  M  reference/filesystem/functions/fgetcsv.xml
  M  reference/spl/splfileobject/fgetcsv.xml


Diff:

diff --git a/reference/filesystem/functions/fgetcsv.xml b/reference/filesystem/functions/fgetcsv.xml
index 7e1ba4046dc9..856f305b70db 100644
--- a/reference/filesystem/functions/fgetcsv.xml
+++ b/reference/filesystem/functions/fgetcsv.xml
@@ -88,18 +88,17 @@
        It must be a single byte character or the empty string.
        The empty string (<literal>""</literal>) disables the proprietary escape mechanism.
       </para>
-      <note>
+      <warning>
        <simpara>
-        Usually an <parameter>enclosure</parameter> character is escaped inside
-        a field by doubling it; however, the <parameter>escape</parameter>
-        character can be used as an alternative. So for the default parameter
-        values <literal>""</literal> and <literal>\"</literal> have the same
-        meaning. Other than allowing to escape the
-        <parameter>enclosure</parameter> character the
-        <parameter>escape</parameter> character has no special meaning; it isn't
-        even meant to escape itself.
+       Inside an <parameter>enclosure</parameter>, the <parameter>enclosure</parameter> character can always be <parameter>escaped</parameter> by doubling it,
+       resulting in a single <parameter>enclosure</parameter> character in the parsed result.
+       The <parameter>escaped</parameter> character works differently:
+       If it is followed by an <parameter>enclosure</parameter> character then that <parameter>enclosure</parameter> character will not be treated as one,
+       however the <parameter>escaped</parameter> character itself remains. So for the default parameters, <literal>""</literal>
+       inside an <parameter>enclosure</parameter> will be parsed into <literal>",</literal> while <literal>\"</literal> inside an
+       <parameter>enclosure</parameter> will be parsed into <literal>\"</literal>.
        </simpara>
-      </note>
+      </warning>
       <warning>
        <simpara>
         As of PHP 8.4.0, depending on the default value of
diff --git a/reference/spl/splfileobject/fgetcsv.xml b/reference/spl/splfileobject/fgetcsv.xml
index 7d36981e754f..f149533eb638 100644
--- a/reference/spl/splfileobject/fgetcsv.xml
+++ b/reference/spl/splfileobject/fgetcsv.xml
@@ -55,18 +55,17 @@
        <methodname>SplFileObject::setCsvControl</methodname>.
        An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
       </para>
-      <note>
+      <warning>
        <simpara>
-        Usually an <parameter>enclosure</parameter> character is escaped inside
-        a field by doubling it; however, the <parameter>escape</parameter>
-        character can be used as an alternative. So for the default parameter
-        values <literal>""</literal> and <literal>\"</literal> have the same
-        meaning. Other than allowing to escape the
-        <parameter>enclosure</parameter> character the
-        <parameter>escape</parameter> character has no special meaning; it isn't
-        even meant to escape itself.
+       Inside an <parameter>enclosure</parameter>, the <parameter>enclosure</parameter> character can always be <parameter>escaped</parameter> by doubling it,
+       resulting in a single <parameter>enclosure</parameter> character in the parsed result.
+       The <parameter>escaped</parameter> character works differently:
+       If it is followed by an <parameter>enclosure</parameter> character then that <parameter>enclosure</parameter> character will not be treated as one,
+       however the <parameter>escaped</parameter> character itself remains. So for the default parameters, <literal>""</literal>
+       inside an <parameter>enclosure</parameter> will be parsed into <literal>",</literal> while <literal>\"</literal> inside an
+       <parameter>enclosure</parameter> will be parsed into <literal>\"</literal>.
        </simpara>
-      </note>
+      </warning>
       <warning>
        <simpara>
         As of PHP 8.4.0, depending on the default value of