From 33225f7c5759ebd29496e98a55a3e4ba58cb1ac4 Mon Sep 17 00:00:00 2001
From: Denis Ryabov <dryabov@yandex.ru>
Date: Sat, 4 Sep 2021 15:53:55 +0300
Subject: [PATCH] Add a separate example section for escaping of characters

See also merged PR https://github.com/php/php-src/pull/7420 (https://github.com/php/php-src/commit/d3a6054d4441a6d431e6ca7aa63de62cee5585c2)

Closes GH-898.
---
 .../filesystem/functions/parse-ini-file.xml   | 59 +++++++++++++++++--
 1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/reference/filesystem/functions/parse-ini-file.xml b/reference/filesystem/functions/parse-ini-file.xml
index a2d7fca712..eea0bd63a5 100644
--- a/reference/filesystem/functions/parse-ini-file.xml
+++ b/reference/filesystem/functions/parse-ini-file.xml
@@ -227,7 +227,7 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
   </para>
   <para>
    <example>
-    <title>value interpolation</title>
+    <title>Value Interpolation</title>
     <para>
      In addition to evaluating constants, certain characters have special meaning in an ini value.
      Additionally, environment variables and previously defined values may be read using
@@ -250,10 +250,6 @@ negative_two = ~1
 ; () is used for grouping
 seven = (8|7)&(6|5)
 
-; \ is used to escape a value.
-newline_is = "\\n" ; results in the string "\n", not a newline character.
-with quotes = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
-
 path = ${PATH}
 also_five = ${five}
 
@@ -261,6 +257,59 @@ also_five = ${five}
     </programlisting>
    </example>
   </para>
+  <para>
+   <example>
+    <title>Escaping Characters</title>
+    <para>
+     Some characters have special meaning in double-quoted strings and must be escaped by the backslash prefix.
+     First of all, these are the double quote <code>"</code> as the boundary marker, and the backslash <code>\</code> itself
+     (if followed by one of the special characters):
+    </para>
+    <programlisting>
+<![CDATA[
+quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
+hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote
+]]>
+    </programlisting>
+    <para>
+     There is an exception made for Windows-like paths: it's possible to not escape trailing backslash
+     if the quoted string is directly followed by a linebreak:
+    </para>
+    <programlisting>
+<![CDATA[
+save_path = "C:\Temp\"
+]]>
+    </programlisting>
+    <para>
+     If one does need to escape double quote followed by linebreak in a multiline value,
+     it's possible to use value concatenation in the following way
+     (there is one double-quoted string directly followed by another one):
+    </para>
+    <programlisting>
+<![CDATA[
+long_text = "Lorem \"ipsum\"""
+ dolor" ; Results in: Lorem "ipsum"\n dolor
+]]>
+    </programlisting>
+    <para>
+     Another character with special meaning is <code>$</code> (the dollar sign).
+     It must be escaped if followed by the open curly brace:
+    </para>
+    <programlisting>
+<![CDATA[
+code = "\${test}"
+]]>
+    </programlisting>
+    <para>
+     Escaping characters is not supported in the <constant>INI_SCANNER_RAW</constant> mode
+     (in this mode all characters are processed "as is").
+    </para>
+    <para>
+     Note that the ini parser doesn't support standard escape sequences (<code>\n</code>, <code>\t</code>, etc.).
+     If necessary, post-process the result of <function>parse_ini_file</function> with <function>stripcslashes</function> function.
+    </para>
+   </example>
+  </para>
  </refsect1>
 
  <refsect1 role="notes">