reference/pdo/pdostatement/fetch.xml
daf4cc624df3c21d472149725feb377b1beedb04
...
...
@@ -1,4 +1,4 @@
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.fetch" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
...
...
@@ -9,16 +9,16 @@
9
9
</refnamediv>
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<methodsynopsis>
13
-
<type>mixed</type><methodname>PDOStatement::fetch</methodname>
14
-
<methodparam choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>cursor_orientation</parameter><initializer>PDO::FETCH_ORI_NEXT</initializer></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>cursor_offset</parameter><initializer>0</initializer></methodparam>
12
+
<methodsynopsis role="PDOStatement">
13
+
<modifier>public</modifier> <type>mixed</type><methodname>PDOStatement::fetch</methodname>
14
+
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>PDO::FETCH_DEFAULT</initializer></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter>cursorOrientation</parameter><initializer>PDO::FETCH_ORI_NEXT</initializer></methodparam>
16
+
<methodparam choice="opt"><type>int</type><parameter>cursorOffset</parameter><initializer>0</initializer></methodparam>
17
17
</methodsynopsis>
18
18

19
19
<para>
20
20
Fetches a row from a result set associated with a PDOStatement object. The
21
-
<parameter>fetch_style</parameter> parameter determines how PDO returns
21
+
<parameter>mode</parameter> parameter determines how PDO returns
22
22
the row.
23
23
</para>
24
24
</refsect1>
...
...
@@ -28,7 +28,7 @@
28
28
<para>
29
29
<variablelist>
30
30
<varlistentry>
31
-
<term><parameter>fetch_style</parameter></term>
31
+
<term><parameter>mode</parameter></term>
32
32
<listitem>
33
33
<para>
34
34
Controls how the next row will be returned to the caller. This value
...
...
@@ -48,13 +48,15 @@
48
48
<listitem><para>
49
49
<literal>PDO::FETCH_BOUND</literal>: returns &true; and assigns the
50
50
values of the columns in your result set to the PHP variables to which
51
-
they were bound with the <function>PDOStatement::bindColumn</function>
51
+
they were bound with the <methodname>PDOStatement::bindColumn</methodname>
52
52
method
53
53
</para></listitem>
54
54
<listitem><para>
55
55
<literal>PDO::FETCH_CLASS</literal>: returns a new instance of the
56
56
requested class, mapping the columns of the result set to named
57
-
properties in the class. If <parameter>fetch_style</parameter>
57
+
properties in the class, and calling the constructor afterwards, unless
58
+
<literal>PDO::FETCH_PROPS_LATE</literal> is also given.
59
+
If <parameter>mode</parameter>
58
60
includes PDO::FETCH_CLASSTYPE (e.g. <literal>PDO::FETCH_CLASS |
59
61
PDO::FETCH_CLASSTYPE</literal>) then the name of the class is
60
62
determined from a value of the first column.
...
...
@@ -67,7 +69,15 @@
67
69
<listitem><para>
68
70
<literal>PDO::FETCH_LAZY</literal>: combines
69
71
<literal>PDO::FETCH_BOTH</literal> and <literal>PDO::FETCH_OBJ</literal>,
70
-
creating the object variable names as they are accessed
72
+
and is returning a <classname>PDORow</classname> object
73
+
which is creating the object property names as they are accessed.
74
+
</para></listitem>
75
+
<listitem><para>
76
+
<literal>PDO::FETCH_NAMED</literal>: returns an array with the same
77
+
form as <literal>PDO::FETCH_ASSOC</literal>, except that if there are
78
+
multiple columns with the same name, the value referred to by that
79
+
key will be an array of all the values in the row that had that
80
+
column name
71
81
</para></listitem>
72
82
<listitem><para>
73
83
<literal>PDO::FETCH_NUM</literal>: returns an array indexed by column
...
...
@@ -78,12 +88,18 @@
78
88
property names that correspond to the column names returned in your
79
89
result set
80
90
</para></listitem>
91
+
<listitem><para>
92
+
<literal>PDO::FETCH_PROPS_LATE</literal>: when used with
93
+
<literal>PDO::FETCH_CLASS</literal>, the constructor of the class is
94
+
called before the properties are assigned from the respective column
95
+
values.
96
+
</para></listitem>
81
97
</itemizedlist>
82
98
</para>
83
99
</listitem>
84
100
</varlistentry>
85
101
<varlistentry>
86
-
<term><parameter>cursor_orientation</parameter></term>
102
+
<term><parameter>cursorOrientation</parameter></term>
87
103
<listitem>
88
104
<para>
89
105
For a PDOStatement object representing a scrollable cursor, this
...
...
@@ -93,25 +109,25 @@
93
109
scrollable cursor for your PDOStatement object, you must set the
94
110
<literal>PDO::ATTR_CURSOR</literal> attribute to
95
111
<literal>PDO::CURSOR_SCROLL</literal> when you prepare the SQL
96
-
statement with <function>PDO::prepare</function>.
112
+
statement with <methodname>PDO::prepare</methodname>.
97
113
</para>
98
114
</listitem>
99
115
</varlistentry>
100
116
<varlistentry>
101
-
<term><parameter>offset</parameter></term>
117
+
<term><parameter>cursorOffset</parameter></term>
102
118
<listitem>
103
119
<para>
104
120
For a PDOStatement object representing a scrollable cursor for which
105
-
the <literal>cursor_orientation</literal> parameter is set to
121
+
the <parameter>cursorOrientation</parameter> parameter is set to
106
122
<literal>PDO::FETCH_ORI_ABS</literal>, this value specifies the
107
123
absolute number of the row in the result set that shall be fetched.
108
124
</para>
109
125
<para>
110
126
For a PDOStatement object representing a scrollable cursor for which
111
-
the <literal>cursor_orientation</literal> parameter is set to
127
+
the <parameter>cursorOrientation</parameter> parameter is set to
112
128
<literal>PDO::FETCH_ORI_REL</literal>, this value specifies the
113
129
row to fetch relative to the cursor position before
114
-
<function>PDOStatement::fetch</function> was called.
130
+
<methodname>PDOStatement::fetch</methodname> was called.
115
131
</para>
116
132
</listitem>
117
133
</varlistentry>
...
...
@@ -123,10 +139,15 @@
123
139
&reftitle.returnvalues;
124
140
<para>
125
141
The return value of this function on success depends on the fetch type. In
126
-
all cases, &false; is returned on failure.
142
+
all cases, &false; is returned on failure or if there are no more rows.
127
143
</para>
128
144
</refsect1>
129
145

146
+
<refsect1 role="errors">
147
+
&reftitle.errors;
148
+
&pdo.errors;
149
+
</refsect1>
150
+

130
151
<refsect1 role="examples">
131
152
&reftitle.examples;
132
153
<para>
...
...
@@ -138,29 +159,29 @@ $sth = $dbh->prepare("SELECT name, colour FROM fruit");
138
159
$sth->execute();
139
160

140
161
/* Exercise PDOStatement::fetch styles */
141
-
print("PDO::FETCH_ASSOC: ");
142
-
print("Return next row as an array indexed by column name\n");
162
+
print "PDO::FETCH_ASSOC: ";
163
+
print "Return next row as an array indexed by column name\n";
143
164
$result = $sth->fetch(PDO::FETCH_ASSOC);
144
165
print_r($result);
145
-
print("\n");
166
+
print "\n";
146
167

147
-
print("PDO::FETCH_BOTH: ");
148
-
print("Return next row as an array indexed by both column name and number\n");
168
+
print "PDO::FETCH_BOTH: ";
169
+
print "Return next row as an array indexed by both column name and number\n";
149
170
$result = $sth->fetch(PDO::FETCH_BOTH);
150
171
print_r($result);
151
-
print("\n");
172
+
print "\n";
152
173

153
-
print("PDO::FETCH_LAZY: ");
154
-
print("Return next row as an anonymous object with column names as properties\n");
174
+
print "PDO::FETCH_LAZY: ";
175
+
print "Return next row as a PDORow object with column names as properties\n";
155
176
$result = $sth->fetch(PDO::FETCH_LAZY);
156
177
print_r($result);
157
-
print("\n");
178
+
print "\n";
158
179

159
-
print("PDO::FETCH_OBJ: ");
160
-
print("Return next row as an anonymous object with column names as properties\n");
180
+
print "PDO::FETCH_OBJ: ";
181
+
print "Return next row as an anonymous object with column names as properties\n";
161
182
$result = $sth->fetch(PDO::FETCH_OBJ);
162
-
print $result->NAME;
163
-
print("\n");
183
+
print $result->name;
184
+
print "\n";
164
185
?>
165
186
]]>
166
187
</programlisting>
...
...
@@ -170,24 +191,24 @@ print("\n");
170
191
PDO::FETCH_ASSOC: Return next row as an array indexed by column name
171
192
Array
172
193
(
173
-
[NAME] => apple
174
-
[COLOUR] => red
194
+
[name] => apple
195
+
[colour] => red
175
196
)
176
197

177
198
PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
178
199
Array
179
200
(
180
-
[NAME] => banana
201
+
[name] => banana
181
202
[0] => banana
182
-
[COLOUR] => yellow
203
+
[colour] => yellow
183
204
[1] => yellow
184
205
)
185
206

186
-
PDO::FETCH_LAZY: Return next row as an anonymous object with column names as properties
207
+
PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
187
208
PDORow Object
188
209
(
189
-
[NAME] => orange
190
-
[COLOUR] => orange
210
+
[name] => orange
211
+
[colour] => orange
191
212
)
192
213

193
214
PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
...
...
@@ -200,35 +221,23 @@ kiwi
200
221
<![CDATA[
201
222
<?php
202
223
function readDataForwards($dbh) {
203
-
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
204
-
try {
224
+
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
205
225
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
206
226
$stmt->execute();
207
227
while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
208
-
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
209
-
print $data;
228
+
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
229
+
print $data;
210
230
}
211
-
$stmt = null;
212
-
}
213
-
catch (PDOException $e) {
214
-
print $e->getMessage();
215
-
}
216
231
}
217
232
function readDataBackwards($dbh) {
218
-
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
219
-
try {
233
+
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
220
234
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
221
235
$stmt->execute();
222
236
$row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
223
237
do {
224
-
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
225
-
print $data;
238
+
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
239
+
print $data;
226
240
} while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
227
-
$stmt = null;
228
-
}
229
-
catch (PDOException $e) {
230
-
print $e->getMessage();
231
-
}
232
241
}
233
242

234
243
print "Reading forwards:\n";
...
...
@@ -255,6 +264,56 @@ Reading backwards:
255
264
</screen>
256
265
</example>
257
266

267
+
<example><title>Construction order</title>
268
+
<simpara>
269
+
When objects are fetched via <literal>PDO::FETCH_CLASS</literal> the object
270
+
properties are assigned first, and then the constructor of the class is
271
+
invoked. If <literal>PDO::FETCH_PROPS_LATE</literal> is also given, this
272
+
order is reversed, i.e. first the constructor is called, and afterwards the
273
+
properties are assigned.
274
+
</simpara>
275
+
<programlisting role="php">
276
+
<![CDATA[
277
+
<?php
278
+
class Person
279
+
{
280
+
private $name;
281
+

282
+
public function __construct()
283
+
{
284
+
$this->tell();
285
+
}
286
+

287
+
public function tell()
288
+
{
289
+
if (isset($this->name)) {
290
+
echo "I am {$this->name}.\n";
291
+
} else {
292
+
echo "I don't have a name yet.\n";
293
+
}
294
+
}
295
+
}
296
+

297
+
$sth = $dbh->query("SELECT * FROM people");
298
+
$sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
299
+
$person = $sth->fetch();
300
+
$person->tell();
301
+
$sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
302
+
$person = $sth->fetch();
303
+
$person->tell();
304
+
?>
305
+
]]>
306
+
</programlisting>
307
+
&example.outputs.similar;
308
+
<screen>
309
+
<![CDATA[
310
+
I am Alice.
311
+
I am Alice.
312
+
I don't have a name yet.
313
+
I am Bob.
314
+
]]>
315
+
</screen>
316
+
</example>
258
317
</para>
259
318
</refsect1>
260
319

...
...
@@ -262,17 +321,16 @@ Reading backwards:
262
321
&reftitle.seealso;
263
322
<para>
264
323
<simplelist>
265
-
<member><function>PDO::prepare</function></member>
266
-
<member><function>PDOStatement::execute</function></member>
267
-
<member><function>PDOStatement::fetchAll</function></member>
268
-
<member><function>PDOStatement::fetchColumn</function></member>
269
-
<member><function>PDOStatement::fetchObject</function></member>
270
-
<member><function>PDOStatement::setFetchMode</function></member>
324
+
<member><methodname>PDO::prepare</methodname></member>
325
+
<member><methodname>PDOStatement::execute</methodname></member>
326
+
<member><methodname>PDOStatement::fetchAll</methodname></member>
327
+
<member><methodname>PDOStatement::fetchColumn</methodname></member>
328
+
<member><methodname>PDOStatement::fetchObject</methodname></member>
329
+
<member><methodname>PDOStatement::setFetchMode</methodname></member>
271
330
</simplelist>
272
331
</para>
273
332
</refsect1>
274
333
</refentry>
275
-

276
334
<!-- Keep this comment at the end of the file
277
335
Local variables:
278
336
mode: sgml
279
337