reference/filesystem/functions/fgetcsv.xml
781f2ec04ee8817687e5e333bc3e64ab973322d7
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fgetcsv">
3
+
<refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>fgetcsv</refname>
6
6
<refpurpose>Gets line from file pointer and parse for CSV fields</refpurpose>
...
...
@@ -9,12 +9,12 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>array</type><methodname>fgetcsv</methodname>
13
-
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>0</initializer></methodparam>
15
-
<methodparam choice="opt"><type>string</type><parameter>delimiter</parameter><initializer>','</initializer></methodparam>
16
-
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>'"'</initializer></methodparam>
17
-
<methodparam choice="opt"><type>string</type><parameter>escape</parameter><initializer>'\\'</initializer></methodparam>
12
+
<type class="union"><type>array</type><type>false</type></type><methodname>fgetcsv</methodname>
13
+
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
15
+
<methodparam choice="opt"><type>string</type><parameter>separator</parameter><initializer>","</initializer></methodparam>
16
+
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>"\""</initializer></methodparam>
17
+
<methodparam choice="opt"><type>string</type><parameter>escape</parameter><initializer>"\\"</initializer></methodparam>
18
18
</methodsynopsis>
19
19
<para>
20
20
Similar to <function>fgets</function> except that
...
...
@@ -22,6 +22,14 @@
22
22
<acronym>CSV</acronym> format and returns an array containing the fields
23
23
read.
24
24
</para>
25
+
<note>
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>
32
+
</note>
25
33
</refsect1>
26
34

27
35
<refsect1 role="parameters">
...
...
@@ -29,7 +37,7 @@
29
37
<para>
30
38
<variablelist>
31
39
<varlistentry>
32
-
<term><parameter>handle</parameter></term>
40
+
<term><parameter>stream</parameter></term>
33
41
<listitem>
34
42
<para>
35
43
A valid file pointer to a file successfully opened by
...
...
@@ -43,18 +51,23 @@
43
51
<listitem>
44
52
<para>
45
53
Must be greater than the longest line (in characters) to be found in
46
-
the CSV file (allowing for trailing line-end characters). It became
47
-
optional in PHP 5. Omitting this parameter (or setting it to 0 in PHP
48
-
5.0.4 and later) the maximum line length is not limited, which is
49
-
slightly slower.
54
+
the CSV file (allowing for trailing line-end characters). Otherwise the
55
+
line is split in chunks of <parameter>length</parameter> characters,
56
+
unless the split would occur inside an enclosure.
57
+
</para>
58
+
<para>
59
+
Omitting this parameter (or setting it to 0,
60
+
or &null; in PHP 8.0.0 or later) the maximum line length is not limited,
61
+
which is slightly slower.
50
62
</para>
51
63
</listitem>
52
64
</varlistentry>
53
65
<varlistentry>
54
-
<term><parameter>delimiter</parameter></term>
66
+
<term><parameter>separator</parameter></term>
55
67
<listitem>
56
68
<para>
57
-
Set the field delimiter (one character only).
69
+
The <parameter>separator</parameter> parameter sets the field separator.
70
+
It must be a single byte character.
58
71
</para>
59
72
</listitem>
60
73
</varlistentry>
...
...
@@ -62,7 +75,8 @@
62
75
<term><parameter>enclosure</parameter></term>
63
76
<listitem>
64
77
<para>
65
-
Set the field enclosure character (one character only).
78
+
The <parameter>enclosure</parameter> parameter sets the field enclosure character.
79
+
It must be a single byte character.
66
80
</para>
67
81
</listitem>
68
82
</varlistentry>
...
...
@@ -70,18 +84,41 @@
70
84
<term><parameter>escape</parameter></term>
71
85
<listitem>
72
86
<para>
73
-
Set the escape character (one character only). Defaults as a backslash.
87
+
The <parameter>escape</parameter> parameter sets the escape character.
88
+
It must be a single byte character or the empty string.
89
+
The empty string (<literal>""</literal>) disables the proprietary escape mechanism.
74
90
</para>
91
+
<note>
92
+
<simpara>
93
+
Usually an <parameter>enclosure</parameter> character is escaped inside
94
+
a field by doubling it; however, the <parameter>escape</parameter>
95
+
character can be used as an alternative. So for the default parameter
96
+
values <literal>""</literal> and <literal>\"</literal> have the same
97
+
meaning. Other than allowing to escape the
98
+
<parameter>enclosure</parameter> character the
99
+
<parameter>escape</parameter> character has no special meaning; it isn't
100
+
even meant to escape itself.
101
+
</simpara>
102
+
</note>
103
+
<warning>
104
+
<simpara>
105
+
As of PHP 8.4.0, depending on the default value of
106
+
<parameter>escape</parameter> is deprecated.
107
+
It needs to be provided explicitly either positionally or by the use
108
+
of <link linkend="functions.named-arguments">named arguments</link>.
109
+
</simpara>
110
+
</warning>
75
111
</listitem>
76
112
</varlistentry>
77
113
</variablelist>
78
114
</para>
115
+
&warning.csv.escape-parameter;
79
116
</refsect1>
80
117

81
118
<refsect1 role="returnvalues">
82
119
&reftitle.returnvalues;
83
120
<para>
84
-
Returns an indexed array containing the fields read.
121
+
Returns an indexed array containing the fields read on success, &return.falseforfailure;.
85
122
</para>
86
123
<note>
87
124
<para>
...
...
@@ -91,11 +128,19 @@
91
128
</para>
92
129
</note>
93
130
&note.line-endings;
94
-
<para>
95
-
<function>fgetcsv</function> returns &null; if an invalid
96
-
<parameter>handle</parameter> is supplied or &false; on other errors,
97
-
including end of file.
98
-
</para>
131
+
</refsect1>
132
+

133
+
<refsect1 role="errors">
134
+
&reftitle.errors;
135
+
<simpara>
136
+
Throws a <exceptionname>ValueError</exceptionname> if
137
+
<parameter>separator</parameter> or <parameter>enclosure</parameter>
138
+
is not one byte long.
139
+
</simpara>
140
+
<simpara>
141
+
Throws a <exceptionname>ValueError</exceptionname> if
142
+
<parameter>escape</parameter> is not one byte long or the empty string.
143
+
</simpara>
99
144
</refsect1>
100
145

101
146
<refsect1 role="changelog">
...
...
@@ -111,21 +156,31 @@
111
156
</thead>
112
157
<tbody>
113
158
<row>
114
-
<entry>5.3.0</entry>
159
+
<entry>8.4.0</entry>
115
160
<entry>
116
-
The <parameter>escape</parameter> parameter was added
161
+
Relying on the default value of <parameter>escape</parameter> is now
162
+
deprecated.
117
163
</entry>
118
164
</row>
119
165
<row>
120
-
<entry>4.3.5</entry>
166
+
<entry>8.3.0</entry>
121
167
<entry>
122
-
<function>fgetcsv</function> is now binary safe
168
+
An empty string is returned instead of a string with a single
169
+
null byte for the last field if it contains only an unterminated
170
+
enclosure.
123
171
</entry>
124
172
</row>
125
173
<row>
126
-
<entry>4.3.0</entry>
174
+
<entry>8.0.0</entry>
127
175
<entry>
128
-
The <parameter>enclosure</parameter> parameter was added
176
+
<parameter>length</parameter> is now nullable.
177
+
</entry>
178
+
</row>
179
+
<row>
180
+
<entry>7.4.0</entry>
181
+
<entry>
182
+
The <parameter>escape</parameter> parameter now also accepts an empty
183
+
string to disable the proprietary escape mechanism.
129
184
</entry>
130
185
</row>
131
186
</tbody>
...
...
@@ -161,32 +216,22 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) {
161
216
</para>
162
217
</refsect1>
163
218

164
-
<refsect1 role="notes">
165
-
&reftitle.notes;
166
-
<note>
167
-
<para>
168
-
Locale setting is taken into account by this function. If
169
-
<varname>LANG</varname> is e.g. <literal>en_US.UTF-8</literal>, files in
170
-
one-byte encoding are read wrong by this function.
171
-
</para>
172
-
</note>
173
-
</refsect1>
174
-

175
219
<refsect1 role="seealso">
176
220
&reftitle.seealso;
177
-
<para>
178
-
<simplelist>
179
-
<member><function>str_getcsv</function></member>
180
-
<member><function>explode</function></member>
181
-
<member><function>file</function></member>
182
-
<member><function>pack</function></member>
183
-
<member><function>fputcsv</function></member>
184
-
</simplelist>
185
-
</para>
221
+
<simplelist>
222
+
<member><function>fputcsv</function></member>
223
+
<member><function>str_getcsv</function></member>
224
+
<member><methodname>SplFileObject::fgetcsv</methodname></member>
225
+
<member><methodname>SplFileObject::fputcsv</methodname></member>
226
+
<member><methodname>SplFileObject::setCsvControl</methodname></member>
227
+
<member><methodname>SplFileObject::getCsvControl</methodname></member>
228
+
<member><function>explode</function></member>
229
+
<member><function>file</function></member>
230
+
<member><function>pack</function></member>
231
+
</simplelist>
186
232
</refsect1>
187
233

188
234
</refentry>
189
-

190
235
<!-- Keep this comment at the end of the file
191
236
Local variables:
192
237
mode: sgml
193
238



Translation status