reference/filesystem/functions/fgetcsv.xml
61374bbe228e8e9c55a24aba59a1e2bb2a871148
...
...
@@ -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,13 @@
22
22
<acronym>CSV</acronym> format and returns an array containing the fields
23
23
read.
24
24
</para>
25
+
<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>
31
+
</note>
25
32
</refsect1>
26
33

27
34
<refsect1 role="parameters">
...
...
@@ -29,7 +36,7 @@
29
36
<para>
30
37
<variablelist>
31
38
<varlistentry>
32
-
<term><parameter>handle</parameter></term>
39
+
<term><parameter>stream</parameter></term>
33
40
<listitem>
34
41
<para>
35
42
A valid file pointer to a file successfully opened by
...
...
@@ -43,18 +50,22 @@
43
50
<listitem>
44
51
<para>
45
52
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.
53
+
the CSV file (allowing for trailing line-end characters). Otherwise the
54
+
line is split in chunks of <parameter>length</parameter> characters,
55
+
unless the split would occur inside an enclosure.
56
+
</para>
57
+
<para>
58
+
Omitting this parameter (or setting it to 0,
59
+
or &null; in PHP 8.0.0 or later) the maximum line length is not limited,
60
+
which is slightly slower.
50
61
</para>
51
62
</listitem>
52
63
</varlistentry>
53
64
<varlistentry>
54
-
<term><parameter>delimiter</parameter></term>
65
+
<term><parameter>separator</parameter></term>
55
66
<listitem>
56
67
<para>
57
-
Set the field delimiter (one character only).
68
+
The optional <parameter>separator</parameter> parameter sets the field separator (one single-byte character only).
58
69
</para>
59
70
</listitem>
60
71
</varlistentry>
...
...
@@ -62,7 +73,7 @@
62
73
<term><parameter>enclosure</parameter></term>
63
74
<listitem>
64
75
<para>
65
-
Set the field enclosure character (one character only).
76
+
The optional <parameter>enclosure</parameter> parameter sets the field enclosure character (one single-byte character only).
66
77
</para>
67
78
</listitem>
68
79
</varlistentry>
...
...
@@ -70,8 +81,21 @@
70
81
<term><parameter>escape</parameter></term>
71
82
<listitem>
72
83
<para>
73
-
Set the escape character (one character only). Defaults as a backslash.
84
+
The optional <parameter>escape</parameter> parameter sets the escape character (at most one single-byte character).
85
+
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
74
86
</para>
87
+
<note>
88
+
<simpara>
89
+
Usually an <parameter>enclosure</parameter> character is escaped inside
90
+
a field by doubling it; however, the <parameter>escape</parameter>
91
+
character can be used as an alternative. So for the default parameter
92
+
values <literal>""</literal> and <literal>\"</literal> have the same
93
+
meaning. Other than allowing to escape the
94
+
<parameter>enclosure</parameter> character the
95
+
<parameter>escape</parameter> character has no special meaning; it isn't
96
+
even meant to escape itself.
97
+
</simpara>
98
+
</note>
75
99
</listitem>
76
100
</varlistentry>
77
101
</variablelist>
...
...
@@ -81,7 +105,7 @@
81
105
<refsect1 role="returnvalues">
82
106
&reftitle.returnvalues;
83
107
<para>
84
-
Returns an indexed array containing the fields read.
108
+
Returns an indexed array containing the fields read on success, &return.falseforfailure;.
85
109
</para>
86
110
<note>
87
111
<para>
...
...
@@ -91,11 +115,6 @@
91
115
</para>
92
116
</note>
93
117
&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>
99
118
</refsect1>
100
119

101
120
<refsect1 role="changelog">
...
...
@@ -111,21 +130,16 @@
111
130
</thead>
112
131
<tbody>
113
132
<row>
114
-
<entry>5.3.0</entry>
133
+
<entry>8.0.0</entry>
115
134
<entry>
116
-
The <parameter>escape</parameter> parameter was added
135
+
<parameter>length</parameter> is now nullable.
117
136
</entry>
118
137
</row>
119
138
<row>
120
-
<entry>4.3.5</entry>
139
+
<entry>7.4.0</entry>
121
140
<entry>
122
-
<function>fgetcsv</function> is now binary safe
123
-
</entry>
124
-
</row>
125
-
<row>
126
-
<entry>4.3.0</entry>
127
-
<entry>
128
-
The <parameter>enclosure</parameter> parameter was added
141
+
The <parameter>escape</parameter> parameter now also accepts an empty
142
+
string to disable the proprietary escape mechanism.
129
143
</entry>
130
144
</row>
131
145
</tbody>
...
...
@@ -161,17 +175,6 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) {
161
175
</para>
162
176
</refsect1>
163
177

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
178
<refsect1 role="seealso">
176
179
&reftitle.seealso;
177
180
<para>
...
...
@@ -186,7 +189,6 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) {
186
189
</refsect1>
187
190

188
191
</refentry>
189
-

190
192
<!-- Keep this comment at the end of the file
191
193
Local variables:
192
194
mode: sgml
193
195



Tools (Chinese (Simplified) Manual)