Add explicit warning about CSV function's escape parameter

php · Sep 24, 2024 · 2f999e7 · 2f999e7
1 parent 6f5c53e
commit 2f999e7
Show file tree

Hide file tree

Showing 7 changed files with 23 additions and 7 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 1cdefe36cdfc0e3acaff6a0db918d4b037081aa8 Maintainer: adiel Status: ready --><!-- CREDITS: adiel, ae, atomotavio, fabioluciano, felipe, klaussilveira, rafaelbernard, leonardolara, fernandowobeto -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: adiel Status: ready --><!-- CREDITS: adiel, ae, atomotavio, fabioluciano, felipe, klaussilveira, rafaelbernard, leonardolara, fernandowobeto -->
 
 <!ENTITY installation.enabled.disable 'Esta extensão está habilitada por padrão. Ela pode ser desabilitada usando a seguinte opção em tempo de compilação: '>
 
@@ -1060,6 +1060,16 @@ e testes.</simpara></warning>'>
  </entry>
 </row>'>
 
+<!-- CSV -->
+<!ENTITY warning.csv.escape-parameter '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"><simpara>
+ Quando o parâmetro <parameter>escape</parameter> for definido para algo diferente de uma string vazia
+ (<literal>""</literal>), isso pode resultar em um CSV que não esteja conforme a
+ <link xlink:href="&url.rfc;4180">RFC 4180</link> ou que não seja capaz de sobreviver a uma viagem de ida e volta
+ através das funções CSV do PHP. O padrão para <parameter>escape</parameter> é
+ <literal>"\\"</literal>, portanto é recomendado defini-lo explicitamente para a string vazia.
+ O valor padrão será alterado em uma versão futura do PHP, mas não antes do PHP 9.0.
+</simpara></warning>'>
+
 <!-- DBM notes -->
 
 <!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

diff --git a/reference/filesystem/functions/fgetcsv.xml b/reference/filesystem/functions/fgetcsv.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: thiago Status: ready --><!-- CREDITS: diogo, rarruda, ae, leonardolara -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: thiago Status: ready --><!-- CREDITS: diogo, rarruda, ae, leonardolara -->
 <refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>fgetcsv</refname>
@@ -100,6 +100,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/filesystem/functions/fputcsv.xml b/reference/filesystem/functions/fputcsv.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 291d60430d25f2b508bebb5720b41cc68f9a6ec1 Maintainer: thiago Status: ready --><!-- CREDITS: diogo,narigone,leonardolara -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: thiago Status: ready --><!-- CREDITS: diogo,narigone,leonardolara -->
 <refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>fputcsv</refname>
@@ -81,6 +81,7 @@
      </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
   <note>
    <para>
     Se um caractere <parameter>enclosure</parameter> estiver contido em um campo,

diff --git a/reference/spl/splfileobject/fgetcsv.xml b/reference/spl/splfileobject/fgetcsv.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: fernandowobeto Status: ready --><!-- CREDITS: fernandowobeto -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: fernandowobeto Status: ready --><!-- CREDITS: fernandowobeto -->
 <refentry xml:id="splfileobject.fgetcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>SplFileObject::fgetcsv</refname>
@@ -69,6 +69,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/spl/splfileobject/fputcsv.xml b/reference/spl/splfileobject/fputcsv.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: d51166ca16fda8e766849505b84f9306ef443f71 Maintainer: fernandowobeto Status: ready --><!-- CREDITS: fernandowobeto -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: fernandowobeto Status: ready --><!-- CREDITS: fernandowobeto -->
 <refentry xml:id="splfileobject.fputcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>SplFileObject::fputcsv</refname>
@@ -70,6 +70,7 @@
     </listitem>
    </varlistentry>
   </variablelist>
+  &warning.csv.escape-parameter;
   <note>
    <para>
     Se um caractere de <parameter>enclosure</parameter> estiver contido em um campo,

diff --git a/reference/spl/splfileobject/setcsvcontrol.xml b/reference/spl/splfileobject/setcsvcontrol.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: d51166ca16fda8e766849505b84f9306ef443f71 Maintainer: fernandowobeto Status: ready --><!-- CREDITS: fernandowobeto -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: fernandowobeto Status: ready --><!-- CREDITS: fernandowobeto -->
 <refentry xml:id="splfileobject.setcsvcontrol" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>SplFileObject::setCsvControl</refname>
@@ -50,6 +50,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/strings/functions/str-getcsv.xml b/reference/strings/functions/str-getcsv.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: leonardolara Status: ready --><!-- CREDITS: lisaldo,felipe,leonardolara -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: leonardolara Status: ready --><!-- CREDITS: lisaldo,felipe,leonardolara -->
 <refentry xml:id="function.str-getcsv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>str_getcsv</refname>
@@ -82,6 +82,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">