reference/filesystem/functions/fputcsv.xml
898627b9fec5baa51de18adefb9c584369f25aea
...
...
@@ -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.fputcsv">
3
+
<refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<refnamediv>
5
5
<refname>fputcsv</refname>
6
6
<refpurpose>Format line as CSV and write to file pointer</refpurpose>
...
...
@@ -9,17 +9,19 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>int</type><methodname>fputcsv</methodname>
13
-
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
12
+
<type class="union"><type>int</type><type>false</type></type><methodname>fputcsv</methodname>
13
+
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
14
14
<methodparam><type>array</type><parameter>fields</parameter></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_char</parameter><initializer>"\"</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
+
<methodparam choice="opt"><type>string</type><parameter>eol</parameter><initializer>"\n"</initializer></methodparam>
18
19
</methodsynopsis>
19
20
<para>
20
21
<function>fputcsv</function> formats a line (passed as a
21
-
<parameter>fields</parameter> array) as CSV and write it (terminated by a
22
-
newline) to the specified file <parameter>handle</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>.
23
25
</para>
24
26
</refsect1>
25
27

...
...
@@ -28,7 +30,7 @@
28
30
<para>
29
31
<variablelist>
30
32
<varlistentry>
31
-
<term><parameter>handle</parameter></term>
33
+
<term><parameter>stream</parameter></term>
32
34
<listitem>
33
35
&fs.validfp.all;
34
36
</listitem>
...
...
@@ -37,48 +39,51 @@
37
39
<term><parameter>fields</parameter></term>
38
40
<listitem>
39
41
<para>
40
-
An array of values.
42
+
An array of <type>string</type>s.
41
43
</para>
42
44
</listitem>
43
45
</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>
44
55
<varlistentry>
45
-
<term><parameter>delimiter</parameter></term>
56
+
<term><parameter>eol</parameter></term>
46
57
<listitem>
47
58
<para>
48
-
The optional <parameter>delimiter</parameter> parameter sets the field
49
-
delimiter (one character only).
50
-
</para>
51
-
</listitem>
52
-
</varlistentry>
53
-
<varlistentry>
54
-
<term><parameter>enclosure</parameter></term>
55
-
<listitem>
56
-
<para>
57
-
The optional <parameter>enclosure</parameter> parameter sets the field
58
-
enclosure (one character only).
59
-
</para>
60
-
</listitem>
61
-
</varlistentry>
62
-
<varlistentry>
63
-
<term><parameter>escape_char</parameter></term>
64
-
<listitem>
65
-
<para>
66
-
The optional <parameter>escape_char</parameter> parameter sets the
67
-
escape character (one character only).
59
+
The optional <parameter>eol</parameter> parameter sets
60
+
a custom End of Line sequence.
68
61
</para>
69
62
</listitem>
70
63
</varlistentry>
71
64
</variablelist>
72
65
</para>
66
+
&warning.csv.escape-parameter;
67
+
<note>
68
+
<para>
69
+
If an <parameter>enclosure</parameter> character is contained in a field,
70
+
it will be escaped by doubling it, unless it is immediately preceded by an
71
+
<parameter>escape</parameter>.
72
+
</para>
73
+
</note>
73
74
</refsect1>
74
75

75
76
<refsect1 role="returnvalues">
76
77
&reftitle.returnvalues;
77
78
<para>
78
-
Returns the length of the written string&return.falseforfailure;.
79
+
Returns the length of the written string &return.falseforfailure;.
79
80
</para>
80
81
</refsect1>
81
82

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
+

82
87
<refsect1 role="changelog">
83
88
&reftitle.changelog;
84
89
<para>
...
...
@@ -91,10 +96,20 @@
91
96
</row>
92
97
</thead>
93
98
<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>
102
+
<row>
103
+
<entry>8.1.0</entry>
104
+
<entry>
105
+
The optional <parameter>eol</parameter> parameter has been added.
106
+
</entry>
107
+
</row>
94
108
<row>
95
-
<entry>5.5.4</entry>
109
+
<entry>7.4.0</entry>
96
110
<entry>
97
-
The <parameter>escape_char</parameter> parameter was added
111
+
The <parameter>escape</parameter> parameter now also accepts an empty
112
+
string to disable the proprietary escape mechanism.
98
113
</entry>
99
114
</row>
100
115
</tbody>
...
...
@@ -112,16 +127,16 @@
112
127
<![CDATA[
113
128
<?php
114
129

115
-
$list = array (
116
-
array('aaa', 'bbb', 'ccc', 'dddd'),
117
-
array('123', '456', '789'),
118
-
array('"aaa"', '"bbb"')
119
-
);
130
+
$list = [
131
+
['aaa', 'bbb', 'ccc', 'dddd'],
132
+
['123', '456', '789'],
133
+
['"aaa"', '"bbb"']
134
+
];
120
135

121
136
$fp = fopen('file.csv', 'w');
122
137

123
138
foreach ($list as $fields) {
124
-
fputcsv($fp, $fields);
139
+
fputcsv($fp, $fields, ',', '"', '');
125
140
}
126
141

127
142
fclose($fp);
...
...
@@ -141,22 +156,19 @@ aaa,bbb,ccc,dddd
141
156
</para>
142
157
</refsect1>
143
158

144
-
<refsect1 role="notes">
145
-
&reftitle.notes;
146
-
&note.line-endings;
147
-
</refsect1>
148
-

149
159
<refsect1 role="seealso">
150
160
&reftitle.seealso;
151
-
<para>
152
-
<simplelist>
153
-
<member><function>fgetcsv</function></member>
154
-
</simplelist>
155
-
</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>
156
169
</refsect1>
157
170

158
171
</refentry>
159
-

160
172
<!-- Keep this comment at the end of the file
161
173
Local variables:
162
174
mode: sgml
163
175



Translation status