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
...
...
@@ -48,17 +55,17 @@
48
55
unless the split would occur inside an enclosure.
49
56
</para>
50
57
<para>
51
-
Omitting this parameter (or setting it to 0 in PHP
52
-
5.1.0 and later) the maximum line length is not limited, which is
53
-
slightly slower.
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.
54
61
</para>
55
62
</listitem>
56
63
</varlistentry>
57
64
<varlistentry>
58
-
<term><parameter>delimiter</parameter></term>
65
+
<term><parameter>separator</parameter></term>
59
66
<listitem>
60
67
<para>
61
-
The optional <parameter>delimiter</parameter> parameter sets the field delimiter (one character only).
68
+
The optional <parameter>separator</parameter> parameter sets the field separator (one single-byte character only).
62
69
</para>
63
70
</listitem>
64
71
</varlistentry>
...
...
@@ -66,7 +73,7 @@
66
73
<term><parameter>enclosure</parameter></term>
67
74
<listitem>
68
75
<para>
69
-
The optional <parameter>enclosure</parameter> parameter sets the field enclosure character (one character only).
76
+
The optional <parameter>enclosure</parameter> parameter sets the field enclosure character (one single-byte character only).
70
77
</para>
71
78
</listitem>
72
79
</varlistentry>
...
...
@@ -74,8 +81,21 @@
74
81
<term><parameter>escape</parameter></term>
75
82
<listitem>
76
83
<para>
77
-
The optional <parameter>escape</parameter> parameter sets the escape character (one character only).
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.
78
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>
79
99
</listitem>
80
100
</varlistentry>
81
101
</variablelist>
...
...
@@ -85,7 +105,7 @@
85
105
<refsect1 role="returnvalues">
86
106
&reftitle.returnvalues;
87
107
<para>
88
-
Returns an indexed array containing the fields read.
108
+
Returns an indexed array containing the fields read on success, &return.falseforfailure;.
89
109
</para>
90
110
<note>
91
111
<para>
...
...
@@ -95,11 +115,6 @@
95
115
</para>
96
116
</note>
97
117
&note.line-endings;
98
-
<para>
99
-
<function>fgetcsv</function> returns &null; if an invalid
100
-
<parameter>handle</parameter> is supplied or &false; on other errors,
101
-
including end of file.
102
-
</para>
103
118
</refsect1>
104
119

105
120
<refsect1 role="changelog">
...
...
@@ -115,27 +130,16 @@
115
130
</thead>
116
131
<tbody>
117
132
<row>
118
-
<entry>5.3.0</entry>
133
+
<entry>8.0.0</entry>
119
134
<entry>
120
-
The <parameter>escape</parameter> parameter was added
135
+
<parameter>length</parameter> is now nullable.
121
136
</entry>
122
137
</row>
123
138
<row>
124
-
<entry>5.1.0</entry>
139
+
<entry>7.4.0</entry>
125
140
<entry>
126
-
The <parameter>length</parameter> is now optional.
127
-
Default is <literal>0</literal>, meaning no length limit.
128
-
<!--
129
-
Note to documentors: the length parameter was actually
130
-
made optional in PHP 5.0.4 but didn't behave properly.
131
-
Let's gloss over that here. :)
132
-
-->
133
-
</entry>
134
-
</row>
135
-
<row>
136
-
<entry>4.3.5</entry>
137
-
<entry>
138
-
<function>fgetcsv</function> is now binary safe
141
+
The <parameter>escape</parameter> parameter now also accepts an empty
142
+
string to disable the proprietary escape mechanism.
139
143
</entry>
140
144
</row>
141
145
</tbody>
...
...
@@ -171,17 +175,6 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) {
171
175
</para>
172
176
</refsect1>
173
177

174
-
<refsect1 role="notes">
175
-
&reftitle.notes;
176
-
<note>
177
-
<para>
178
-
Locale setting is taken into account by this function. If
179
-
<varname>LANG</varname> is e.g. <literal>en_US.UTF-8</literal>, files in
180
-
one-byte encoding are read wrong by this function.
181
-
</para>
182
-
</note>
183
-
</refsect1>
184
-

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

198
191
</refentry>
199
-

200
192
<!-- Keep this comment at the end of the file
201
193
Local variables:
202
194
mode: sgml
203
195



Tools (Polish Manual)