reference/pdo/pdostatement/fetchall.xml
44bcc82c7d1a0dea5578093833d3172c0c742f5a
...
...
@@ -1,21 +1,37 @@
1
-
<?xml version="1.0" encoding="UTF-8"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="pdostatement.fetchall" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>PDOStatement::fetchAll</refname>
6
6
<refpurpose>
7
-
Returns an array containing all of the result set rows
7
+
Fetches the remaining rows from a result set
8
8
</refpurpose>
9
9
</refnamediv>
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<methodsynopsis>
13
-
<type>array</type><methodname>PDOStatement::fetchAll</methodname>
14
-
<methodparam choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
15
-
<methodparam choice="opt"><type>mixed</type><parameter>fetch_argument</parameter></methodparam>
16
-
<methodparam choice="opt"><type>array</type><parameter>ctor_args</parameter><initializer>array()</initializer></methodparam>
12
+
<methodsynopsis role="PDOStatement">
13
+
<modifier>public</modifier> <type>array</type><methodname>PDOStatement::fetchAll</methodname>
14
+
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>PDO::FETCH_DEFAULT</initializer></methodparam>
17
15
</methodsynopsis>
18
16

17
+
<methodsynopsis role="PDOStatement">
18
+
<modifier>public</modifier> <type>array</type><methodname>PDOStatement::fetchAll</methodname>
19
+
<methodparam><type>int</type><parameter>mode</parameter><initializer>PDO::FETCH_COLUMN</initializer></methodparam>
20
+
<methodparam><type>int</type><parameter>column</parameter></methodparam>
21
+
</methodsynopsis>
22
+

23
+
<methodsynopsis role="PDOStatement">
24
+
<modifier>public</modifier> <type>array</type><methodname>PDOStatement::fetchAll</methodname>
25
+
<methodparam><type>int</type><parameter>mode</parameter><initializer>PDO::FETCH_CLASS</initializer></methodparam>
26
+
<methodparam><type>string</type><parameter>class</parameter></methodparam>
27
+
<methodparam><type class="union"><type>array</type><type>null</type></type><parameter>constructorArgs</parameter></methodparam>
28
+
</methodsynopsis>
29
+

30
+
<methodsynopsis role="PDOStatement">
31
+
<modifier>public</modifier> <type>array</type><methodname>PDOStatement::fetchAll</methodname>
32
+
<methodparam><type>int</type><parameter>mode</parameter><initializer>PDO::FETCH_FUNC</initializer></methodparam>
33
+
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
34
+
</methodsynopsis>
19
35
</refsect1>
20
36

21
37
<refsect1 role="parameters">
...
...
@@ -23,11 +39,11 @@
23
39
<para>
24
40
<variablelist>
25
41
<varlistentry>
26
-
<term><parameter>fetch_style</parameter></term>
42
+
<term><parameter>mode</parameter></term>
27
43
<listitem>
28
44
<para>
29
45
Controls the contents of the returned array as documented in
30
-
<function>PDOStatement::fetch</function>.
46
+
<methodname>PDOStatement::fetch</methodname>.
31
47
Defaults to value of <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>
32
48
(which defaults to <constant>PDO::FETCH_BOTH</constant>)
33
49
</para>
...
...
@@ -35,58 +51,68 @@
35
51
To return an array consisting of all values of a single column from
36
52
the result set, specify <constant>PDO::FETCH_COLUMN</constant>. You
37
53
can specify which column you want with the
38
-
<parameter>column-index</parameter> parameter.
54
+
<parameter>column</parameter> parameter.
39
55
</para>
40
56
<para>
41
-
To fetch only the unique values of a single column from the result set,
42
-
bitwise-OR <constant>PDO::FETCH_COLUMN</constant> with
43
-
<constant>PDO::FETCH_UNIQUE</constant>.
57
+
To index the resulting array by a certain column's value (instead of
58
+
consecutive numbers), put this column's name first in the column
59
+
list in SQL, and use <constant>PDO::FETCH_UNIQUE</constant>.
60
+
This column must contain only unique values or some data will be lost.
44
61
</para>
45
62
<para>
46
-
To return an associative array grouped by the values of a specified
47
-
column, bitwise-OR <constant>PDO::FETCH_COLUMN</constant> with
48
-
<constant>PDO::FETCH_GROUP</constant>.
63
+
To group results in the form of a 3-dimensional array indexed by values
64
+
of a specified column, put this column's name first in
65
+
the column list in SQL and use <constant>PDO::FETCH_GROUP</constant>.
66
+
</para>
67
+
<para>
68
+
To group results in the form of a 2-dimensional array
69
+
use bitwise-OR <constant>PDO::FETCH_GROUP</constant> with
70
+
<constant>PDO::FETCH_COLUMN</constant>.
71
+
The results will be grouped by the first column, with the array element's value
72
+
being a list array of the corresponding entries from the second column.
49
73
</para>
50
74
</listitem>
51
75
</varlistentry>
76
+
</variablelist>
77
+
The following are dynamic parameters that are depending on the fetch mode.
78
+
They can't be used with named parameters.
79
+
<variablelist>
52
80
<varlistentry>
53
-
<term><parameter>fetch_argument</parameter></term>
81
+
<term><parameter>column</parameter></term>
54
82
<listitem>
55
83
<para>
56
-
This argument have a different meaning depending on the value of
57
-
the <parameter>fetch_style</parameter> parameter:
58
-
<itemizedlist>
59
-
<listitem>
60
-
<para>
61
-
<constant>PDO::FETCH_COLUMN</constant>: Returns the indicated 0-indexed
62
-
column.
63
-
</para>
64
-
</listitem>
65
-
<listitem>
66
-
<para>
67
-
<constant>PDO::FETCH_CLASS</constant>: Returns instances of the specified
68
-
class, mapping the columns of each row to named properties in the class.
69
-
</para>
70
-
</listitem>
71
-
<listitem>
72
-
<para>
73
-
<constant>PDO::FETCH_FUNC</constant>: Returns the results of calling the
74
-
specified function, using each row's columns as parameters in the call.
75
-
</para>
76
-
</listitem>
77
-
</itemizedlist>
84
+
Used with <constant>PDO::FETCH_COLUMN</constant>. Returns the indicated
85
+
0-indexed column.
78
86
</para>
79
87
</listitem>
80
88
</varlistentry>
81
89
<varlistentry>
82
-
<term><parameter>ctor_args</parameter></term>
90
+
<term><parameter>class</parameter></term>
83
91
<listitem>
84
92
<para>
85
-
Arguments of custom class constructor when the <parameter>fetch_style</parameter>
93
+
Used with <constant>PDO::FETCH_CLASS</constant>. Returns instances of the specified
94
+
class, mapping the columns of each row to named properties in the class.
95
+
</para>
96
+
</listitem>
97
+
</varlistentry>
98
+
<varlistentry>
99
+
<term><parameter>constructorArgs</parameter></term>
100
+
<listitem>
101
+
<para>
102
+
Arguments of custom class constructor when the <parameter>mode</parameter>
86
103
parameter is <constant>PDO::FETCH_CLASS</constant>.
87
104
</para>
88
105
</listitem>
89
106
</varlistentry>
107
+
<varlistentry>
108
+
<term><parameter>callback</parameter></term>
109
+
<listitem>
110
+
<para>
111
+
Used with <constant>PDO::FETCH_FUNC</constant>. Returns the results of calling the
112
+
specified function, using each row's columns as parameters in the call.
113
+
</para>
114
+
</listitem>
115
+
</varlistentry>
90
116
</variablelist>
91
117
</para>
92
118
</refsect1>
...
...
@@ -94,10 +120,11 @@
94
120
<refsect1 role="returnvalues">
95
121
&reftitle.returnvalues;
96
122
<para>
97
-
<function>PDOStatement::fetchAll</function> returns an array containing
123
+
<methodname>PDOStatement::fetchAll</methodname> returns an array containing
98
124
all of the remaining rows in the result set. The array represents each
99
125
row as either an array of column values or an object with properties
100
-
corresponding to each column name.
126
+
corresponding to each column name. An empty array is returned if there
127
+
are zero results to fetch.
101
128
</para>
102
129
<para>
103
130
Using this method to fetch large result sets will result in a heavy
...
...
@@ -109,6 +136,34 @@
109
136
</para>
110
137
</refsect1>
111
138

139
+
<refsect1 role="errors">
140
+
&reftitle.errors;
141
+
&pdo.errors;
142
+
</refsect1>
143
+

144
+
<refsect1 role="changelog">
145
+
&reftitle.changelog;
146
+
<informaltable>
147
+
<tgroup cols="2">
148
+
<thead>
149
+
<row>
150
+
<entry>&Version;</entry>
151
+
<entry>&Description;</entry>
152
+
</row>
153
+
</thead>
154
+
<tbody>
155
+
<row>
156
+
<entry>8.0.0</entry>
157
+
<entry>
158
+
This method always returns an &array; now, while previously &false; may have
159
+
been returned on failure.
160
+
</entry>
161
+
</row>
162
+
</tbody>
163
+
</tgroup>
164
+
</informaltable>
165
+
</refsect1>
166
+

112
167
<refsect1 role="examples">
113
168
&reftitle.examples;
114
169
<para>
...
...
@@ -120,7 +175,7 @@ $sth = $dbh->prepare("SELECT name, colour FROM fruit");
120
175
$sth->execute();
121
176

122
177
/* Fetch all of the remaining rows in the result set */
123
-
print("Fetch all of the remaining rows in the result set:\n");
178
+
print "Fetch all of the remaining rows in the result set:\n";
124
179
$result = $sth->fetchAll();
125
180
print_r($result);
126
181
?>
...
...
@@ -134,17 +189,25 @@ Array
134
189
(
135
190
[0] => Array
136
191
(
137
-
[NAME] => pear
192
+
[name] => apple
193
+
[0] => apple
194
+
[colour] => red
195
+
[1] => red
196
+
)
197
+

198
+
[1] => Array
199
+
(
200
+
[name] => pear
138
201
[0] => pear
139
-
[COLOUR] => green
202
+
[colour] => green
140
203
[1] => green
141
204
)
142
205

143
-
[1] => Array
206
+
[2] => Array
144
207
(
145
-
[NAME] => watermelon
208
+
[name] => watermelon
146
209
[0] => watermelon
147
-
[COLOUR] => pink
210
+
[colour] => pink
148
211
[1] => pink
149
212
)
150
213

...
...
@@ -230,7 +293,7 @@ array(3) {
230
293
["watermelon"]=>
231
294
array(1) {
232
295
[0]=>
233
-
string(5) "green"
296
+
string(5) "pink"
234
297
}
235
298
}
236
299

...
...
@@ -283,6 +346,20 @@ array(3) {
283
346
["colour"]=>
284
347
string(4) "pink"
285
348
}
349
+
[3]=>
350
+
object(fruit)#4 (2) {
351
+
["name"]=>
352
+
string(5) "apple"
353
+
["colour"]=>
354
+
string(3) "red"
355
+
}
356
+
[4]=>
357
+
object(fruit)#5 (2) {
358
+
["name"]=>
359
+
string(4) "pear"
360
+
["colour"]=>
361
+
string(5) "green"
362
+
}
286
363
}
287
364
]]>
288
365
</screen>
...
...
@@ -317,6 +394,10 @@ array(3) {
317
394
string(12) "pear: yellow"
318
395
[2]=>
319
396
string(16) "watermelon: pink"
397
+
[3]=>
398
+
string(10) "apple: red"
399
+
[4]=>
400
+
string(11) "pear: green"
320
401
}
321
402
]]>
322
403
</screen>
...
...
@@ -329,16 +410,15 @@ array(3) {
329
410
&reftitle.seealso;
330
411
<para>
331
412
<simplelist>
332
-
<member><function>PDO::query</function></member>
333
-
<member><function>PDOStatement::fetch</function></member>
334
-
<member><function>PDOStatement::fetchColumn</function></member>
335
-
<member><function>PDO::prepare</function></member>
336
-
<member><function>PDOStatement::setFetchMode</function></member>
413
+
<member><methodname>PDO::query</methodname></member>
414
+
<member><methodname>PDOStatement::fetch</methodname></member>
415
+
<member><methodname>PDOStatement::fetchColumn</methodname></member>
416
+
<member><methodname>PDO::prepare</methodname></member>
417
+
<member><methodname>PDOStatement::setFetchMode</methodname></member>
337
418
</simplelist>
338
419
</para>
339
420
</refsect1>
340
421
</refentry>
341
-

342
422
<!-- Keep this comment at the end of the file
343
423
Local variables:
344
424
mode: sgml
345
425



Translation status