Skip to content

Commit 73007ad

Browse files
Girgiascmb69
Girgias
and
cmb69
authored
PHP 8.4: CSV related changes and deprecations (#4093)
Co-authored-by: Christoph M. Becker <[email protected]>
1 parent 35ca7f1 commit 73007ad

File tree

7 files changed

+217
-219
lines changed

7 files changed

+217
-219
lines changed

‎reference/filesystem/functions/fgetcsv.xml

+45-14
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,12 @@
2323
read.
2424
</para>
2525
<note>
26-
<para>
27-
The locale settings are taken into account by this function. If
28-
<constant>LC_CTYPE</constant> is e.g. <literal>en_US.UTF-8</literal>, files in
29-
one-byte encodings may be read wrongly by this function.
30-
</para>
26+
<simpara>
27+
The locale settings are taken into account by this function.
28+
For example, data encoded in certain one-byte encodings may be parsed
29+
incorrectly if <constant>LC_CTYPE</constant> is
30+
<literal>en_US.UTF-8</literal>.
31+
</simpara>
3132
</note>
3233
</refsect1>
3334

@@ -96,6 +97,14 @@
9697
even meant to escape itself.
9798
</simpara>
9899
</note>
100+
<warning>
101+
<simpara>
102+
As of PHP 8.4.0, depending on the default value of
103+
<parameter>escape</parameter> is deprecated.
104+
It needs to be provided explicitly either positionally or by the use
105+
of <link linkend="functions.named-arguments">named arguments</link>.
106+
</simpara>
107+
</warning>
99108
</listitem>
100109
</varlistentry>
101110
</variablelist>
@@ -118,6 +127,19 @@
118127
&note.line-endings;
119128
</refsect1>
120129

130+
<refsect1 role="errors">
131+
&reftitle.errors;
132+
<simpara>
133+
Throws a <exceptionname>ValueError</exceptionname> if
134+
<parameter>separator</parameter> or <parameter>enclosure</parameter>
135+
is not one byte long.
136+
</simpara>
137+
<simpara>
138+
Throws a <exceptionname>ValueError</exceptionname> if
139+
<parameter>escape</parameter> is not one byte long or the empty string.
140+
</simpara>
141+
</refsect1>
142+
121143
<refsect1 role="changelog">
122144
&reftitle.changelog;
123145
<para>
@@ -130,6 +152,13 @@
130152
</row>
131153
</thead>
132154
<tbody>
155+
<row>
156+
<entry>8.4.0</entry>
157+
<entry>
158+
Relying on the default value of <parameter>escape</parameter> is now
159+
deprecated.
160+
</entry>
161+
</row>
133162
<row>
134163
<entry>8.0.0</entry>
135164
<entry>
@@ -178,15 +207,17 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) {
178207

179208
<refsect1 role="seealso">
180209
&reftitle.seealso;
181-
<para>
182-
<simplelist>
183-
<member><function>str_getcsv</function></member>
184-
<member><function>explode</function></member>
185-
<member><function>file</function></member>
186-
<member><function>pack</function></member>
187-
<member><function>fputcsv</function></member>
188-
</simplelist>
189-
</para>
210+
<simplelist>
211+
<member><function>fputcsv</function></member>
212+
<member><function>str_getcsv</function></member>
213+
<member><methodname>SplFileObject::fgetcsv</methodname></member>
214+
<member><methodname>SplFileObject::fputcsv</methodname></member>
215+
<member><methodname>SplFileObject::setCsvControl</methodname></member>
216+
<member><methodname>SplFileObject::getCsvControl</methodname></member>
217+
<member><function>explode</function></member>
218+
<member><function>file</function></member>
219+
<member><function>pack</function></member>
220+
</simplelist>
190221
</refsect1>
191222

192223
</refentry>

‎reference/filesystem/functions/fputcsv.xml

+28-41
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook">
3+
<refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>fputcsv</refname>
66
<refpurpose>Format line as CSV and write to file pointer</refpurpose>
@@ -19,8 +19,9 @@
1919
</methodsynopsis>
2020
<para>
2121
<function>fputcsv</function> formats a line (passed as a
22-
<parameter>fields</parameter> array) as CSV and writes it (terminated by a
23-
newline) to the specified file <parameter>stream</parameter>.
22+
<parameter>fields</parameter> array) as <acronym>CSV</acronym> and writes it
23+
(terminated by a <parameter>eol</parameter>) to the specified
24+
<parameter>stream</parameter>.
2425
</para>
2526
</refsect1>
2627

@@ -42,34 +43,15 @@
4243
</para>
4344
</listitem>
4445
</varlistentry>
45-
<varlistentry>
46-
<term><parameter>separator</parameter></term>
47-
<listitem>
48-
<para>
49-
The optional <parameter>separator</parameter> parameter sets the field
50-
delimiter (one single-byte character only).
51-
</para>
52-
</listitem>
53-
</varlistentry>
54-
<varlistentry>
55-
<term><parameter>enclosure</parameter></term>
56-
<listitem>
57-
<para>
58-
The optional <parameter>enclosure</parameter> parameter sets the field
59-
enclosure (one single-byte character only).
60-
</para>
61-
</listitem>
62-
</varlistentry>
63-
<varlistentry>
64-
<term><parameter>escape</parameter></term>
65-
<listitem>
66-
<para>
67-
The optional <parameter>escape</parameter> parameter sets the
68-
escape character (at most one single-byte character).
69-
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
70-
</para>
71-
</listitem>
72-
</varlistentry>
46+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='separator']]]/.)">
47+
<xi:fallback/>
48+
</xi:include>
49+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='enclosure']]]/.)">
50+
<xi:fallback/>
51+
</xi:include>
52+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='escape']]]/.)">
53+
<xi:fallback/>
54+
</xi:include>
7355
<varlistentry>
7456
<term><parameter>eol</parameter></term>
7557
<listitem>
@@ -98,6 +80,10 @@
9880
</para>
9981
</refsect1>
10082

83+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='errors']/.)">
84+
<xi:fallback/>
85+
</xi:include>
86+
10187
<refsect1 role="changelog">
10288
&reftitle.changelog;
10389
<para>
@@ -110,6 +96,9 @@
11096
</row>
11197
</thead>
11298
<tbody>
99+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='changelog']//db:row[db:entry[text()='8.4.0']]/.)">
100+
<xi:fallback/>
101+
</xi:include>
113102
<row>
114103
<entry>8.1.0</entry>
115104
<entry>
@@ -167,18 +156,16 @@ aaa,bbb,ccc,dddd
167156
</para>
168157
</refsect1>
169158

170-
<refsect1 role="notes">
171-
&reftitle.notes;
172-
&note.line-endings;
173-
</refsect1>
174-
175159
<refsect1 role="seealso">
176160
&reftitle.seealso;
177-
<para>
178-
<simplelist>
179-
<member><function>fgetcsv</function></member>
180-
</simplelist>
181-
</para>
161+
<simplelist>
162+
<member><function>fgetcsv</function></member>
163+
<member><function>str_getcsv</function></member>
164+
<member><methodname>SplFileObject::fgetcsv</methodname></member>
165+
<member><methodname>SplFileObject::fputcsv</methodname></member>
166+
<member><methodname>SplFileObject::setCsvControl</methodname></member>
167+
<member><methodname>SplFileObject::getCsvControl</methodname></member>
168+
</simplelist>
182169
</refsect1>
183170

184171
</refentry>

‎reference/spl/splfileobject/fgetcsv.xml

+41-19
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="splfileobject.fgetcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3+
<refentry xml:id="splfileobject.fgetcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>SplFileObject::fgetcsv</refname>
66
<refpurpose>Gets line from file and parse as CSV fields</refpurpose>
@@ -17,13 +17,9 @@
1717
<para>
1818
Gets a line from the file which is in <acronym>CSV</acronym> format and returns an array containing the fields read.
1919
</para>
20-
<note>
21-
<para>
22-
The locale settings are taken into account by this function. If
23-
<constant>LC_CTYPE</constant> is e.g. <literal>en_US.UTF-8</literal>, files in
24-
one-byte encodings may be read wrongly by this function.
25-
</para>
26-
</note>
20+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='description']//db:note/.)">
21+
<xi:fallback/>
22+
</xi:include>
2723
</refsect1>
2824

2925
<refsect1 role="parameters">
@@ -34,23 +30,30 @@
3430
<term><parameter>separator</parameter></term>
3531
<listitem>
3632
<para>
37-
The field delimiter (one single-byte character only). Defaults as a comma or the value set using <methodname>SplFileObject::setCsvControl</methodname>.
33+
The field delimiter (one single-byte character only).
34+
By default <literal>,</literal> or the value set by a prior call to
35+
<methodname>SplFileObject::setCsvControl</methodname>.
3836
</para>
3937
</listitem>
4038
</varlistentry>
4139
<varlistentry>
4240
<term><parameter>enclosure</parameter></term>
4341
<listitem>
4442
<para>
45-
The field enclosure character (one single-byte character only). Defaults as a double quotation mark or the value set using <methodname>SplFileObject::setCsvControl</methodname>.
43+
The field enclosure character (one single-byte character only).
44+
By default <literal>"</literal> or the value set by a prior call to
45+
<methodname>SplFileObject::setCsvControl</methodname>.
4646
</para>
4747
</listitem>
4848
</varlistentry>
4949
<varlistentry>
5050
<term><parameter>escape</parameter></term>
5151
<listitem>
5252
<para>
53-
The escape character (at most one single-byte character). Defaults as a backslash (<literal>\</literal>) or the value set using <methodname>SplFileObject::setCsvControl</methodname>.
53+
The escape character (at most one single-byte character).
54+
The field enclosure character (one single-byte character only).
55+
By default <literal>\</literal> or the value set by a prior call to
56+
<methodname>SplFileObject::setCsvControl</methodname>.
5457
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
5558
</para>
5659
<note>
@@ -65,6 +68,15 @@
6568
even meant to escape itself.
6669
</simpara>
6770
</note>
71+
<warning>
72+
<simpara>
73+
As of PHP 8.4.0, depending on the default value of
74+
<parameter>escape</parameter> is deprecated.
75+
It needs to be provided explicitly either positionally or by the use
76+
of <link linkend="functions.named-arguments">Named Arguments</link>,
77+
or by a call to <methodname>SplFileObject::setCsvControl</methodname>.
78+
</simpara>
79+
</warning>
6880
</listitem>
6981
</varlistentry>
7082
</variablelist>
@@ -86,6 +98,10 @@
8698
</note>
8799
</refsect1>
88100

101+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='errors']/.)">
102+
<xi:fallback/>
103+
</xi:include>
104+
89105
<refsect1 role="changelog">
90106
&reftitle.changelog;
91107
<para>
@@ -98,6 +114,9 @@
98114
</row>
99115
</thead>
100116
<tbody>
117+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='changelog']//db:row[db:entry[text()='8.4.0']]/.)">
118+
<xi:fallback/>
119+
</xi:include>
101120
<row>
102121
<entry>7.4.0</entry>
103122
<entry>
@@ -169,14 +188,17 @@ A salmon is a fish with 0 legs
169188

170189
<refsect1 role="seealso">
171190
&reftitle.seealso;
172-
<para>
173-
<simplelist>
174-
<member><methodname>SplFileObject::setCsvControl</methodname></member>
175-
<member><methodname>SplFileObject::setFlags</methodname></member>
176-
<member><link linkend="splfileobject.constants.read-csv">SplFileObject::READ_CSV</link></member>
177-
<member><methodname>SplFileObject::current</methodname></member>
178-
</simplelist>
179-
</para>
191+
<simplelist>
192+
<member><methodname>SplFileObject::fputcsv</methodname></member>
193+
<member><methodname>SplFileObject::setCsvControl</methodname></member>
194+
<member><methodname>SplFileObject::getCsvControl</methodname></member>
195+
<member><methodname>SplFileObject::setFlags</methodname></member>
196+
<member><constant>SplFileObject::READ_CSV</constant></member>
197+
<member><methodname>SplFileObject::current</methodname></member>
198+
<member><function>fputcsv</function></member>
199+
<member><function>fgetcsv</function></member>
200+
<member><function>str_getcsv</function></member>
201+
</simplelist>
180202
</refsect1>
181203

182204
</refentry>

0 commit comments

Comments
 (0)