reference/pdo/pdostatement/fetch.xml
a8863b0123dc5348c91e67198b995222878a7e65
...
...
@@ -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,16 +48,23 @@
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
-
requested class, mapping the columns of the result set to named
57
-
properties in the class. If <parameter>fetch_style</parameter>
58
-
includes PDO::FETCH_CLASSTYPE (e.g. <literal>PDO::FETCH_CLASS |
59
-
PDO::FETCH_CLASSTYPE</literal>) then the name of the class is
60
-
determined from a value of the first column.
56
+
requested class. The object is initialized by mapping the columns of
57
+
the result set to properties in the class. This occurs before the
58
+
constructor is called, allowing properties to be populated regardless
59
+
of their visibility or whether they are marked as <literal>readonly</literal>.
60
+
If a property does not exist in the class, the magic <link linkend="object.set">__set()</link>
61
+
method will be invoked if it exists; otherwise, a dynamic public
62
+
property will be created. However, when <constant>PDO::FETCH_PROPS_LATE</constant>
63
+
is also given, the constructor is called <emphasis>before</emphasis>
64
+
the properties are populated. If <parameter>mode</parameter> includes
65
+
<constant>PDO::FETCH_CLASSTYPE</constant> (e.g.
66
+
<literal>PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE</literal>), the name
67
+
of the class is determined from the value of the first column.
61
68
</para></listitem>
62
69
<listitem><para>
63
70
<literal>PDO::FETCH_INTO</literal>: updates an existing instance
...
...
@@ -67,7 +74,15 @@
67
74
<listitem><para>
68
75
<literal>PDO::FETCH_LAZY</literal>: combines
69
76
<literal>PDO::FETCH_BOTH</literal> and <literal>PDO::FETCH_OBJ</literal>,
70
-
creating the object variable names as they are accessed
77
+
and is returning a <classname>PDORow</classname> object
78
+
which is creating the object property names as they are accessed.
79
+
</para></listitem>
80
+
<listitem><para>
81
+
<literal>PDO::FETCH_NAMED</literal>: returns an array with the same
82
+
form as <literal>PDO::FETCH_ASSOC</literal>, except that if there are
83
+
multiple columns with the same name, the value referred to by that
84
+
key will be an array of all the values in the row that had that
85
+
column name
71
86
</para></listitem>
72
87
<listitem><para>
73
88
<literal>PDO::FETCH_NUM</literal>: returns an array indexed by column
...
...
@@ -78,12 +93,18 @@
78
93
property names that correspond to the column names returned in your
79
94
result set
80
95
</para></listitem>
96
+
<listitem><para>
97
+
<literal>PDO::FETCH_PROPS_LATE</literal>: when used with
98
+
<literal>PDO::FETCH_CLASS</literal>, the constructor of the class is
99
+
called before the properties are assigned from the respective column
100
+
values.
101
+
</para></listitem>
81
102
</itemizedlist>
82
103
</para>
83
104
</listitem>
84
105
</varlistentry>
85
106
<varlistentry>
86
-
<term><parameter>cursor_orientation</parameter></term>
107
+
<term><parameter>cursorOrientation</parameter></term>
87
108
<listitem>
88
109
<para>
89
110
For a PDOStatement object representing a scrollable cursor, this
...
...
@@ -93,25 +114,25 @@
93
114
scrollable cursor for your PDOStatement object, you must set the
94
115
<literal>PDO::ATTR_CURSOR</literal> attribute to
95
116
<literal>PDO::CURSOR_SCROLL</literal> when you prepare the SQL
96
-
statement with <function>PDO::prepare</function>.
117
+
statement with <methodname>PDO::prepare</methodname>.
97
118
</para>
98
119
</listitem>
99
120
</varlistentry>
100
121
<varlistentry>
101
-
<term><parameter>offset</parameter></term>
122
+
<term><parameter>cursorOffset</parameter></term>
102
123
<listitem>
103
124
<para>
104
125
For a PDOStatement object representing a scrollable cursor for which
105
-
the <literal>cursor_orientation</literal> parameter is set to
126
+
the <parameter>cursorOrientation</parameter> parameter is set to
106
127
<literal>PDO::FETCH_ORI_ABS</literal>, this value specifies the
107
128
absolute number of the row in the result set that shall be fetched.
108
129
</para>
109
130
<para>
110
131
For a PDOStatement object representing a scrollable cursor for which
111
-
the <literal>cursor_orientation</literal> parameter is set to
132
+
the <parameter>cursorOrientation</parameter> parameter is set to
112
133
<literal>PDO::FETCH_ORI_REL</literal>, this value specifies the
113
134
row to fetch relative to the cursor position before
114
-
<function>PDOStatement::fetch</function> was called.
135
+
<methodname>PDOStatement::fetch</methodname> was called.
115
136
</para>
116
137
</listitem>
117
138
</varlistentry>
...
...
@@ -123,10 +144,15 @@
123
144
&reftitle.returnvalues;
124
145
<para>
125
146
The return value of this function on success depends on the fetch type. In
126
-
all cases, &false; is returned on failure.
147
+
all cases, &false; is returned on failure or if there are no more rows.
127
148
</para>
128
149
</refsect1>
129
150

151
+
<refsect1 role="errors">
152
+
&reftitle.errors;
153
+
&pdo.errors;
154
+
</refsect1>
155
+

130
156
<refsect1 role="examples">
131
157
&reftitle.examples;
132
158
<para>
...
...
@@ -138,29 +164,29 @@ $sth = $dbh->prepare("SELECT name, colour FROM fruit");
138
164
$sth->execute();
139
165

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

147
-
print("PDO::FETCH_BOTH: ");
148
-
print("Return next row as an array indexed by both column name and number\n");
173
+
print "PDO::FETCH_BOTH: ";
174
+
print "Return next row as an array indexed by both column name and number\n";
149
175
$result = $sth->fetch(PDO::FETCH_BOTH);
150
176
print_r($result);
151
-
print("\n");
177
+
print "\n";
152
178

153
-
print("PDO::FETCH_LAZY: ");
154
-
print("Return next row as an anonymous object with column names as properties\n");
179
+
print "PDO::FETCH_LAZY: ";
180
+
print "Return next row as a PDORow object with column names as properties\n";
155
181
$result = $sth->fetch(PDO::FETCH_LAZY);
156
182
print_r($result);
157
-
print("\n");
183
+
print "\n";
158
184

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

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

186
-
PDO::FETCH_LAZY: Return next row as an anonymous object with column names as properties
212
+
PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
187
213
PDORow Object
188
214
(
189
-
[NAME] => orange
190
-
[COLOUR] => orange
215
+
[name] => orange
216
+
[colour] => orange
191
217
)
192
218

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

234
248
print "Reading forwards:\n";
...
...
@@ -255,6 +269,56 @@ Reading backwards:
255
269
</screen>
256
270
</example>
257
271

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

287
+
public function __construct()
288
+
{
289
+
$this->tell();
290
+
}
291
+

292
+
public function tell()
293
+
{
294
+
if (isset($this->name)) {
295
+
echo "I am {$this->name}.\n";
296
+
} else {
297
+
echo "I don't have a name yet.\n";
298
+
}
299
+
}
300
+
}
301
+

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

...
...
@@ -262,17 +326,16 @@ Reading backwards:
262
326
&reftitle.seealso;
263
327
<para>
264
328
<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>
329
+
<member><methodname>PDO::prepare</methodname></member>
330
+
<member><methodname>PDOStatement::execute</methodname></member>
331
+
<member><methodname>PDOStatement::fetchAll</methodname></member>
332
+
<member><methodname>PDOStatement::fetchColumn</methodname></member>
333
+
<member><methodname>PDOStatement::fetchObject</methodname></member>
334
+
<member><methodname>PDOStatement::setFetchMode</methodname></member>
271
335
</simplelist>
272
336
</para>
273
337
</refsect1>
274
338
</refentry>
275
-

276
339
<!-- Keep this comment at the end of the file
277
340
Local variables:
278
341
mode: sgml
279
342



Translation status